planning Module

planning Module#

This module provides the planning and optimization core for the SixGman framework.

Module Overview#

Its primary responsibilities include:

  • Integrating network topology (nodes, links, hierarchical levels) with multi-band optical transmission.

  • Performing traffic-aware and spectrum-aware network planning for metro and urban transport networks.

  • Supporting multi-band coexistence by coordinating multiple optical bands (e.g., C, L, S) for transmission.

  • Providing a time-based planning window for iterative or dynamic network optimization.

  • Serving as a controller that coordinates modules from:

    • network.py → Topology and hierarchy modeling

    • band.py → Optical band definition and physical parameters

Key Class#

PlanningTool#

class sixgman.core.planning.PlanningTool(network_instance, bands, optical_parameters, grid_center, period_time=10)#

Bases: object

Main class for SixGman planning and optimization.

This tool integrates physical layer modeling with hierarchical network topology and supports multi-band optical transmission planning. It is intended for use in optical metro and urban transport networks where spectral efficiency, topology hierarchy, and multi-band coexistence are jointly considered.

network#

A reference to the network topology object that contains all node, link, and hierarchical information used for planning.

Type:

Network

bands#

A list of Band instances, each representing an optical band (e.g., C, L, S) with its spectral and physical transmission parameters.

Type:

List[Band]

period_time#

The time period (in arbitrary units) over which traffic demand aggregation or optimization planning is conducted.

Type:

int

__init__(network_instance, bands, optical_parameters, grid_center, period_time=10)#

Initialize the PlanningTool object with a given network topology and bands.

Args:#

network_instance (Network): The network structure including nodes, links,

weights, and hierarchical levels.

bands (List[Band]): The optical bands considered for transmission planning.

Each Band includes start/end frequencies and physical layer parameters.

optical_parameters (dict):

Dictionary containing the optical transmision parameters.

grid_center (np.ndarray):

Numpy array containing the center frequency of frequency channels.

period_time (int, optional): Time granularity (e.g., 10 units) for periodic

traffic updates or recalculation windows. Default is 10.

Example:#

>>> from sixgman.core.planning import PlanningTool

>>> # Initialize planning tool
>>> planner = PlanningTool(
...     network_instance = net, # the network instance
...     bands = [c_band], # list of all band instances
...     optical_parameters = c_band_params, # optical transmission parameters
...     grid_center = f_c_axis, # center frequncy of frequency channels
...     period_time = 10 # the time period for planning (e.g., 10 years)
... )
initialize_planner(num_fslots, hierarchy_level, minimum_hierarchy_level, rolloff=0.1, SR=40000000000.0, Max_bit_rate_BVT=array([400, 348, 280, 200, 120, 80]), Ref_license_capacity=array([100, 87, 70, 50, 30, 20]), FP_max_num=20, band_sepration_idx=[96, 120])#

Initialize planning-related matrices and spectrum parameters.

This method prepares internal state variables needed for simulating BVT allocations, GSNR calculations, fiber placement tracking, and spectrum usage planning across different optical bands.

Args:#

num_fslots (int):

Number of frequency slots available in the network.

hierarchy_level (int):

Target hierarchy level for current planning.

minimum_hierarchy_level (int):

Minimum hierarchy level for subgraph planning.

rolloff (float):

Rolloff factor for spectral shaping (default: 0.1).

SR (float):

Symbol rate in baud (default: 40 Gbaud).

Max_bit_rate_BVT (np.ndarray):

Array of supported BVT bitrates in Gbps.

Ref_license_capacity (np.ndarray):

Array of reference license capacities of different BVT bitrates.

FP_max_num (int):

Maximum number of available fiber pairs per link.

band_sepration_idx (list):

Index of the last frequency slot of the C-Band and SuperC-Band.

Example:#

>>> planner.initialize_planner(
...     num_fslots = num_fslots, # number of frequency slots
...     hierarchy_level = 4, # current hierarchy level
...     minimum_hierarchy_level = 4 # minimum hierarchy levels
...     rolloff = 0.1,
...     SR = 64e9, 64 Gbaud symbol rate for 75GHz channel spacing
...     Max_bit_rate_BVT = np.array([400, 320, 260, 200, 120, 64]),
...     Ref_license_capacity = np.array([100, 80, 65, 50, 30, 16]),
...     FP_max_num = 100 # 100 fiber pairs is available for assignment,
...     band_sepration_idx = [64, 80], # 64 and 80 are the last FS of C-Band and SuperC-Band
... )
generate_initial_traffic_profile(num_nodes, optical_nodes, monteCarlo_steps, min_rate, max_rate, seed, result_directory)#

Generate or load the initial traffic capacity profile for network nodes using Monte Carlo simulation.

This method estimates the initial traffic demand or capacity for each network node by performing multiple Monte Carlo simulations. For each iteration, it generates random capacities uniformly distributed between the specified minimum and maximum rates. If a precomputed capacity file exists in the given directory, it is loaded instead to avoid redundant computation.

The resulting per-node average capacities are stored internally in self.HL_capacity_final. This method does not return any value.

Args:#

num_nodes (int):

