topohub.providers

The providers package contains topology generators for multiple data sources and synthetic models.

topohub.providers.gabriel

Gabriel graph synthetic topology providers.

Provides two generators (pure Python and NumPy-based) that create planar Gabriel graphs for benchmarking and research. Node positions are 2D planar coordinates (not geographic lon/lat).

class GabrielGenerator

Bases: TopoGenerator

Generator of Gabriel graph synthetic topologies.

E. K. Çetinkaya, M. J. F. Alenazi, Y. Cheng, A. M. Peck and J. P. G. Sterbenz, On the fitness of geographic graph generators for modelling physical level topologies. 2013 5th International Congress on Ultra Modern Telecommunications and Control Systems and Workshops (ICUMT), Almaty, Kazakhstan, 2013, pp. 38-45. https://doi.org/10.1109/ICUMT.2013.6798402.

K. Ruben Gabriel, Robert R. Sokal, A New Statistical Approach to Geographic Variation Analysis. Systematic Biology, Volume 18, Issue 3, September 1969, Pages 259-278. https://doi.org/10.2307/2412323

classmethod generate_topo(nnodes, seed, **kwargs) → dict

Generate Gabriel graph topology with a given number of nodes.

Parameters:

  • nnodes (int) – Number of nodes.

  • seed (int) – Random seed.

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

Topology graph in NetworkX node-link format. Node positions are 2D planar coordinates (not geographic lon/lat).

Return type:

dict

class NumpyGabrielGenerator

Bases: TopoGenerator

Generator of Gabriel graph synthetic topologies based on NumPy.

E. K. Çetinkaya, M. J. F. Alenazi, Y. Cheng, A. M. Peck and J. P. G. Sterbenz, On the fitness of geographic graph generators for modelling physical level topologies. 2013 5th International Congress on Ultra Modern Telecommunications and Control Systems and Workshops (ICUMT), Almaty, Kazakhstan, 2013, pp. 38-45. https://doi.org/10.1109/ICUMT.2013.6798402.

K. Ruben Gabriel, Robert R. Sokal, A New Statistical Approach to Geographic Variation Analysis. Systematic Biology, Volume 18, Issue 3, September 1969, Pages 259-278. https://doi.org/10.2307/2412323

classmethod generate_topo(nnodes, seed, **kwargs) → dict

Generate a Gabriel graph topology with a given number of nodes.

Parameters:

  • nnodes (int) – number of nodes

  • seed (int) – random seed

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

topology graph in NetworkX node-link format

Return type:

dict

topohub.providers.sndlib

SNDlib topology provider.

Downloads native SNDlib topologies and converts them to NetworkX node-link format. Node positions are stored as (longitude, latitude) tuples.

class SNDlibGenerator

Bases: TopoGenerator

Generator of topologies from the SNDlib.

Source of data: https://sndlib.put.poznan.pl

Orlowski, S., Wessäly, R., Pióro, M. and Tomaszewski, A. (2010), SNDlib 1.0—Survivable Network Design Library. Networks, 55: 276-286. https://doi.org/10.1002/net.20371

classmethod download_topo(name) → bytes

Download a native SNDlib topology text file by name.

Parameters:

name (str) – Topology identifier as used in SNDlib native filenames.

Returns:

Raw file contents.

Return type:

bytes

classmethod generate_topo(name, **kwargs) → dict

Download topology specified by name from SNDlib and generate its JSON.

Parameters:

  • name (str) – topology name

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

topology graph in NetworkX node-link format

Return type:

dict

topohub.providers.topozoo

Internet Topology Zoo provider.

Downloads GML topologies from the Internet Topology Zoo and converts them to NetworkX node-link format. Node positions are stored as (longitude, latitude) tuples when available in the GML.

class TopoZooGenerator

Bases: TopoGenerator

Generator of topologies from the Internet Topology Zoo.

Source of data: https://topology-zoo.org/

S. Knight, H. X. Nguyen, N. Falkner, R. Bowden and M. Roughan, The Internet Topology Zoo. IEEE Journal on Selected Areas in Communications, vol. 29, no. 9, pp. 1765-1775. https://doi.org/10.1109/JSAC.2011.111002

classmethod download_topo(name) → bytes

Download a GML topology file by name from the Internet Topology Zoo.

Parameters:

name (str) – Topology name (as used by Topology Zoo filenames).

Returns:

Raw GML file contents.

Return type:

bytes

classmethod generate_topo(name, **kwargs) → dict

Download topology specified by name from Topology Zoo and generate its JSON.

Parameters:

  • name (str) – topology name

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

topology graph in NetworkX node-link format

Return type:

dict

topohub.providers.backbone

Backbone synthetic topology provider.

Generates synthetic backbone-style topologies from TopoGen JSON definitions. Node positions are stored as (longitude, latitude) tuples.

class BackboneGenerator

Bases: TopoGenerator

Generator of backbone synthetic topologies.

https://doi.org/10.1109/ICC.2015.7249292 https://www.sciencedirect.com/science/article/pii/S2352711023002364

