network Module

network Module#

The network module provides tools for modeling optical network topologies, loading them from different file formats, and preparing the data for planning and simulation in the SixGman toolkit.

Module Overview#

This module is responsible for:

  • Representing an optical network topology using NetworkX graphs.

  • Loading adjacency matrices from .mat, .npz, or .npy files.

  • Set the hierarchy level of different nodes in the network.

  • Compute k-shortest paths between source and destination nodes using Yen’s algorithm.

  • Identify link- and node-disjoint path pairs (LAND pairs) for each source node.

Key Class#

Network#

class sixgman.core.network.Network(topology_name)#

Bases: object

A class representing an optical network topology and its properties.

This class handles the network topology, hierarchical levels, and path computation for the SixGman planning tool.

graph#

NetworkX graph representing the network topology graph.

Type:

nx.Graph

hierarchical_levels#

Dictionary containing nodes organized by hierarchical level.

Type:

Dict[str, Dict[str, List[str]]]

topology_name#

Name of the network topology.

Type:

str

__init__(topology_name)#

Initialize a Network instance.

Args:#

topology_name (str):

Name of the network topology.

Example

>>> from sixgman.core.network import Network
>>> net = Network("ExampleNetwork")
load_topology(filepath, matrixName=None)#

Load network topology from .mat, .npz, or .npy file.

This function reads an adjacency matrix from a file, converts it to a NetworkX graph, and initializes related network attributes.

Supported formats:#

.mat :

MATLAB file (requires matrixName to specify the variable)

.npz :

NumPy compressed archive (variable name required)

.npy :

NumPy single-array file

Args:#

filepath (str):

Path to the file containing network topology.

matrixName (str):

Name of the adjacency matrix variable in .mat or .npz files.

Output:#

nx.Graph: A NetworkX graph representing the loaded network topology.

Raises:#

FileNotFoundError:

If the file does not exist.

ValueError:

If the adjacency matrix is empty or invalid.

KeyError:

If the specified matrixName does not exist in the file.

IOError:

If there is an error loading the file or parsing the matrix.

Example

>>> net.load_topology("path/to/topology.mat", matrixName="adjacency_matrix")
define_hierarchy(**kwargs)#

Set the hierarchical levels of nodes in the network.

This method allows flexible assignment of nodes to hierarchical levels (HL1, HL2, …) with optional standalone and colocated classifications.

Behavior:#

  • Accepts keyword arguments like HL1_standalone, HL2_colocated, etc.

  • standalone nodes are unique to that level.

  • colocated nodes are shared with previous levels if not explicitly given.

  • If a _colocated list is not provided, it is auto-accumulated from all previous standalone nodes.

Args:#

**kwargs:

Variable keyword arguments for HLx_standalone and HLx_colocated.

Output:#

Dict[str, Dict[str, List[str]]]:

Updated hierarchical levels structure.

Example

>>> HL_dict = net.define_hierarchy(
...     HL3_standalone = [1, 2, 3],
...     HL4_standalone = [4, 5, 6, 7],
...     HL4_colocated = [1]
... )

>>> HL4_Standalone = hl_dict['HL4']['standalone']
>>> HL4_colocated = hl_dict['HL4']['colocated']
>>> HL4_all = np.concatenate((HL4_Standalone, HL4_colocated))
get_standalone_hierarchy_level(node)#

Returns the standalone hierarchical level (HL1, HL2, etc) of the given node. If the node is not found in any standalone level, returns None.

Args:#

node:

The index of the node for which the standalone hierarchical level is to be determined.

Output:#

Integer representing the standalone hierarchical level of the input node (e.g., 2 for HL2).

compute_hierarchy_subgraph(hierarchy_level, minimum_hierarchy_level)#

Extract a subgraph from the network based on hierarchical constraints.

Constructs a subgraph that includes edges where at least one endpoint is in the specified hierarchy level (HLx), and the other is not in any lower level between HL(x+1) and HL(minimum).

Args:#

hierarchy_level (int):

The current HL level (e.g., 1 for HL1).

minimum_hierarchy_level (int):

The lowest HL level to exclude from edge participation.

Output:#

Tuple[nx.Graph, np.ndarray]:

  • The resulting NetworkX subgraph.

  • The subgraph’s adjacency (cost) matrix with np.inf for missing links.

Example

>>> subgraph, subnetMatrix = net.compute_hierarchy_subgraph(
...     hierarchy_level = 4, # Current hierarchy level
...     minimum_hierarchy_level = 4 # Minimum hierarchy level to include in analysis
... )
get_neighbor_nodes(nodes)#