Number of nodes in the network for which to simulate traffic.

optical_nodes (list):

List of all nodes with no electrical aggregation (optically bypass nodes), these nodes not have any initial traffic and can’t be the destination of any node

monteCarlo_steps (int):

Number of Monte Carlo iterations used for averaging.

min_rate (float):

Minimum possible traffic rate (Gbps) per node.

max_rate (float):

Maximum possible traffic rate (Gbps) per node.

seed (int):

Initial random seed for reproducibility of the simulations.

result_directory (Path):

Directory where results are stored or loaded from.

Updates:#

self.HL_capacity_final (np.ndarray):

Final per-node traffic capacity values averaged over all Monte Carlo simulations.

Output:#

None

Example:#

>>> # generate port capacity for the lowest HL nodes uisng Monte Carlo simulation
>>> planner.generate_initial_traffic_profile(
...     num_nodes = len(HL4_all), # all the nodes of minimum hierarchy level
...     Optical_nodes = [], # there is no any all optical node
...     monteCarlo_steps = 100, # Number of Monte Carlo iterations
...     min_rate = 20, # minimum allowed traffic rate per node in Gbps
...     max_rate = 200, # maximum allowed traffic rate per node in Gbps
...     seed = 20, # random seed for reproducibility
...     result_directory = results_dir # Path to the directory where results are stored
... )
simulate_traffic_annual(lowest_hierarchy_dict, CAGR, result_directory)#

Simulate annual traffic evolution for the lowest hierarchy-level nodes using a Compound Annual Growth Rate (CAGR).

This method models how network traffic grows over multiple years at the lowest hierarchy level (e.g., HL4) by applying a constant annual growth rate to each node’s base capacity. It calculates annual traffic, added traffic, number of 100G licenses, and residual capacities for both standalone and colocated nodes.

If precomputed results are available in the specified directory, they are loaded from file to save computation time. Otherwise, the full annual simulation is performed and results are saved.

Args:#

lowest_hierarchy_dict (dict):

Dictionary containing node IDs for the lowest hierarchy level, with keys ‘standalone’ and ‘colocated’.

CAGR (float):

Compound Annual Growth Rate (e.g., 0.4 for 40% annual increase).

result_directory (Path):

Directory where results are read from or written to.

Updates:#

self.lowest_HL_added_traffic_annual_standalone (np.ndarray):

Annual incremental traffic for standalone nodes (years × nodes).

self.lowest_HL_added_traffic_annual_colocated (np.ndarray):

Annual incremental traffic for colocated nodes (years × nodes).

Output:#

None

Example:#

>>> # Traffic growth simulation over 10 years
>>> planner.simulate_traffic_annual(
...     lowest_hierarchy_dict = hl_dict['HL4'], # Dictionary with minimum hierarchy level standalone and colocated nodes
...     CAGR = 0.4, # 40% annual growth rate
...     result_directory = results_dir # Path to the directory where results are stored
...)
run_planner(hierarchy_level, prev_hierarchy_level, pairs_disjoint, kpair_standalone, kpair_colocated, candidate_paths_standalone_df, candidate_paths_colocated_df, GSNR_opt_link, Nspan_array, all_node_degree, P_opt_links, minimum_level, node_cap_update_idx, result_directory)#

Executes the hierarchical optical network planning algorithm for a given hierarchy level.

This function performs traffic allocation, spectrum assignment, and resource planning for both standalone and colocated High-Level (HL) nodes across multiple years. It computes primary and secondary paths, assigns BVTs (Bandwidth Variable Transceivers), updates frequency plans (FPs), tracks GSNR (Generalized Signal-to-Noise Ratio) evolution, and saves annual network performance results.

The planner operates iteratively per year and per HL node, handling:

  • Traffic growth and residual throughput updates

  • Spectrum assignment via _spectrum_assignment()

  • BVT count and license tracking

  • Frequency Plan (FP) and link utilization updates

  • GSNR computation and aggregation over simulation years

  • Capacity profile updates for source and destination nodes

Args:#

hierarchy_level (int):

The current hierarchy level being processed.

prev_hierarchy_level (int):

The previous hierarchy level used for continuity and reference.

pairs_disjoint (pd.DataFrame):

DataFrame containing disjoint node pairs for routing and path computation.

kpair_standalone (int):

Maximum number of LAND pairs to consider for standalone HL nodes.

kpair_colocated (int):

Maximum number of K-shortest paths to consider for colocated HL nodes (secondary path).

candidate_paths_standalone_df (pd.DataFrame):

DataFrame of candidate paths for standalone HL pairs, including metrics like hops.

candidate_paths_colocated_df (pd.DataFrame):

DataFrame of candidate paths for colocated HL pairs, used for colocated spectrum assignment.

GSNR_opt_link (np.ndarray):

Array of per-link GSNR (Generalized Signal-to-Noise Ratio) values.

Nspan_array (np.ndarray):

Array that contains number of spans per link in the whole network.

all_node_degree (np.ndarray):

Initial node degress for WSS penalty calculation.

minimum_level (int):

Minimum hierarchy level considered in the network for FP continuity and reference.

node_cap_update_idx (int):

