DOCSEARCHbyAlgolia
Submit Docs

TopoNetX: Computing on Topological Domains

repository·main·Indexed 42 days ago

https://github.com/pyt-team/toponetx

A unified platform for computing with topological domains, including simplicial complexes, cell complexes, and combinatorial complexes. TopoNetX extends NetworkX to support higher-order mathematical structures, allowing for the computation of boundary operators, Hodge Laplacians, and higher-order adjacency operators. It includes tools for transforming graphs into complexes, generating random topological domains, and performing signal processing via its algorithms module.

Tokens
8.4K
Snippets
28
Records
39
Agent score
53%

What's inside TopoNetX

  1. Overview of TopoNetX modules

    main

    TopoNetX is organized into several functional modules that allow you to work with various topological domains:

    • classes: Core implementation of topological domains, including SimplicialComplex, CellComplex, and CombinatorialComplex.
    • datasets: Utilities for loading small, standard datasets onto topological domains.
    • transform: Functions for transforming topological domains, specifically used for "lifting" a dataset onto a different domain.
    • algorithms: Signal processing techniques and mathematical operations on topological domains (e.g., eigendecomposition of a Laplacian).
    • generators: Functions to generate random topological domains.
    • readwrite: Tools for reading from and writing topological domains to disk.

  2. Overview of TopoNetX functionality

    main

    TopoNetX is a Python package designed for computing on topological domains, which represent the relational structures between components in a dataset (e.g., social networks, protein interactions).

    It extends the capabilities of NetworkX by supporting higher-order mathematical structures including:

    • Cell Complexes (CellComplex)
    • Simplicial Complexes (SimplicialComplex)
    • Combinatorial Complexes (CombinatorialComplex)

    Key capabilities include dynamic construction (adding/removing objects after creation), attaching arbitrary attributes to entities, and computing topological properties such as boundary operators, Hodge Laplacians, and higher-order adjacency operators. It is also compatible with NetworkX and gudhi.

  3. Understand TopoNetX Complexes

    main

    Complexes are the primary data structures used to organize and manage collections of atoms. They define the topological relationships between elements. Available complex types include:

    • toponetx.Complex: The base class for all topological complexes.
    • toponetx.SimplicialComplex: A complex composed of simplices.
    • toponetx.PathComplex: A complex structured around paths.
    • toponetx.CellComplex: A complex composed of cells of various dimensions.
    • toponetx.CombinatorialComplex: A complex defined by combinatorial properties.
    • toponetx.ColoredHyperGraph: A hypergraph where edges or nodes may have assigned colors/labels.

  4. Understand TopoNetX Atoms

    main

    Atoms are the fundamental building blocks in TopoNetX. They represent the basic topological elements used to construct more complex structures. The core atom types include:

    • toponetx.Atom: The base class for all atomic elements.
    • toponetx.Simplex: Represents a simplex (e.g., vertices, edges, triangles in a simplicial complex).
    • toponetx.Path: Represents a sequence of connected elements.
    • toponetx.Cell: Represents a cell in a cell complex.
    • toponetx.HyperEdge: Represents an edge in a hypergraph that can connect more than two nodes.

  5. Use TopoNetX Report Views

    main

    Report Views provide specialized interfaces for inspecting and accessing the data within a complex. They allow you to view the complex through different lenses (e.g., focusing on nodes, simplices, or hyperedges). Common view types include:

    • toponetx.NodeView
    • toponetx.AtomView
    • toponetx.SimplexView
    • toponetx.PathView
    • toponetx.CellView
    • toponetx.HyperEdgeView
    • toponetx.ColoredHyperEdgeView

  6. Supported topological complex types

    main

    TopoNetX provides three primary classes for modeling higher-order networks:

    1. CellComplex: Used for modeling cell complexes.
    2. SimplicialComplex: Used for modeling simplicial complexes.
    3. CombinatorialComplex: Used for modeling combinatorial complexes.

    Each of these classes provides specific methods for computing boundary operators, Hodge Laplacians, and higher-order adjacency operators relevant to that specific mathematical structure.

  11. How to contribute to TopoNetX

    main

    The preferred way to contribute is to fork the upstream repository and submit a pull request (PR).

    Follow these steps:

    1. Synchronize: Ensure your main branch is up to date with the upstream repository.
    2. Branch: Create a new feature branch for your changes.
    3. Develop: Implement changes, including appropriate unit tests and documentation.
    4. Commit & Push: Add your changes with git add, commit them, and push to your fork.
    5. PR: Create a pull request from your fork on GitHub.
    $ git checkout main
$ git pull upstream main
$ git checkout -b <branch-name>
$ git add <modified_files>
$ git commit -m "Add my feature"
$ git push origin <branch-name>

  12. Write documentation using NumPy docstring style

    main

    TopoNetX uses the NumPy docstring standard for all functions, classes, and modules. This is required for automated API Reference generation.

    Docstring Anatomy

    • Summary: A one-line description (under 79 chars) starting with a capital letter and ending with a period. For functions, use the imperative mood (e.g., Compute instead of Computes).
    • Description: A multi-line informative description separated from the summary by a blank line.
    • Parameters: A list of arguments including name, type, and shape. Format: name : type, shape=[...]. For optional parameters, include Optional, default: value. on a new line.
    • Returns: A list of returned objects with type and description, following the same syntax as Parameters.
    • Optional Sections: Use Raises, See Also, Notes (supports LaTeX via :math:), Examples, and References as needed.

    Formatting Rules

    • Use built-in Python types (e.g., bool instead of boolean).
    • Use [ and ] for defining shapes: array-like, shape=[..., dim].
    • For multiple string options, use curly braces: input: str, {"log", "squared"}.
    • Use array-like to include lists, while ndarray refers specifically to numpy.ndarray.
    def my_method(self, my_param_1, my_param_2="vector"):
   r"""Write a one-line summary for the method.

   Write a description of the method, including "big O"
   (:math:`O\left(g\left(n\right)\right)`) complexities.

   Parameters
   ----------
   my_param_1 : array-like, shape=[..., dim]
      Write a short description of parameter my_param_1.
   my_param_2 : str, {"vector", "matrix"}
      Write a short description of parameter my_param_2.
      Optional, default: "vector".

   Returns
   -------
   my_result : array-like, shape=[..., dim, dim]
      Write a short description of the result returned by the method.

   Notes
   -----
   If relevant, provide equations with (:math:) 
   describing computations performed in the method.

   Examples
   --------
   Provide code snippets showing how the method is used.

   Reference
   ---------
   If relevant, provide a reference with associated pdf or
   wikipedia page.
   """
   pass