Return the unique neighbors of a given list of nodes in the graph.

This excludes the input nodes themselves. Each neighbor appears only once regardless of how many input nodes it is connected to.

Args:#

nodes (List[int]):

List of node IDs.

Output:#

List[int]:

Sorted list of unique neighbor node IDs.

Example

>>> neighbors_HL4 = net.get_neighbor_nodes(HL4_standalone)
compute_k_shortest_paths(subnet_matrix, paths, source, target, k=20)#

Compute k-shortest paths between source and target nodes using Yen’s algorithm.

This function computes candidate paths for optical network planning, calculates distances, and updates the paths list with detailed path information.

Args:#

subnet_matrix (np.ndarray):

Adjacency matrix of the subnet.

paths (List[Dict]):

List to append path dictionaries to (can be empty initially).

source (int):

Source node ID.

target (int):

Target node ID.

k (int, optional):

Number of paths to compute (default: 20).

Output:#

List[Dict]:
Updated list of paths, where each dictionary contains:

  • src_node (int): Source node

  • dest_node (int): Destination node

  • nodes (List[int]): Sequence of nodes in the path

  • links (List[int]): Link indices forming the path

  • distance (float): Total path distance

  • num_hops (int): Number of hops in the path

Example

>>> src_nodes = HL4_standalone
>>> target_nodes = neighbors_HL4
>>> k_paths = 20

>>> # Define a list to store path attributes
>>> K_path_attributes = []
>>> # Iterate through each standalone HL4 node
>>> for src in src_nodes:
...     for dest in target_nodes:
...         K_path_attributes = net.compute_k_shortest_paths(
...             subnetMatrix,
...             K_path_attributes,
...             source = src,
...             target = dest,
...             k = k_paths
...         )
>>> # Convert to dataframe
>>> K_path_attributes_df = pd.DataFrame(K_path_attributes)
get_node_degrees(nodes)#

Get the degree of specified nodes in the graph.

This method returns a dictionary where each key is a node ID, and each value is the degree of the corresponding node (the number of edges connected to it).

Args:#

nodes (List[int]):

List of node IDs for which to retrieve the degree.

Output:#

np.ndarray:

2D numpy array containing node IDs and their relative degree.

land_pair_finder(src_list, candidate_paths_sorted, num_pairs)#

Identify link- and node-disjoint path pairs (LAND pairs) for each source node.

A LAND pair consists of a primary and secondary path where: - They connect different destination nodes. - They are node-disjoint (except the source). - They are link-disjoint.

Return type:

DataFrame

Args:#

src_list (List[int]):

List of source node IDs to process.

candidate_paths_sorted (pd.DataFrame):

DataFrame of candidate paths. Must include columns: [‘src_node’, ‘dest_node’, ‘nodes’, ‘links’, ‘index’, ‘distance’, ‘num_hops’].

num_pairs (int):

Maximum number of disjoint pairs to return per source node.

Output:#

pd.DataFrame:

DataFrame with columns: [‘primary_path_IDx’, ‘secondary_path_IDx’, ‘numHops_secondary’, ‘distance_secondary’, ‘src_node’]

Example

>>> # Sort the candidate paths by number of hops and distance
>>> K_path_attributes_df_sorted = K_path_attributes_df.groupby(
...     ['src_node'], group_keys = False).apply(
...         lambda x: x.sort_values(['num_hops', 'distance'])
...     )

>>> # Find 1 disjoint pairs for each source node
>>> pairs_disjoint = net.land_pair_finder(
...     src_nodes,
...     K_path_attributes_df_sorted,
...     num_pairs = 1
... )
calc_num_pair(pairs_disjoint_df)#

calculate the number of candidate link & node disjoint (LAND) pairs.

Args:#

pairs_disjoint_df:

Dataframe of disjoint_pairs

Output:#

A numpy array containing the number of candidate LAND pairs for each source node

Key Methods#

  • ``__init__(topology_name)`` Initializes the network with a given name and hierarchical structure.

  • ``load_topology(filepath, matrixName=None)`` Loads the adjacency matrix from a file and converts it to a NetworkX graph. Supports .mat, .npz, and .npy formats.

  • ``define_hierarchy(filepath, matrixName=None)`` Set the hierarchical levels of nodes in the network.

  • ``compute_k_shortest_paths(subnet_matrix, paths, source, target, k=20)`` Compute k-shortest paths between source and target nodes using Yen’s algorithm.

  • ``land_pair_finder(src_list, candidate_paths_sorted, num_pairs)`` Identify link- and node-disjoint path pairs (LAND pairs) for each source node.