matrix_bgpsim

class matrix_bgpsim.RMatrix(input_rels, excluded=None)[source]

Bases: object

class BranchRoute(root, next_hop, length, branch_id)[source]

Bases: NamedTuple

branch_id: int

Alias for field number 3

length: int

Alias for field number 2

next_hop: str

Alias for field number 1

root: str

Alias for field number 0

C2P: int = 1
P2C: int = -1
P2P: int = 0
class RelMap(P2P, C2P, P2C)[source]

Bases: NamedTuple

C2P: int

Alias for field number 1

P2C: int

Alias for field number 2

P2P: int

Alias for field number 0

asn2brts(asn)[source]

Return branch route details for a branch ASN.

Return type:

BranchRoute

asn2idx(asn)[source]

Return the index of a core ASN.

Return type:

int

static caida_reader(fpath)[source]

Parse a CAIDA-formatted AS relationship file and yield tuples.

Parameters:

fpath (Union[str, Path]) – Path to the CAIDA relationship file.

Yields:

Tuple[str, str, int] – asn1, asn2, and relationship type (RMatrix.P2C, P2P, C2P) for each AS pair.

Return type:

Iterator[Tuple[str, str, int]]

static construct_topology(input_rels, excluded=None)[source]

Build the AS-level topology, returning core/branch mappings.

Parameters:

  • input_rels (Union[str, Path, Iterable[Tuple[str, str, int]]]) – Path to a CAIDA file or iterable of (asn1, asn2, rel) tuples.

  • excluded (Union[Callable[[str], bool], Iterable[str], Set[str], Dict[str, Any], None]) – ASNs to exclude. Can be: - None (no exclusion) - Iterable[str] (list, tuple, set, etc.) - Mapping[str, Any] (membership checked via in) - Callable[[str], bool]: returns True if ASN should be excluded

Returns:

  • idx2asn: List of core ASNs by index

  • asn2idx: Dict from ASN to core index

  • idx2ngbrs: Core AS neighbors as RMatrix.RelMap

  • asn2brts: Dict from branch ASN to RMatrix.BranchRoute

Return type:

tuple

dump(fpath)[source]

Serialize and save the current RMatrix object to a lz4 file.

Return type:

None

get_path(asn1, asn2)[source]

Retrieve the AS-level path from asn1 to asn2.

Important caveats:

  • Simulation (run(save_next_hop=True)) must have been executed before calling this method, otherwise an AssertionError is raised.

  • If no route exists between asn1 and asn2, returns None.

  • If asn1 == asn2, returns an empty list [] because no hops are needed.

Parameters:

  • asn1 (str) – Source ASN.

  • asn2 (str) – Destination ASN.

Return type:

Optional[List[str]]

Returns:

  • A list of ASNs forming the path from asn1 to asn2 (excluding asn1, including asn2).

  • [] if asn1 == asn2.

  • None if no path exists.

get_state(asn1, asn2)[source]

Get the route priority and path length between two ASNs.

Important caveats:

  • Simulation (run()) must have been executed before calling this method, otherwise an AssertionError is raised.

  • If the route from asn1 to asn1 does not exist, the result is (None, 0).

  • If asn1 == asn2, the type defaults to P2C and length is 0.

Parameters:

  • asn1 (str) – Source ASN.

  • asn2 (str) – Destination ASN.

Returns:

  • s_type: Relationship type (P2C, P2P, C2P) or None if unreachable.

  • s_len: Path length (0 if unreachable or same ASN).

Return type:

tuple

has_asn(asn)[source]

Check if an ASN exists in the topology (core or branch).

Return type:

bool

idx2asn(idx)[source]

Return the ASN corresponding to a given core AS index.

Return type:

str

idx2ngbrs(idx)[source]

Return neighbors of a core AS (as RMatrix.RelMap).

Return type:

RelMap

is_branch_asn(asn)[source]

Check if an ASN belongs to a branch.

Return type:

bool

is_core_asn(asn)[source]

Check if an ASN belongs to the core network.

Return type:

bool

static load(fpath)[source]

Load an RMatrix object from a serialized lz4 file.

Return type:

RMatrix

run(n_jobs=1, max_iter=32, save_next_hop=True, backend='cpu', device=None)[source]

Run the routing simulation.

Parameters:

  • n_jobs (int) – Number of parallel processes (CPU only).

  • max_iter (int) – Maximum number of iterations.

  • save_next_hop (bool) – Whether to compute next-hop matrix.

  • backend (str) – One of {“cpu”, “torch”, “cupy”}. - “cpu”: Default, uses NumPy + multiprocessing. - “torch”: GPU/CPU acceleration via PyTorch (requires pip install matrix-bgpsim[torch]). - “cupy”: GPU acceleration via CuPy (requires pip install matrix-bgpsim[cupy]).

  • device (Union[str, int, None]) – Device specifier for GPU backends (e.g., “cuda:0”, “cpu”). Ignored for CPU backend. Defaults: - torch: Uses “cuda:0” if available, else “cpu”. - cupy: Uses first available CUDA device.

Return type:

None