Index in the node capacity array that determines where new capacity values are stored.

result_directory (Path or str):

Directory path where annual and summary results are saved.

Updates:#

self.Residual_Throughput_BVT_standalone_HLs_primary (np.ndarray):

Residual unallocated throughput for primary paths of standalone nodes.

self.Residual_Throughput_BVT_standalone_HLs_secondary (np.ndarray):

Residual unallocated throughput for secondary paths of standalone nodes.

self.Residual_Throughput_BVT_colocated_HLs_primary (np.ndarray):

Residual unallocated throughput for primary paths of colocated nodes.

self.Residual_Throughput_BVT_colocated_HLs_secondary (np.ndarray):

Residual unallocated throughput for secondary paths of colocated nodes.

self.Year_FP (np.ndarray):

Number of fiber pairs in different years for network links.

self.Year_FP_HL_colocated (np.ndarray):

Number of fiber pairs in years in-site links.

self.Year_FP_new (np.ndarray):

Number of fiber pairs in different years for network links based on spectrum assignment.

self.Total_effective_FP_new_annual (np.ndarray):

Total km of fiber pair usage across all links per year.

self.GSNR_BVT_all_annual (np.ndarray):

GSNR records of all BVTs (primary and secondary) per year.

self.GSNR_BVT_primary_annual (np.ndarray):

GSNR records of primary BVTs per year.

self.GSNR_BVT_secondary_annual (np.ndarray):

GSNR records of secondary BVTs per year.

self.node_capacity_profile_array (np.ndarray):

Node capacity evolution per year, including allocations and residual capacities.

self.traffic_flow_links_array (np.ndarray):

Annual traffic volume per network link.

self.num_100G_licence_annual (np.ndarray):

Annual count of activated 100G licenses.

self.num_100G_licence_CBand_annual (np.ndarray):

Annual count of activated 100G licenses in C-Band.

self.num_100G_licence_superCBand_annual (np.ndarray):

Annual count of activated 100G licenses in SuperC-Band.

self.num_100G_licence_LBand_annual (np.ndarray):

Annual count of activated 100G licenses in L-Band.

self.Residual_Throughput_LC_standalone_HLs_primary (np.ndarray):

Residual capacity of the last activated licenses (primary path) per standalone node.

self.Residual_Throughput_LC_standalone_HLs_secondary (np.ndarray):

Residual capacity of the last activated licenses (secondary path) per standalone node.

self.Residual_Throughput_LC_colocated_HLs_primary (np.ndarray):

Residual capacity of the last activated licenses (primary path) per colocated node.

self.Residual_Throughput_LC_colocated_HLs_secondary (np.ndarray):

Residual capacity of the last activated licenses (secondary path) per colocated node.

self.LAND_Links_Storage (np.ndarray):

Links of selected LAND pair for each node.

self.LSP_array (np.ndarray):

Link-State-Profile array that show the occupied frequency slots in different fiber pairs.

self.LSP_array_Colocated (np.ndarray):

Link-State-Profile array that show the occupied frequency slots in different fiber pairs for primary colocated paths.

self.path_latency_storage (list):

Latency records for primary and secondary paths.

self.destinations_storage (list):

Destination node records for primary and secondary paths.

self.num_link_CBand_annual (np.ndarray):

Number of fiber pairs with at least one allocated C-Band FS in each link per year.

self.num_link_SupCBand_annual (np.ndarray):

Number of fiber pairs with at least one allocated SuperC-Band FS in each link per year.

self.num_link_LBand_annual (np.ndarray):

Number of fiber pairs with at least one allocated L-Band FS in each link per year.

Output:#

None

Example:#

>>> planner.run_planner(hierarchy_level = 4, # Current hierarchy level
...         prev_hierarchy_level = 3, # Previous hierarchy level
...         pairs_disjoint = pairs_disjoint, # DataFrame of disjoint LAND pairs
...         kpair_standalone = 1, # Maximum Number of K-shortest paths for standalone HL nodes
...         kpair_colocated = 1, # Maximum Number of K-shortest paths for colocated HL nodes
...         candidate_paths_standalone_df = K_path_attributes_df, # DataFrame of candidate paths for standalone HL nodes
...         candidate_paths_colocated_df = K_path_attributes_colocated_df, # DataFrame of candidate paths for colocated HL nodes
...         GSNR_opt_link = GSNR_opt_link, # GSNR values for each link in this hierarchy level
...         Nspan_array = np.ones(len(all_links)), # number of spans for each link in the whole network
...         P_opt_links = opt_power_links, # Optimum power values for each link
...         minimum_level = 4, # Minimum hierarchy level
...         node_cap_update_idx = 2, # Index of node capacity vector to update
...         result_directory = results_dir # Directory to save results
... )

Key Methods#

  • ``run_planner(hierarchy_level, prev_hierarchy_level, pairs_disjoint, kpair_standalone, kpair_colocated, candidate_paths_standalone_df, candidate_paths_colocated_df, GSNR_opt_link, minimum_level, node_cap_update_idx, result_directory)`` Executes the hierarchical planning algorithm for the given hierarchy level.