Source code for eclypse.builders.infrastructure.references.topohub.gabriel

"""Synthetic Gabriel-graph reference infrastructures.

The Gabriel family models synthetic long-haul and optical-style backbone
topologies generated by TopoHub with controlled graph size and reproducible
samples. These graphs include node coordinates, link distances, and ECMP load
metadata, making them useful as scalable WAN references with realistic
distance-driven QoS properties.

Example:
    .. code-block:: python

        get_gabriel(25, sample=2, **kwargs)

Source:
    Jurkiewicz, "TopoHub: A repository of reference Gabriel graph and
    real-world topologies for networking research", SoftwareX 2023,
    https://doi.org/10.1016/j.softx.2023.101540
"""

from __future__ import annotations

from typing import TYPE_CHECKING

from ._helpers import get_topohub

if TYPE_CHECKING:
    from collections.abc import Callable

    import networkx as nx

    from eclypse.graph import Infrastructure
    from eclypse.graph.assets import Asset
    from eclypse.utils.types import (
        InitPolicy,
        UpdatePolicies,
    )




def get_gabriel(
    size: int,
    sample: int = 0,
    infrastructure_id: str | None = None,
    update_policies: UpdatePolicies = None,
    node_assets: dict[str, Asset] | None = None,
    link_assets: dict[str, Asset] | None = None,
    include_default_assets: bool = False,
    resource_init: InitPolicy = "max",
    path_algorithm: Callable[[nx.Graph, str, str], list[str]] | None = None,
    seed: int | None = None,
) -> Infrastructure:
    """Create a Gabriel-graph infrastructure from TopoHub.

    The ``size`` and ``sample`` values must correspond to a valid topology in
    `TopoHub <https://www.topohub.org>`_'s ``gabriel`` family catalogue.

    Args:
        size (int):
            Number of nodes requested from the Gabriel family.
        sample (int):
            Reproducible sample index for the chosen size.
        infrastructure_id (str | None):
            Identifier assigned to the infrastructure. If omitted, a dataset-based
            identifier is used.
        update_policies (UpdatePolicies):
            Graph update policies executed during ``evolve()``.
        node_assets (dict[str, Asset] | None):
            Node asset definitions available to the infrastructure.
        link_assets (dict[str, Asset] | None):
            Edge asset definitions available to the infrastructure.
        include_default_assets (bool):
            Whether to include default ECLYPSE assets.
        resource_init (InitPolicy):
            Initialisation policy used for graph assets.
        path_algorithm (Callable[[nx.Graph, str, str], list[str]] | None):
            Path computation function for infrastructure routing.
        seed (int | None):
            Seed forwarded to the infrastructure random generator.

    Returns:
        Infrastructure: The converted Gabriel infrastructure.
    """
    dataset_path = f"gabriel/{size}/{sample}"
    default_id = f"gabriel_{size}_{sample}"
    return get_topohub(
        topology=dataset_path,
        infrastructure_id=infrastructure_id or default_id,
        use_names=False,
        update_policies=update_policies,
        node_assets=node_assets,
        link_assets=link_assets,
        include_default_assets=include_default_assets,
        resource_init=resource_init,
        path_algorithm=path_algorithm,
        seed=seed,
    )



__all__ = ["get_gabriel"]