Geodesics

Graph-to-graph distances using curvature filtrations. Pick your curvature; get a distance matrix back.

Curvatures

  • forman_curvature (fast)

  • balanced_forman_curvature

  • resistance_curvature

  • ollivier_ricci_curvature (most detailed, slowest)

API

thema.multiverse.universe.geodesics.stellar_curvature_distance(files: str | list, filterfunction: Callable | None = None, curvature='forman_curvature', vectorization='landscape')[source]

Compute a pairwise distance matrix between graphs using curvature filtrations.

Parameters:

  • files (str or list[str]) – Either a path to a directory containing starGraph files or a list of individual file paths.

  • filterfunction (Callable, optional) – A custom filter function to select a subset of cosmic graphs. Defaults to None.

  • curvature (str, optional) –

    The curvature measure to use. Defaults to “forman_curvature”.

    Supported values (increasing in complexity and computational intensity):
    • ”forman_curvature” :

      A combinatorial measure based purely on local graph structure. Fast to compute and suitable for large graphs or exploratory analysis.

    • ”balanced_forman_curvature” :

      A refinement of Forman curvature that balances edge contributions, improving sensitivity to degree heterogeneity while remaining efficient.

    • ”resistance_curvature” :

      Derived from effective resistance distances between nodes. Captures global connectivity patterns but is more computationally demanding.

    • ”ollivier_ricci_curvature” :

      A transport-based curvature measure that reflects the geometry of probabilistic mass movement between node neighborhoods. Provides the most geometric insight but is the slowest to compute.

    For further details, see: https://github.com/aidos-lab/curvature-filtrations/blob/main/notebooks/bagpipeline.ipynb

  • vectorization (str, optional) – Vectorization method for computing distances. Defaults to “landscape”.

Returns:

  • keys (np.ndarray) – Array of keys identifying the models being compared.

  • distance_matrix (np.ndarray) – Pairwise distance matrix between the persistence landscapes of the starGraphs.