classmethod generate_topo(name, **kwargs) → dict

Generate the specified backbone topology.

Parameters:

  • name (str) – Topology key identifying the region, e.g., ‘africa’ or ‘africa_nosc’.

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

Topology graph in NetworkX node-link format. Node positions are stored as (lon, lat) tuples.

Return type:

dict

topohub.providers.caida

CAIDA topology provider.

Parses CAIDA Ark datasets to build ASN-specific undirected graphs. Node positions are stored as (longitude, latitude) tuples. Includes optional geo-filtering and node merging by identical or close positions.

class CaidaGenerator

Bases: TopoGenerator

Generator of CAIDA topologies.

https://publicdata.caida.org/datasets/topology/ark/

classmethod generate_topo(name, distance_km=None, include_countries=None, include_continents=None, exclude_countries=None, mainland_only=False, **kwargs) → dict

Generate a CAIDA ASN topology in NetworkX node-link format.

Parameters:

  • name (str) – ASN identifier (as string or number).

  • distance_km (float | None, default None) – Merge nodes within this distance (kilometers) after grouping by identical coordinates.

  • include_countries (list[str] | None) – Country names to include.

  • include_continents (list[str] | None) – Continent names to include (supports ‘EU’ expansion).

  • exclude_countries (list[str] | None) – Country names to exclude.

  • mainland_only (bool, default False) – If True, reduce countries to their mainland polygons during filtering.

  • **kwargs (dict) – Additional options reserved for future use (currently unused).

Returns:

topology graph in NetworkX node-link format

Return type:

dict

graph(asn, distance_km=None, include_countries=None, include_continents=None, exclude_countries=None, mainland_only=False)

Build an ASN-specific undirected graph from CAIDA data.

Nodes are assigned positions as (lon, lat) tuples and optional city names. Optionally, nodes at the same or nearby coordinates can be merged to reduce clutter, and nodes can be filtered by geographic regions.

Parameters:

  • asn (int | str) – Target ASN to extract.

  • distance_km (float | None, default None) – Merge nodes within this geographic distance after exact-position grouping.

  • include_countries (list[str] | None) – Country names to include.

  • include_continents (list[str] | None) – Continent names to include (supports ‘EU’ expansion in geo module).

  • exclude_countries (list[str] | None) – Country names to exclude.

  • mainland_only (bool, default False) – If True, reduce countries to their mainland polygons during filtering.

Returns:

(nodes, edges) for building a NetworkX node-link graph. Each node has ‘pos’: (lon, lat) and optional ‘name’ attributes. Each edge has ‘source’, ‘target’, and ‘dist’ (km).

Return type:

tuple[dict[int, dict], list[dict]]

merge_nodes_by_pos(selected_with_pos, adjacency, distance_km=None)

Merge nodes that share the same coordinates or are within a threshold distance.

Representative selection rules within each group: 1) Among nodes which have a city name, select a node whose city name is most common; 2) If all city names occur equally often, select the lowest node id among named nodes; 3) If there are no nodes with names, select the lowest node id.

If distance_km is provided, a second pass merges groups whose representatives are within the given distance (in kilometers), using the same selection rules on the combined group.

Parameters:

  • selected_with_pos (dict[int, (float, float, str)]) – Mapping from node id to (lon, lat, city) for nodes selected for the graph.

  • adjacency (dict[int, set[int]]) – Undirected adjacency list of nodes.

  • distance_km (float | None, default None) – If None, merge nodes only with the exact same (lon, lat). If provided, also merge nodes whose haversine distance is <= distance_km.

Returns:

positions remain as (lon, lat) tuples.

Return type:

tuple[dict[int, (float, float, str)], dict[int, set[int]]]

Parse undirected adjacency from the CAIDA links file.

Parameters:

  • path (str) – Path to midar-iff.links file.

  • nodes (Iterable[int] | None, default None) – If provided, include links only among this node subset.

  • grep (bool, default True) – Use external grep to speed up filtering for large files.

Returns:

Undirected adjacency list (both directions present).

Return type:

dict[int, set[int]]

parse_nodes_as(path, asn=None, grep=True)

Parse CAIDA node-to-ASN mappings.

Parameters:

  • path (str) – Path to the midar-iff.nodes.as file.

  • asn (int | None, default None) – If provided, filter to a specific ASN.

  • grep (bool, default True) – Use external grep to speed up filtering for large files.

Returns:

Mapping ASN -> set of node IDs.

Return type:

dict[int, set[int]]

parse_nodes_geo(path, nodes=None, grep=True)

Parse CAIDA node geolocation data.

Parameters:

  • path (str) – Path to the midar-iff.nodes.geo file.

  • nodes (Iterable[int] | None, default None) – If provided, limit parsing to these node IDs.

  • grep (bool, default True) – Use external grep to speed up filtering for large files.

Returns:

Mapping node ID -> tuple of fields (as provided by CAIDA). Consumers should extract city, latitude, longitude and convert to floats as needed.

Return type:

dict[int, tuple[str, …]]