gnpy.core

Simulation of signal propagation in the DWDM network

Optical signals, as defined via info.SpectralInformation, enter elements which compute how these signals are affected as they travel through the network. The simulation is controlled via parameters and implemented mainly via science_utils.

gnpy.core.ansi_escapes

A random subset of ANSI terminal escape codes for colored messages

gnpy.core.elements

Standard network elements which propagate optical spectrum.

A network element is a Python callable. It takes a info.SpectralInformation object and returns a copy with appropriate fields affected. This structure represents spectral information that is “propagated” by this network element. Network elements must have only a local “view” of the network and propagate info.SpectralInformation using only this information. They should be independent and self-contained.

Network elements MUST implement two attributes uid and name representing a unique identifier and a printable name, and provide the __call__() method taking a SpectralInformation as an input and returning another SpectralInformation instance as a result.

class gnpy.core.elements.Edfa(*args, params=None, operational=None, **kwargs)

Bases: _Node

Class representing an Erbium-Doped Fiber Amplifier (EDFA).

This class models the behavior of an EDFA, including its parameters, operational characteristics, and methods for propagation of spectral information.

Variables:

  • variety_list (Union[List[str], None]) – A list of type_variety associated with the amplifier.

  • interpol_dgt (numpy.ndarray) – Interpolated dynamic gain tilt defined per frequency on the amplifier band.

  • interpol_gain_ripple (numpy.ndarray) – Interpolated gain ripple.

  • interpol_nf_ripple (numpy.ndarray) – Interpolated noise figure ripple.

  • channel_freq (numpy.ndarray) – SI channel frequencies.

  • nf (numpy.ndarray) – Noise figure in dB at the operational gain target.

  • gprofile (numpy.ndarray) – Gain profile of the amplifier.

  • pin_db (float) – Input power in dBm.

  • nch (int) – Number of channels.

  • pout_db (float) – Output power in dBm.

  • target_pch_out_dbm (float) – Target output power per channel in dBm.

  • effective_pch_out_db (float) – Effective output power per channel in dBm.

  • passive (bool) – Indicates if the fiber is passive.

  • att_in (float) – Input attenuation in dB.

  • effective_gain (float) – Effective gain of the amplifier.

  • delta_p (float) – Delta power defined by the operational parameters.

  • _delta_p (float) – Computed delta power during design.

  • tilt_target (float) – Target tilt defined per wavelength on the amplifier band.

  • out_voa (float) – Output variable optical attenuator setting.

  • in_voa (float) – Input variable optical attenuator setting.

  • propagated_labels (numpy.ndarray) – Labels propagated by the amplifier.

Raises:

  • ParametersError – If there are conflicting amplifier definitions for the same frequency band during initialization.

  • ValueError – If the input spectral information does not match any defined amplifier bands during propagation.

_calc_nf(avg=False)

nf calculation based on 2 models: self.params.nf_model.enabled from json import: True => 2 stages amp modelling based on precalculated nf1, nf2 and delta_p in build_OA_json False => polynomial fit based on self.params.nf_fit_coeff

_gain_profile(pin, err_tolerance=1e-11, simple_opt=True)

Pin : input power / channel in W

Parameters:

  • gain_ripple (numpy.ndarray) – design flat gain

  • dgt (numpy.ndarray) – design gain tilt

  • Pin (numpy.ndarray) – total input power in W

  • gp (float) – Average gain setpoint in dB units (provisioned gain)

  • gtp (float) – gain tilt setting (provisioned tilt)

Returns:

gain profile in dBm, per channel or spectral slice

Return type:

numpy.ndarray

Checking of output power clamping is implemented in interpol_params().

Based on:

R. di Muro, “The Er3+ fiber gain coefficient derived from a dynamic gain tilt technique”, Journal of Lightwave Technology, Vol. 18, Iss. 3, Pp. 343-347, 2000.

Ported from Matlab version written by David Boerges at Ciena.

_nf(type_def, nf_model, nf_fit_coeff, gain_min, gain_flatmax, gain_target)
interpol_params(spectral_info)

interpolate SI channel frequencies with the edfa dgt and gain_ripple frquencies from JSON

Parameters:

spectral_info (SpectralInformation) – The spectral information object.

noise_profile(spectral_info: SpectralInformation)

Computes amplifier ASE noise integrated over the signal bandwidth. This is calculated at amplifier input.

Returns:

the ASE power in W in the signal bandwidth bw for 96 channels

Return type:

numpy.ndarray

ASE power using per channel gain profile inputs:

NF_dB - Noise figure in dB, vector of length number of channels or

spectral slices

G_dB - Actual gain calculated for the EDFA, vector of length number of

channels or spectral slices

ffs - Center frequency grid of the channels or spectral slices in

THz, vector of length number of channels or spectral slices

dF - width of each channel or spectral slice in THz,

vector of length number of channels or spectral slices

OUTPUT:

ase_dBm - ase in dBm per channel or spectral slice

NOTE:

The output is the total ASE in the channel or spectral slice. For 50GHz channels the ASE BW is effectively 0.4nm. To get to noise power in 0.1nm, subtract 6dB.

ONSR is usually quoted as channel power divided by the ASE power in 0.1nm RBW, regardless of the width of the actual channel. This is a historical convention from the days when optical signals were much smaller (155Mbps, 2.5Gbps, … 10Gbps) than the resolution of the OSAs that were used to measure spectral power which were set to 0.1nm resolution for convenience. Moving forward into flexible grid and high baud rate signals, it may be convenient to begin quoting power spectral density in the same BW for both signal and ASE, e.g. 12.5GHz.

propagate(spectral_info)

add ASE noise to the propagating carriers of info.SpectralInformation

Parameters:

spectral_info (SpectralInformation) – The spectral information object.

property to_json

Converts the Edfa’s state to a JSON-compatible dictionary. Adapts the json export: scalar or vector.

Return Dict[str, Any]:

JSON representation of the Edfa.

class gnpy.core.elements.Fiber(*args, params=None, **kwargs)

Bases: _Node

Represents an optical fiber element in the network.

Variables:

  • pch_out_db (float) – Output power per channel in dBm.

  • passive (bool) – Indicates if the fiber is passive.

  • propagated_labels (List[str]) – Labels propagated by the fiber.

alpha(frequency)

Returns the linear exponent attenuation coefficient such that :math: lin_attenuation = e^{- alpha length}

Parameters:

frequency – the frequency at which alpha is computed [Hz]

Returns:

alpha: power attenuation coefficient for f in frequency [Neper/m]

beta2(frequency=None)

Returns the beta2 chromatic dispersion coefficient as the second order term of the beta function expanded as a Taylor series evaluated at the given frequency

Parameters:

frequency – the frequency at which alpha is computed [Hz]

Returns:

beta2: beta2 chromatic dispersion coefficient for f in frequency # 1/(m * Hz^2)

beta3(frequency=None)

Returns the beta3 chromatic dispersion coefficient as the third order term of the beta function expanded as a Taylor series evaluated at the given frequency

Parameters:

frequency – the frequency at which alpha is computed [Hz]

Returns:

beta3: beta3 chromatic dispersion coefficient for f in frequency # 1/(m * Hz^3)

chromatic_dispersion(freq=None)

Returns accumulated chromatic dispersion (CD).

Parameters:

freq – the frequency at which the chromatic dispersion is computed

Returns:

chromatic dispersion: the accumulated dispersion [s/m]

cr(frequency)

Returns the raman gain coefficient matrix including the vibrational loss

Parameters:

frequency – the frequency at which cr is computed [Hz]

Returns:

cr: raman gain coefficient matrix [1 / (W m)]

gamma(frequency=None)

Returns the nonlinear interference coefficient such that :math: gamma(f) = 2 pi f n_2 c^{-1} A_{eff}^{-1}

Parameters:

frequency – the frequency at which gamma is computed [Hz]

Returns:

gamma: nonlinear interference coefficient for f in frequency [1/(W m)]

interpolate_parameter_over_spectrum(parameter, ref_frequency, spectrum_frequency, name)

Interpolates loss coefficient value given the input frequency.

Parameters:

  • (ndarray) (spectrum_frequency) – The parameter to interpolate.

  • (ndarray) – Reference frequencies.

  • (ndarray) – Frequencies of the spectrum.

  • (str) (name) – Name of the parameter for error messages.

Return ndarray:

Interpolated values.

property loss

total loss including padding att_in: useful for polymorphism with roadm loss

Return float:

Total loss in dB.

loss_coef_func(frequency)

Returns the loss coefficient (of a fibre) which can be uniform, or made frequency-dependent defined via a dictionnary-model per instance in the topology-file, or via a list-model (‘LUT’) in the equipment-file.

If a list-model is declared, then the legacy ‘loss_coef’ scalar is used to offset the provided LUT-model for the given self.params.ref_frequency’ such that at the ‘self.params.ref_frequency’ the offset model values the ‘loss_coef’ scalar; in case the ‘loss_coef’ scalar is not defined then no offset is applied.

In case a dictionary-model as well as a list-model are declared, then the legacy dictionary-based model has priority.

Parameters:

ndarray]) (frequency (Union[float,) – Frequency at which to compute the loss coefficient.

Return ndarray:

Loss coefficient values.

property pmd

differential group delay (PMD) [s]

propagate(spectral_info: SpectralInformation)

Modifies the spectral information computing the attenuation, the non-linear interference generation, the CD and PMD accumulation.

property to_json

Converts the fiber’s state to a JSON-compatible dictionary. Adapts the json export: scalar or vector.

Return Dict[str, Any]:

JSON representation of the fiber.

class gnpy.core.elements.Fused(*args, params=None, **kwargs)

Bases: _Node

Represents a fused optical element in the network.

Variables:

  • (float) (loss) – Loss experienced by the fused element.

  • (bool) (passive) – Indicates if the fused element is passive.

propagate(spectral_info)

Applies loss to the spectral information.

Parameters:

spectral_info (SpectralInformation) – The spectral information object.

property to_json

Converts the fused element’s state to a JSON-compatible dictionary.

Return Dict[str, Any]:

JSON representation of the fused element.

class gnpy.core.elements.Location(latitude: float = 0, longitude: float = 0, city: str = None, region: str = None)

Bases: Location

Represents a geographical location with latitude, longitude, city, and region.

class gnpy.core.elements.Multiband_amplifier(*args, amplifiers: List[dict], params: dict, **kwargs)

Bases: _Node

Represents a multiband amplifier that manages multiple amplifiers across different frequency bands.

This class allows for the initialization and management of amplifiers, each associated with a specific frequency band. It provides methods for signal propagation through the amplifiers and for exporting to JSON format.

Parameters:

  • amplifiers (List[Dict]) – list of dictionaries, each containing parameters for setting an individual amplifier.

  • params (Dict) – dictionary of parameters for the multiband amplifier, which must include necessary configuration settings.

  • args – Additional positional and keyword arguments passed to the parent class _Node.

  • kwargs – Additional positional and keyword arguments passed to the parent class _Node.

Variables:

  • variety_list (list) – A list of varieties associated with the amplifier.

  • amplifiers (dict) – A dictionary mapping band names to their corresponding amplifier instances.

Raises:

  • ParametersError – If there are conflicting amplifier definitions for the same frequency band during initialization.

  • ValueError – If the input spectral information does not match any defined amplifier bands during propagation.

property to_json

Converts the MultibandAmplifier’s state to a JSON-compatible dictionary.

Return Dict[str, Any]:

JSON representation of the MultibandAmplifier.

class gnpy.core.elements.RamanFiber(*args, params=None, **kwargs)

Bases: Fiber

Class representing a Raman fiber in a network.

Inherits from the Fiber class and adds specific parameters and methods for Raman amplification.

Variables:

  • raman_pumps (Tuple[PumpParams]) – A tuple of pump parameters for the Raman amplification.

  • temperature (float) – The operational temperature of the Raman fiber.

Raises:

NetworkTopologyError – If the fiber is defined as a RamanFiber without operational parameters, or if required operational parameters are missing.

propagate(spectral_info: SpectralInformation)

Modifies the spectral information computing the attenuation, the non-linear interference generation, the CD and PMD accumulation.

property to_json

Converts the RamanFiber’s state to a JSON-compatible dictionary. Adapts the json export: scalar or vector.

Return Dict[str, Any]:

JSON representation of the RamanFiber.

class gnpy.core.elements.Roadm(*args, params=None, **kwargs)

Bases: _Node

Represents a Reconfigurable Optical Add-Drop Multiplexer (ROADM).

Variables:

  • ref_pch_out_dbm (float) – Reference output power in dBm.

  • loss (float) – Total loss experienced by the ROADM.

  • loss_pch_db (numpy.ndarray) – Loss per channel in dB.

  • ref_effective_loss (float) – Effective loss for a reference carrier.

  • passive (bool) – True, indicates that the ROADM is passive.

  • restrictions (dict) – Restrictions on the ROADM.

  • propagated_labels (numpy.ndarray[str]) – Labels propagated by the ROADM.

  • target_pch_out_dbm (float) – Target output power in dBm.

  • target_psd_out_mWperGHz (float) – Target PSD output in mW/GHz.

  • target_out_mWperSlotWidth (float) – Target output power per slot width.

  • per_degree_pch_out_dbm (Dict[str, float]) – Per degree target output power.

  • per_degree_pch_psd (Dict[str, float]) – Per degree target PSD output.

  • per_degree_pch_psw (Dict[str, float]) – Per degree target output per slot width.

  • ref_pch_in_dbm (Dict[str, float]) – Reference input power in dBm.

  • ref_carrier (ReferenceCarrier) – Reference carrier.

  • roadm_paths (Dict[str, Any]) – Internal paths for the ROADM.

  • roadm_path_impairments (Dict) – Impairment profiles for the ROADM paths.

  • per_degree_impairments (Dict[str, Any]) – Per degree impairments.

  • design_bands (List[Dict]) – Design bands parameters.

  • per_degree_design_bands (Dict[str, Dict]) – Per degree design bands parameters.

get_impairment(impairment: str, frequency_array: array, from_degree: str, degree: str) → array

Retrieves the specified impairment values for the given frequency array.

Parameters:

  • impairment (str) – The type of impairment to retrieve (e.g., roadm-pmd, roadm-maxloss).

  • frequency_array (numpy.ndarray) – The frequencies at which to check for impairments.

  • from_degree (str) – The ingress degree for the ROADM internal path.

  • degree (str) – The egress degree for the ROADM internal path.

Return array:

An array of impairment values for the specified frequencies.

get_path_type_per_id(impairment_id: int) → str | None

returns the path_type of the impairment if the id is defined

Parameters:

impairment_id (int) – The impairment ID.

Return Union[str, None]:

The path type or None if not found.

get_per_degree_impairment_id(from_degree: str, to_degree: str) → int | None

returns the id of the impairment if the degrees are in the per_degree tab.

Parameters:

  • from_degree (str) – The ingress degree.

  • to_degree (str) – The egress degree.

Return Union[int, None]:

The impairment ID or None if not found.

get_per_degree_power(degree, spectral_info)

Get the target power in dBm out of ROADM degree for the spectral information If no equalization is defined on this degree use the ROADM level one.

Parameters:

  • degree (str) – The degree identifier.

  • spectral_info (SpectralInformation) – The spectral information object.

Return float:

Target power in dBm.

get_per_degree_ref_power(degree)

Get the target power in dBm out of ROADM degree for the reference bandwidth If no equalization is defined on this degree use the ROADM level one.

Parameters:

degree (str) – The degree identifier.

Return float:

Target power in dBm

get_roadm_path(from_degree: str, to_degree: str)

Get internal path type impairment.

Parameters:

  • from_degree (str) – The ingress degree.

  • to_degree (str) – The egress degree.

Return Any:

The roadm path object.

get_roadm_target_power(spectral_info: SpectralInformation = None) → float | ndarray

Computes the power in dBm for a reference carrier or for a spectral information. power is computed based on equalization target. if spectral_info baud_rate is baud_rate = [32e9, 42e9, 64e9, 42e9, 32e9], and target_pch_out_dbm is defined to -20 dbm, then the function returns an array of powers [-20, -20, -20, -20, -20] if target_psd_out_mWperGHz is defined instead with 3.125e-4mW/GHz then it returns [-20, -18.819, -16.9897, -18.819, -20] if instead a reference_baud_rate is defined, the functions computes the result for a single reference carrier whose baud_rate is reference_baudrate.

Parameters:

spectral_info (SpectralInformation, optional) – The spectral information object.

Returns:

Target power in dBm.

Return type:

Union[float, ndarray]

propagate(spectral_info, degree, from_degree)

Equalization targets are read from topology file if defined and completed with default definition of the library. If the input power is lower than the target one, use the input power minus the ROADM loss if is exists, because a ROADM doesn’t amplify, it can only attenuate. There is no difference for add or express : the same target is applied. For the moment propagate operates with spectral info carriers all having the same source or destination.

Parameters:

  • spectral_info (SpectralInformation) – The spectral information object.

  • degree (str) – The egress degree.

  • from_degree (str) – The ingress degree.

set_roadm_paths(from_degree, to_degree, path_type, impairment_id=None)

set internal path type: express, drop or add with corresponding impairment

If no impairment id is defined, then use the first profile that matches the path_type in the profile dictionnary.

Parameters:

  • from_degree (str) – The ingress degree.

  • to_degree (str) – The egress degree.

  • path_type (str) – Type of the path (express, drop, add).-

  • impairment_id (int, optional) – Impairment profile ID. This parameter is optional.

property to_json

Converts the ROADM’s state to a JSON-compatible dictionary.

Return Dict[str, Any]:

JSON representation of the ROADM.

class gnpy.core.elements.Transceiver(*args, params=None, **kwargs)

Bases: _Node

Represents a logical start for propagation in the optical network.

Variables:

  • osnr_ase_01nm (numpy.ndarray) – OSNR in 0.1 nm bandwidth per carrier in the spectrum.

  • osnr_ase (numpy.ndarray) – OSNR ASE value per carrier in the spectrum.

  • osnr_nli (numpy.ndarray) – OSNR NLI value per carrier in the spectrum.

  • snr (numpy.ndarray) – Generalized Signal-to-noise ratio per carrier in the spectrum.

  • passive (bool) – Indicates if the system is passive (default is False).

  • baud_rate (numpy.ndarray) – Baud rate of each carrier of the emitted spectrum.

  • chromatic_dispersion (numpy.ndarray) – Chromatic dispersion value per carrier in the spectrum.

  • pmd (numpy.ndarray) – PMD value per carrier in the spectrum.

  • pdl (numpy.ndarray) – PDL value per carrier in the spectrum.

  • latency (numpy.ndarray) – Latency value per carrier in the spectrum.

  • penalties (Dict[str, float]) – Penalties for various impairments.

  • total_penalty (numpy.ndarray) – Total penalty value per carrier in the spectrum.

  • propagated_labels (numpy.ndarray[str]) – Labels propagated by the transceiver.

  • tx_power (numpy.ndarray) – Transmit power.

  • design_bands (list) – Design bands parameters.

  • per_degree_design_bands (dict) – Per degree design bands parameters.

_calc_cd(spectral_info)

Updates the Transceiver property with the CD of the received channels. CD in ps/nm.

_calc_latency(spectral_info)

Updates the Transceiver property with the latency of the received channels. Latency in ms.

_calc_pdl(spectral_info)

Updates the Transceiver property with the PDL of the received channels. PDL in dB.

_calc_penalty(impairment_value, boundary_list)

Computes the SNR penalty given the impairment value.

Parameters:

  • impairment_value (float) – The impairment value.

  • boundary_list (Dict[str, Any]) – The boundary list for penalties.

Return float:

The computed penalty.

_calc_pmd(spectral_info)

Updates the Transceiver property with the PMD of the received channels. PMD in ps.

_calc_snr(spectral_info)
calc_penalties(penalties)

Updates the Transceiver property with penalties (CD, PMD, etc.) of the received channels in dB. Penalties are linearly interpolated between given points and set to ‘inf’ outside interval.

property to_json

Converts the transceiver’s state to a JSON-compatible dictionary.

Return Dict[str, Any]:

JSON representation of the transceiver.

update_snr(*args)

snr_added in 0.1nm compute SNR penalties such as transponder Tx_osnr or Roadm add_drop_osnr only applied in request.py / propagate on the last Trasceiver node of the path all penalties are added in a single call because to avoid uncontrolled cumul

class gnpy.core.elements._Node(uid, name=None, params=None, metadata=None, operational=None, type_variety=None)

Bases: object

Convenience class for providing common functionality of all network elements

This class is just an internal implementation detail; do not assume that all network elements inherit from _Node.

Variables:

  • uid (str) – Unique identifier for the node.

  • name (str) – Printable name of the node.

  • params (Any) – Parameters associated with the node.

  • metadata (Dict[str, Any]) – Metadata including location.

  • operational (Any) – Operational parameters.

  • type_variety (str) – Type variety of the node.

property lat

Returns the latitude of the node.

property latitude

Returns the latitude of the node.

property lng

Returns the longitude of the node.

property loc

Returns the location of the node.

property location

Returns the location of the node.

property longitude

Returns the longitude of the node.

gnpy.core.equipment

This module contains functionality for specifying equipment.

gnpy.core.equipment.find_type_varieties(amps: List[str], equipment: dict) → List[List[str]]

Returns the multiband list of type_varieties associated with a list of single band type_varieties Args: amps (List[str]): A list of single band type_varieties. equipment (dict): A dictionary containing equipment information.

Returns: List[List[str]]: A list of lists containing the multiband type_varieties associated with each single band type_variety.

gnpy.core.equipment.find_type_variety(amps: List[str], equipment: dict) → List[str]

Returns the multiband type_variety associated with a list of single band type_varieties Args: amps (List[str]): A list of single band type_varieties. equipment (dict): A dictionary containing equipment information.

Returns: str: an amplifier type variety

gnpy.core.equipment.trx_mode_params(equipment, trx_type_variety='', trx_mode='', error_message=False)

return the trx and SI parameters from eqpt_config for a given type_variety and mode (ie format)

if the type or mode do no match an existing transceiver in the library, then the function raises an error if error_message is True else returns a default mode based on equipment[‘SI’][‘default’] If trx_mode is None (but type is valid), it returns an undetermined mode whatever the error message: this is a special case for automatic mode selection.

gnpy.core.exceptions

Exceptions thrown by other gnpy modules

exception gnpy.core.exceptions.ConfigurationError

Bases: Exception

User-provided configuration contains an error

exception gnpy.core.exceptions.DisjunctionError

Bases: ServiceError

Disjunction of user-provided request can not be satisfied

exception gnpy.core.exceptions.EquipmentConfigError

Bases: ConfigurationError

Incomplete or wrong configuration within the equipment library

exception gnpy.core.exceptions.NetworkTopologyError

Bases: ConfigurationError

Topology of user-provided network is wrong

exception gnpy.core.exceptions.ParametersError

Bases: ConfigurationError

Incomplete or wrong configurations within parameters json

exception gnpy.core.exceptions.ServiceError

Bases: Exception

Service of user-provided request is wrong

exception gnpy.core.exceptions.SpectrumError

Bases: Exception

Spectrum errors of the program

gnpy.core.info

This module contains classes for modelling SpectralInformation.

class gnpy.core.info.Carrier(delta_pdb: float, baud_rate: float, slot_width: float, roll_off: float, tx_osnr: float, tx_power: float, label: str)

Bases: object

One channel in the initial mixed-type spectrum definition, each type being defined by its delta_pdb (power offset with respect to reference power), baud rate, slot_width, roll_off tx_power, and tx_osnr. delta_pdb offset is applied to target power out of Roadm. Label is used to group carriers which belong to the same partition when printing results.

baud_rate: float
delta_pdb: float
label: str
roll_off: float
slot_width: float
tx_osnr: float
tx_power: float
class gnpy.core.info.Channel(channel_number, frequency, baud_rate, slot_width, roll_off, signal, ase, nli, chromatic_dispersion, pmd, pdl, latency)

Bases: Channel

Class containing the parameters of a WDM signal.

Parameters:

  • channel_number – channel number in the WDM grid

  • frequency – central frequency of the signal (Hz)

  • baud_rate – the symbol rate of the signal (Baud)

  • slot_width – the slot width (Hz)

  • roll_off – the roll off of the signal. It is a pure number between 0 and 1

  • signal – signal power (dBm)

  • ase – ASE noise power (dBm)

  • nli – NLI noise power (dBm)

  • chromatic_dispersion – chromatic dispersion (s/m)

  • pmd – polarization mode dispersion (s)

  • pdl – polarization dependent loss (dB)

  • latency – propagation latency (s)

gnpy.core.info.DEFAULT_SLOT_WIDTH_STEP = 12500000000.0

Channels with unspecified slot width will have their slot width evaluated as the baud rate rounded up to the minimum multiple of the DEFAULT_SLOT_WIDTH_STEP (the baud rate is extended including the roll off in this evaluation)

class gnpy.core.info.ReferenceCarrier(baud_rate: float, slot_width: float)

Bases: object

Reference channel type is used to determine target power out of ROADM for the reference channel when constant power spectral density (PSD) equalization is set. Reference channel is the type that has been defined in SI block and used for the initial design of the network. Computing the power out of ROADM for the reference channel is required to correctly compute the loss experienced by reference channel in Roadm element.

Baud rate is required to find the target power in constant PSD: power = PSD_target * baud_rate. For example, if target PSD is 3.125e4mW/GHz and reference carrier type a 32 GBaud channel then output power should be -20 dBm and for a 64 GBaud channel power target would need 3 dB more: -17 dBm.

Slot width is required to find the target power in constant PSW (constant power per slot width equalization): power = PSW_target * slot_width. For example, if target PSW is 2e4mW/GHz and reference carrier type a 32 GBaud channel in a 50GHz slot width then output power should be -20 dBm and for a 64 GBaud channel in a 75 GHz slot width, power target would be -18.24 dBm.

Other attributes (like roll-off) may be added there for future equalization purpose.

baud_rate: float
slot_width: float
class gnpy.core.info.SpectralInformation(frequency: array, baud_rate: array, slot_width: array, pch: array, signal_ratio: array, ase_ratio: array, nli_ratio: array, roll_off: array, chromatic_dispersion: array, pmd: array, pdl: array, latency: array, delta_pdb_per_channel: array, tx_osnr: array, tx_power: array, label: array)

Bases: object

Class containing the parameters of the entire WDM comb.

delta_pdb_per_channel: (per frequency) per channel delta power in dbm for the actual mix of channels

add_ase(ase)
add_nli(nli)
apply_attenuation_db(attenuation_db)
apply_attenuation_lin(attenuation_lin)
apply_gain_db(gain_db)
apply_gain_lin(gain_lin)
property ase
property ase_dbm
property baud_rate
property carriers
property channel_number
property chromatic_dispersion
property delta_pdb_per_channel
property df

Matrix of relative frequency distances between all channels. Positive elements in the upper right side.

property frequency
property gsnr
property gsnr_db
property label
property latency
property nli
property nli_dbm
property number_of_channels
property opt_gsnr_db
property opt_snr_lin_db
property opt_snr_nli_db
property pch
property pch_dbm
property pdl
property pmd
property ptot
property ptot_dbm
property roll_off
property signal
property signal_dbm
property slot_width
property snr_lin
property snr_lin_db
property snr_nli
property snr_nli_db
property tx_osnr
property tx_power
gnpy.core.info.carriers_to_spectral_information(initial_spectrum: dict[float, Carrier], power: float) → SpectralInformation

Initial spectrum is a dict with key = carrier frequency, and value a Carrier object. :param initial_spectrum: indexed by frequency in Hz, with power offset (delta_pdb), baudrate, slot width, tx_osnr, tx_power and roll off. :param power: power of the request

gnpy.core.info.create_arbitrary_spectral_information(frequency: ndarray | Iterable | float, pch: float | ndarray | Iterable, baud_rate: float | ndarray | Iterable, tx_osnr: float | ndarray | Iterable, tx_power: float | ndarray | Iterable = None, delta_pdb_per_channel: float | ndarray | Iterable = 0.0, slot_width: float | ndarray | Iterable = None, roll_off: float | ndarray | Iterable = 0.0, chromatic_dispersion: float | ndarray | Iterable = 0.0, pmd: float | ndarray | Iterable = 0.0, pdl: float | ndarray | Iterable = 0.0, latency: float | ndarray | Iterable = 0.0, label: str | ndarray | Iterable = None)

This is just a wrapper around the SpectralInformation.__init__() that simplifies the creation of a non-uniform spectral information with NLI and ASE powers set to zero.

gnpy.core.info.create_input_spectral_information(f_min, f_max, roll_off, baud_rate, spacing, tx_osnr, tx_power, delta_pdb=0)

Creates a fixed slot width spectral information with flat power. all arguments are scalar values

gnpy.core.info.demuxed_spectral_information(input_si: SpectralInformation, band: dict) → SpectralInformation | None

extract a si based on band

gnpy.core.info.is_in_band(frequency: array, slot_width: array, band: dict) → array

band has {“f_min”: value, “f_max”: value} format

gnpy.core.info.muxed_spectral_information(input_si_list: List[SpectralInformation]) → SpectralInformation

return the assembled spectrum

gnpy.core.info.select_channels(spectrum: SpectralInformation, select: array) → SpectralInformation

select: boolean array of indices to keep

gnpy.core.network

Working with networks which consist of network elements

gnpy.core.network.add_connector_loss(network: DiGraph, fibers: List[Fiber], default_con_in: float, default_con_out: float, EOL: float)

Adds default connector loss to fibers in the network if not already defined.

This function sets the input and output connector losses for each fiber. If no connector loss is defined, it assigns default values. Additionally, it adds an end-of-line (EOL) repair margin as a connector loss unless the next node is a fused element.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • fibers (List[elements.Fiber]) – A list of fiber nodes to which connector losses will be added.

  • default_con_in (float) – The default input connector loss to apply if not defined.

  • default_con_out (float) – The default output connector loss to apply if not defined.

  • EOL (float) – The end-of-line repair margin to be added as connector loss.

Returns:

None

Notes:

  • The function checks each fiber’s parameters and updates them accordingly.

  • It skips adding EOL loss if the next node is a fused element.

gnpy.core.network.add_fiber_padding(network: DiGraph, fibers: List[Fiber], padding: float, equipment: dict)

Adds padding attenuation at the input of the first fiber in a succession of fibers.

This function checks each fiber in the network and adds a specified padding loss at the input of the first fiber in a series of connected fibers if the calculated span loss is less than the specified padding.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • fibers (List[elements.Fiber]) – A list of fiber nodes to which padding will be added.

  • padding (float) – The amount of padding attenuation to apply.

  • equipment (dict) – A dictionary containing equipment specifications, including span loss data.

Returns:

None

Notes:

  • The function skips padding for Raman fibers and fused elements.

  • It updates the design span loss for each fiber accordingly.

gnpy.core.network.add_inline_amplifier(network: DiGraph, fiber: Fiber)

Adds an inline amplifier to the network between a fiber and its next node.

This function checks the next node connected to the specified fiber. If the next node is a fiber or a Raman fiber, it removes the existing edge and adds an inline amplifier (either a multiband amplifier or an EDFA) based on the type of the connected nodes. The amplifier is positioned at the midpoint between the fiber and the next node.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • fiber (elements.Fiber) – The fiber node to which the inline amplifier will be added.

Returns:

None

Notes:

  • The function determines the type of amplifier to add based on the connected nodes.

  • It updates the network by adding the amplifier node and connecting it to the fiber and the next node.

  • The amplifier’s location metadata is calculated as the midpoint between the fiber and the next node.

gnpy.core.network.add_missing_elements_in_network(network: DiGraph, equipment: dict)

Autodesigns the network by adding missing elements.

This function splits fibers that are too long, adds ROADM preamplifiers or boosters, and inserts inline amplifiers between fibers to ensure proper network design.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • equipment (dict) – A dictionary containing equipment specifications, including span data.

Returns:

None

Notes:

  • The function calculates the maximum and minimum lengths for fibers based on equipment specifications.

  • It processes all fiber nodes to ensure they are within acceptable length limits and adds necessary amplifiers.

gnpy.core.network.add_missing_fiber_attributes(network: DiGraph, equipment: dict)

Fills in missing connector loss attributes for fibers in the network.

This function sets default connector loss values for fibers and adds padding loss where required. It also includes end-of-line (EOL) losses as part of the connector loss configuration.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • equipment (dict) – A dictionary containing equipment specifications, including default span data.

Returns:

None

Notes:

  • The function processes all fiber nodes in the network to ensure they have the necessary attributes.

  • It separates the addition of connector losses and padding losses for clarity in the code.

gnpy.core.network.add_roadm_booster(network: DiGraph, roadm: Roadm)

Adds a booster amplifier to the specified ROADM in the network.

This function identifies the successor nodes of the ROADM that are not transceivers, fused elements, or amplifiers. For each valid successor, it removes the existing edge to the ROADM and adds a booster amplifier (either a multiband amplifier or an EDFA) based on the type of the connected nodes and the design bands of the ROADM. The amplifier is positioned at the location of the ROADM.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • roadm (elements.Roadm) – The ROADM node to which the booster amplifier will be added.

Returns:

None

Notes:

  • The function determines the type of amplifier to add based on the connected nodes and the design bands of the ROADM.

  • It updates the network by adding the amplifier node and connecting it to the ROADM and the successor node.

  • The amplifier’s location metadata is set to the location of the ROADM.

gnpy.core.network.add_roadm_preamp(network: DiGraph, roadm: Roadm)

Adds a preamplifier to the specified ROADM in the network.

This function identifies the predecessor nodes of the ROADM that are not transceivers, fused elements, or amplifiers. For each valid predecessor, it removes the existing edge to the ROADM and adds a preamplifier (either a multiband amplifier or an EDFA) based on the type of the connected nodes. The amplifier is positioned at the location of the ROADM.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • roadm (elements.Roadm) – The ROADM node to which the preamplifier will be added.

Returns:

None

Notes:

  • The function determines the type of amplifier to add based on the connected nodes.

  • It updates the network by adding the amplifier node and connecting it to the predecessor node and the ROADM.

  • The amplifier’s location metadata is set to the location of the ROADM.

gnpy.core.network.build_network(network: DiGraph, equipment: dict, reference_channel, set_connector_losses: bool = True, verbose: bool = True)

Sets the ROADM equalization targets and amplifier gain and power.

This function configures the network by setting the equalization targets for ROADMs, configuring the design bands for each node, and adjusting the gain, delta power, and output variable optical attenuation (VOA) for amplifiers along the optical paths.

Parameters:

  • network (DiGraph) – The network graph representing the topology to be configured.

  • equipment (dict) – A dictionary containing equipment specifications and configurations.

  • pref_ch_db (float) – The reference channel power in dBm.

  • pref_total_db (float) – The reference total power in dBm.

  • set_connector_losses (bool) – Flag indicating whether to set connector losses (default is True).

  • verbose (bool) – Flag indicating whether to print warnings and information (default is True).

Returns:

None

Notes:

  • The function processes ROADMs and transceivers to set their design bands and equalization targets.

  • It also configures amplifiers and sets input powers for fibers in the network.

gnpy.core.network.calculate_new_length(fiber_length, bounds, target_length)

If fiber is over boundary, then assume this is a link “intent” and computes the set of identical fiber spans this link should be composed of.

gnpy.core.network.check_oms_single_type(oms_edges: List[Tuple]) → List[str]

Verifies that the OMS only contains all single band amplifiers or all multi band amplifiers No mixed OMS are permitted for the time being. returns the amplifiers’type of the OMS

gnpy.core.network.check_per_degree_design_bands_keys(node: Roadm | Transceiver, network: DiGraph)

Checks that per_degree_design_bands keys are existing uid of elements in the network

Parameters:
gnpy.core.network.compute_band_power_deviation_and_tilt(srs_power_deviation: List[Dict], design_bands: Dict, ratio: float = 0.8)

Computes the power difference between bands at center frequency and the power tilt within each band.

This function calculates the relative power deviation with respect to the maximum value for each band and determines the tilt target to apply for each band based on the stimulated Raman scattering (SRS) power deviation.

Parameters:

  • srs_power_deviation (List[dict]) – A list of dictionaries containing the power at band centers and the tilt within each band.

  • design_bands (dict) – A dictionary of design bands with frequency ranges.

  • ratio (float) – The ratio applied to compute the band tilt (default is 0.8).

Returns:

A tuple containing: - A dictionary with the relative power deviation in dB for each band. - A dictionary with the tilt target to apply for each band.

Return type:

Tuple[dict, dict]

Notes:

  • If there is no SRS computed, the tilt estimation will be zero for all bands.

  • The function uses the maximum center frequency power to compute the deviations and tilt targets.

gnpy.core.network.compute_gain_power_and_tilt_target(node: Edfa, prev_node: Fiber | Roadm | Fused | Edfa | Transceiver, next_node: Fiber | Roadm | Fused | Edfa | Transceiver, power_mode: bool, prev_voa: float, prev_dp: float, pref_total_db: float, network: DiGraph, equipment: dict, deviation_db: float, tilt_target: float) → Tuple[float, float, float, float, float]

Computes the gain and power targets for a given EDFA node.

This function calculates the gain target, power target, delta power, output variable optical attenuation (VOA), and span loss for the specified EDFA node based on the network configuration and previous amplifier settings.

Parameters:
Returns:

A tuple containing: - gain_target (float): The computed gain target. - power_target (float): The computed power target. - tilt_target (float): The tilt target to be configured on this amplifier. - dp (float): The computed delta power. - voa (float): The output variable optical attenuation. - node_loss (float): The span loss from the previous amplifier.

Return type:

Tuple[float, float, float, float, float]

Notes:

  • The function considers both power mode and gain mode when calculating the gain target and delta power.

  • If the operational parameters are not set, default values are used for calculations.

gnpy.core.network.compute_tilt_using_previous_and_next_spans(prev_node: Fiber | Roadm | Fused | Edfa | Transceiver, next_node: Fiber | Roadm | Fused | Edfa | Transceiver, design_bands: Dict[str, float], input_powers: Dict[str, float], equipment: dict, network: DiGraph, prev_weight: float = 1.0, next_weight: float = 0) → Tuple[Dict[str, float], Dict[str, float]]

Computes the power deviation per band and the tilt target based on previous and next spans.

This function estimates the power deviation between center frequencies due to the previous span and the tilt within each band using the previous and next fiber spans, applying specified weights.

Parameters:
Returns:

A tuple containing: - A dictionary with the tilt estimation for each design band. - A dictionary with the tilt target for each design band.

Return type:

Tuple[Dict[str, float], Dict[str, float]]

Notes:

  • The function computes the tilt based on the estimated stimulated Raman scattering (SRS) power deviation from the previous and next spans.

  • If either node is not a Fiber, the corresponding tilt estimation will not be computed.

gnpy.core.network.design_network(reference_channel, network: DiGraph, equipment: Dict, set_connector_losses: bool = True, verbose: bool = True)

Designs the network according to the specified reference channel.

This function configures the network based on the properties of the reference channel, including the number of channels and their power levels. It also allows for the setting of connector losses and controls the verbosity of logging for warnings and information.

Parameters:

  • reference_channel (gnpy.topology.request.PathRequest) – The reference channel used for designing the network.

  • network (DiGraph) – The network graph representing the topology to be designed.

  • equipment (Dict) – A dictionary containing equipment specifications and configurations.

  • set_connector_losses (bool) – Flag indicating whether to set connector losses (default is True).

  • verbose (bool) – Flag indicating whether to print warnings and information (default is True).

Returns:

None

Notes:

  • The function calculates the reference total power based on the number of channels and their power levels.

gnpy.core.network.edfa_nf(gain_target: float, amp_params) → float

Calculates the noise figure (NF) of an EDFA (Erbium-Doped Fiber Amplifier) based on the specified gain target and amplifier parameters.

This function creates an EDFA instance with the given parameters and computes its noise figure using the internal calculation method.

Parameters:

  • gain_target (float) – The target gain for which the noise figure is to be calculated.

  • amp_params (gnpy.tools.json_io.Amp) – An object containing the amplifier parameters.

Returns:

The calculated noise figure (NF) of the EDFA in dB.

Return type:

float

Raises:

ValueError – If the gain_target is not achievable with the given parameters.

gnpy.core.network.estimate_raman_gain(node: Fiber | Roadm | Fused | Edfa | Transceiver, equipment: DiGraph, power_dbm: float) → float

Estimates the possible Raman gain for a given node if it is a RamanFiber.

This function computes the stimulated Raman scattering loss profile to estimate the gain. Note that this computation may be time-consuming.

Parameters:

  • node (elements) – The node for which the Raman gain is to be estimated.

  • equipment (dict) – A dictionary containing equipment parameters and configurations.

  • power_dbm (float) – The input power in dBm to be used for the gain estimation.

Returns:

The estimated Raman gain in dB, or 0.0 if the node is not a RamanFiber.

Return type:

float

Raises:

ValueError – If the node is not properly configured or if required parameters are missing.

Notes:

  • If the node is a RamanFiber and has already estimated gain, it will return the cached value.

  • The function applies various parameters from the equipment configuration to compute the gain.

gnpy.core.network.estimate_srs_power_deviation(network: DiGraph, last_node, equipment: Dict, design_bands: Dict, input_powers: Dict) → List[Dict]

Estimate tilt of power accross the design bands.

If Raman flag is on (sim-params), this function estimates the center frequency power and the power tilt within each design band using the stimulated Raman scattering loss profile. Note that this computation may be time-consuming.

Parameters:

  • network (DiGraph) – The network object representing the topology.

  • last_node (elements) – The last node (Fiber or RamanFiber) of the considered span, which may consist of a succession of fiber and fused elements.

  • equipment (dict) – A dictionary containing equipment parameters.

  • design_bands (dict) – A dictionary of design bands with frequency ranges.

  • input_powers (dict) – A dictionary of input powers in the fiber span for each design band.

Returns:

A list of dictionaries containing the power at band centers and the tilt within each band.

Return type:

List[dict]

Raises:

ValueError – If an unexpected type is encountered for nodes during processing.

Notes:

  • The function collects preceding nodes (Fiber and Fused) and computes the stimulated Raman scattering for each fiber span to estimate the power deviation.

  • The results include center frequency powers normalized to the input powers and the in-band power deviation in dB.

gnpy.core.network.filter_edfa_list_based_on_targets(uid: str, edfa_eqpt: dict, power_target: float, gain_target: float, tilt_target: float, target_extended_gain: float, raman_allowed: bool = True, verbose: bool = False)

Filters amplifiers based on power, gain, and tilt targets.

This function evaluates a list of EDFA amplifiers and filters them according to specified power, gain, and tilt targets. It considers both standard and Raman amplifiers based on the provided parameters.

Parameters:

  • uid (str) – The unique identifier for the node being processed.

  • edfa_eqpt (dict) – A dictionary containing the amplifiers’ equipment specifications.

  • power_target (float) – The target power level for the amplifiers.

  • gain_target (float) – The target gain level for the amplifiers.

  • tilt_target (float) – The target tilt level for the amplifiers.

  • target_extended_gain (float) – The extended gain target for the amplifiers.

  • raman_allowed (bool) – Flag indicating whether to include Raman amplifiers in the selection (default is True).

  • verbose (bool) – Flag for enabling verbose logging (default is False).

Returns:

A list of amplifiers that satisfy the specified power, gain, and tilt targets.

Return type:

list

Raises:

ConfigurationError – If no amplifiers meet the minimum gain requirement.

Notes:

  • The function creates two lists of amplifiers: one for standard EDFAs and another for Raman amplifiers, applying different criteria for each.

  • If no amplifiers meet the minimum gain requirement, a warning is issued, and the function raises an error.

gnpy.core.network.find_first_node(network, node)

Finds the first node at the origin of a succession of fused nodes.

This function traverses the network in reverse to locate the first node in a sequence of fused nodes, ensuring that there are no amplifiers in between.

Parameters:

  • network (Any) – The network object representing the topology.

  • node (elements) – The starting node from which to find the first fused node.

Returns:

The first node in the succession of fused nodes.

Return type:

elements

gnpy.core.network.find_last_node(network, node)

Finds the last node in a succession of fused nodes.

This function traverses the network to locate the last node in a sequence of fused nodes, ensuring that there are no amplifiers in between.

Parameters:

  • network (Any) – The network object representing the topology.

  • node (elements) – The starting node from which to find the last fused node.

Returns:

The last node in the succession of fused nodes.

Return type:

elements

gnpy.core.network.get_next_node(node, network)

get_next node else raise tha appropriate error

gnpy.core.network.get_node_restrictions(node: Edfa | Multiband_amplifier, prev_node: Fiber | Roadm | Fused | Edfa | Transceiver, next_node: Fiber | Roadm | Fused | Edfa | Transceiver, equipment: dict, _design_bands: dict) → List

Returns a list of eligible amplifiers that comply with restrictions and design bands.

If the node is a multiband amplifier, only multiband amplifiers will be considered.

Parameters:
Returns:

A list of eligible amplifier types that meet the specified restrictions.

Return type:

List[str]

Notes:

  • If the amplifier node has a specified type variety, that variety takes precedence over other restrictions.

  • The function checks for restrictions based on the previous and next nodes if applicable.

  • For multiband amplifiers, it filters the available amplifiers to ensure they are eligible for all design bands.

gnpy.core.network.get_oms_edge_list(oms_ingress_node: Roadm | Transceiver, network: DiGraph) → List[Tuple]

get the list of OMS edges (node, neighbour next node) starting from its ingress down to its egress oms_ingress_node can be a ROADM or a Transceiver

gnpy.core.network.get_oms_edge_list_from_egress(oms_egress_node, network: DiGraph) → List[Tuple]

get the list of OMS edges (node, neighbour next node) starting from its ingress down to its egress oms_ingress_node can be a ROADM or a Transceiver

gnpy.core.network.get_previous_node(node, network)

get previous node else raise the appropriate error

gnpy.core.network.next_node_generator(network: DiGraph, node: Fiber | Roadm | Fused | Edfa | Transceiver) → Iterator[Fiber | Fused]

Generates successor nodes in the network that are either Fused or Fibers preceded by Fused.

This function iterates over all successors of the specified node, yielding nodes that meet the criteria of being either a Fused element or a Fiber that is preceded by a Fused element.

Parameters:
Yield:

The successor nodes that are either Fused or Fibers preceded by Fused.

Return type:

Iterator[Union[elements.Fiber, elements.Fused]

Raises:

NetworkTopologyError – If the node is not properly connected in the network topology.

Notes:

  • If the node is a Transceiver and has no successors, the function will return without yielding any nodes.

gnpy.core.network.preselect_multiband_amps(uid: str, _amplifiers: dict, prev_node: Fiber | Roadm | Fused | Edfa | Transceiver, next_node: Fiber | Roadm | Fused | Edfa | Transceiver, power_mode: bool, prev_voa: dict, prev_dp: dict, pref_total_db: dict, network: DiGraph, equipment: dict, restrictions: List, _design_bands: dict, deviation_db: dict, tilt_target: dict)

Preselects multiband amplifiers eligible based on power, gain, and tilt targets across all bands.

This function filters multiband amplifiers according to specified constraints, ensuring that they meet the power, gain, and tilt targets for each design band.

Parameters:

  • uid (str) – The unique identifier for the node being processed.

  • _amplifiers (dict) – A dictionary containing the amplifiers of the multiband amplifier.

  • prev_node (Union[elements.Fiber, elements.Roadm, elements.Fused, elements.Edfa, elements.Transceiver, elements.Transceiver]) – The previous node in the network.

  • next_node (Union[elements.Fiber, elements.Roadm, elements.Fused, elements.Edfa, elements.Transceiver, elements.Transceiver]) – The next node in the network.

  • power_mode (bool) – Indicates if the computation is in power mode.

  • prev_voa (dict) – A dictionary containing the previous amplifier output VOA settings per band.

  • prev_dp (dict) – A dictionary containing the previous amplifier delta power settings per band.

  • pref_total_db (float) – The total power used for design in dBm.

  • network (DiGraph) – The network graph representing the topology.

  • equipment (dict) – A dictionary containing equipment specifications.

  • restrictions (List) – A list of restrictions related to amplifier selection.

  • _design_bands (dict) – A dictionary of design bands with frequency ranges.

  • deviation_db (dict) – A dictionary of tilt power per band.

  • tilt_target (dict) – A dictionary of tilt targets for each band.

Returns:

A list of preselected multiband amplifiers that are eligible for all the bands.

Return type:

list

Notes:

  • The function iteratively filters amplifiers based on the constraints and updates the selection based on the results from each band.

  • If no amplifiers meet the criteria, an empty list is returned.

gnpy.core.network.prev_node_generator(network: DiGraph, node: Fiber | Roadm | Fused | Edfa | Transceiver) → Iterator[Fiber | Fused]

Generates predecessor nodes in the network that are either Fused or Fibers succeeded by Fused.

This function iterates over all predecessors of the specified node, yielding nodes that meet the criteria of being either a Fused element or a Fiber that is succeeded by a Fused element.

Parameters:
Yield:

The predecessor nodes that are either Fused or Fibers succeeded by Fused.

Return type:

Iterator[Union[elements.Fiber, elements.Fused]

Raises:

NetworkTopologyError – If the node is not properly connected in the network topology.

Notes:

  • If the node is a Transceiver and has no predecessors, the function will return without yielding any nodes.

gnpy.core.network.select_edfa(raman_allowed: bool, gain_target: float, power_target: float, edfa_eqpt: dict, uid: str, target_extended_gain: float, verbose: bool | None = True) → Tuple[str, float]

Selects an amplifier within a library based on specified parameters.

This function implements an amplifier selection algorithm that considers various constraints, including gain and power targets. It can also handle Raman amplifiers if allowed. edfa_eqpt dict has already filtered out the amplifiers that do not match any other restrictions such as ROADM booster or preamp restrictions or frequency constraints.

Parameters:

  • raman_allowed (bool) – Indicates whether Raman amplifiers are permitted in the selection.

  • gain_target (float) – The target gain that the selected amplifier should achieve.

  • power_target (float) – The target power level for the amplifier.

  • edfa_eqpt (dict) – A dictionary containing available EDFA equipment, where keys are amplifier names and values are amplifier objects.

  • uid (str) – A unique identifier for the node where the amplifier will be used.

  • target_extended_gain (float) – The extended gain target derived from configuration settings.

  • verbose (Optional[bool], default=True) – If True, enables verbose logging of warnings and information.

Returns:

A tuple containing the selected amplifier’s variety and the power reduction applied (if any).

Return type:

Tuple[str, float]

Raises:

ConfigurationError – If no amplifiers meet the minimum gain requirement for the specified node.

Notes:

  • The function considers both gain and power limitations when selecting an amplifier.

  • If no suitable amplifier is found or if the target gain exceeds the capabilities of available amplifiers, a warning is logged.

Author:

Jean-Luc Augé

gnpy.core.network.set_amplifier_voa(amp: Edfa, power_target: float, power_mode: bool, voa_margin: float, voa_step: float)

Sets the output variable optical attenuator (VOA) for the amplifier.

This function adjusts the VOA based on the target power and the operating mode of the amplifier. It ensures that the VOA is not maximized beyond a certain margin.

Parameters:

  • amp (elements.Edfa) – The amplifier object for which the VOA is being set.

  • power_target (float) – The target output power level for the amplifier.

  • power_mode (bool) – The mode for the design (power_mode True means use delta_p targets, while power_mode False means use gain targets).

Returns:

None

Notes:

  • If the amplifier’s output VOA is set to None and the power mode is active, the function calculates the appropriate VOA value based on the amplifier’s parameters and the target power.

  • If power_mode is False, the output VOA optimization is not applied.

gnpy.core.network.set_egress_amplifier(network: DiGraph, this_node: Roadm | Transceiver, equipment: dict, pref_ch_db: float, verbose: bool, reference_channel)

Configures the egress amplifiers for a given node in the network.

Go through each link starting from this_node until next Roadm or Transceiver and set the amplifiers (Edfa and multiband) according to configurations set by user. Computes the gain for Raman finers and records it as the gain for reference design.

  • power_mode = True, set amplifiers delta_p and effective_gain

  • power_mode = False, set amplifiers effective_gain and ignore delta_p config: set it to None.

Records the computed dp in an internal variable for autodesign purpose.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • this_node (Union[elements.Roadm, elements.Transceiver]) – The starting node for OMS link configuration, which can be a ROADM or Transceiver.

  • equipment (dict) – Equipment specifications.

  • pref_ch_db (float) – Reference channel power in dBm.

  • pref_total_db (float) – Reference total power in dBm.

  • verbose (bool) – Flag for verbose logging.

Raises:

Notes:

  • The function initializes power and VOA settings for each design band and updates them as it traverses through the network nodes.

  • It handles different types of nodes (EDFA, RamanFiber, Multiband_amplifier) and applies appropriate configurations based on their characteristics.

gnpy.core.network.set_fiber_input_power(network: DiGraph, fiber: Fiber, equipment: dict, pref_ch_db: float)

Sets the reference power at the input of a fiber for a specified reference channel.

This function calculates the input power for a fiber based on the losses incurred through connected nodes, including ROADMs, amplifiers, and other fibers. It assumes that the target power out of ROADMs and amplifiers is consistent. This is primarily for visualization purposes.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • fiber (elements.Fiber) – The fiber node for which the input power is being set.

  • equipment (dict) – A dictionary containing equipment specifications.

  • pref_ch_db (float) – The preferred channel power in dBm to be used as a reference.

Returns:

None

Notes:

  • The function traverses the network to calculate the cumulative loss from the predecessor nodes.

  • It sets the reference power based on the type of the preceding node, adjusting for losses accordingly.

  • The function handles various node types, including fibers, ROADMs, EDFAs, transceivers, and multiband amplifiers.

gnpy.core.network.set_one_amplifier(node: Edfa, prev_node: Fiber | Roadm | Fused | Edfa | Transceiver, next_node: Fiber | Roadm | Fused | Edfa | Transceiver, power_mode: bool, prev_voa: float, prev_dp: float, pref_ch_db: float, pref_total_db: float, network: DiGraph, restrictions: List[str], equipment: dict, verbose: bool, deviation_db: float = 0.0, tilt_target: float = 0.0) → Tuple[float, float]

Sets the EDFA amplifier configuration based on power targets.

This function adjusts the amplifier settings according to specified parameters and ensures compliance with power and gain targets. It handles both cases where the amplifier type is specified or needs to be selected based on restrictions.

Parameters:

  • node (elements.Edfa) – The EDFA amplifier node to configure.

  • prev_node (Union[elements.Fiber, elements.Roadm, elements.Fused, elements.Edfa, elements.Transceiver, elements.Transceiver]) – The previous node in the network.

  • next_node (Union[elements.Fiber, elements.Roadm, elements.Fused, elements.Edfa, elements.Transceiver, elements.Transceiver]) – The next node in the network.

  • power_mode (bool) – Indicates if the amplifier is in power mode.

  • prev_voa (float) – The previous amplifier variable optical attenuator value.

  • prev_dp (float) – The previous amplifier delta power.

  • pref_ch_db (float) – Reference per channel power in dBm.

  • pref_total_db (float) – Reference total power in dBm.

  • network (DiGraph) – The network graph representing the topology.

  • restrictions (List[str]) – A list of amplifiers authorized for this configuration.

  • equipment (dict) – Equipment library containing amplifier specifications.

  • verbose (bool) – Flag for verbose logging.

  • deviation_db (float) – Tilt power per band (default is 0.0).

  • tilt_target (float) – Tilt target in each band (default is 0.0).

Returns:

A tuple containing the updated delta power and variable optical attenuator values.

Return type:

Tuple[float, float]

Notes:

  • The function computes the gain and power targets based on previous amplifier settings and the network state.

  • It selects the appropriate amplifier type based on the specified restrictions and updates the amplifier parameters accordingly.

  • Warnings are logged if the effective gain exceeds the specified amplifier limits.

gnpy.core.network.set_per_degree_design_band(node: Roadm | Transceiver, network: DiGraph, equipment: dict)

Configures the design bands for each degree of a node based on network and equipment constraints. This function determines the design bands for each degree of a node (either a ROADM or a Transceiver) based on the existing amplifier types and spectral information (SI) constraints. It uses a default design band derived from the SI or ROADM bands if no specific bands are defined by the user. node.params.x contains the values initially defined by user (with x in design_bands, per_degree_design_bands). node.x contains the autodesign values.

Parameters:

  • node (Union[elements.Roadm, elements.Transceiver]) – The node for which design bands are being set (ROADM or Transceiver).

  • network (DiGraph) – The network containing the node and its connections.

  • equipment (dict) – A dictionary containing equipment data, including spectral information.

Raises:

NetworkTopologyError – If there is an inconsistency in band definitions or unsupported configurations.

Notes:

  • The function prioritizes user-defined bands in node.params if available.

  • It checks for consistency between default bands and amplifier types.

  • Mixed single-band and multi-band configurations are not supported and will raise an error.

  • The function ensures that all bands are ordered by their minimum frequency.

gnpy.core.network.set_roadm_input_powers(network: DiGraph, roadm: Roadm, equipment: dict, pref_ch_db: float)

Sets the reference powers at the input of a ROADM for a specified reference channel based on adjacent OMS.

This function calculates the input power for the ROADM based on the losses incurred through connected nodes. It assumes that there is no dependency on the path, meaning that the power output from one element may not be consistent with the target powers of subsequent elements. If the target powers cannot be met, a warning is raised.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • roadm (elements.Roadm) – The ROADM node for which the input powers are being set.

  • equipment (dict) – A dictionary containing equipment specifications.

  • pref_ch_db (float) – The preferred channel power in dBm to be used as a reference.

Returns:

None

Raises:

ConfigurationError – If no target power, PSD, or PSW can be found in the ROADM.

Notes:

  • The function traverses the network to calculate the cumulative loss from the predecessor nodes.

  • It sets the reference power based on the type of the preceding node, adjusting for losses accordingly.

  • If the calculated input power is below the maximum target power, a warning is logged to inform the user.

  • This value is primarily used for visualization purposes to compute resulting ROADM loss in elements.

Example:

For a ROADM with the following configuration:

::

`` node power out of element roadm A (target power -10dBm) -10dBm fiber A (16 dB loss) -26dBm roadm B (target power -12dBm) -26dBm fiber B (10 dB loss) -36dBm roadm C (target power -14dBm) -36dBm ``

is not consistent because target powers in roadm B and roadm C can not be met. The input power for the reference channel will be set to -26 dBm in roadm B and -22 dBm in roadm C, because at design time we cannot know about the path. The function raises a warning if target powers cannot be met with the design, indicating that the user should be aware that the design was not successful and that power reduction was applied.

gnpy.core.network.set_roadm_internal_paths(roadm: Roadm, network: DiGraph)

Sets the internal path types (express, add, drop) for a ROADM.

This function determines the path types for the ROADM based on its connections to other nodes in the network. It uses implicit assumptions if no specific information is provided for the ROADM’s paths.

Parameters:

  • roadm (elements.Roadm) – The ROADM node for which the internal paths are being set.

  • network (DiGraph) – The network graph containing nodes and links.

Returns:

None

Raises:

NetworkTopologyError – If the path types are inconsistent with the expected types based on the connections.

Notes:

  • The function identifies the next and previous nodes connected to the ROADM, distinguishing between transceivers and other elements.

  • It sets the path types based on the connections and raises errors if any inconsistencies are found.

  • The function ensures that paths connected to transceivers are marked as ‘add’ or ‘drop’, while other paths can be ‘express’, ‘add’, or ‘drop’.

gnpy.core.network.set_roadm_per_degree_targets(roadm, network)

Set target powers/PSD on all degrees This is needed to populate per_degree_pch_out_dbm or per_degree_pch_psd or per_degree_pch_psw dicts when they are not initialized by users.

gnpy.core.network.set_roadm_ref_carrier(roadm, equipment)

ref_carrier records carrier information used for design and usefull for equalization

gnpy.core.network.span_loss(network: DiGraph, node: Fiber | Fused, equipment: Dict, input_power: float | None = None) → float

Calculates the total loss of a span (Fiber and Fused nodes) containing the specified node.

This function computes the total loss by considering the losses of the node itself, its predecessors, and successors in the network. It also accounts for any Raman gain that may be present in the span.

Parameters:

  • network (DiGraph) – The directed graph representing the network topology.

  • node (Union[elements.Fiber, elements.Fused]) – The node for which the span loss is being calculated.

  • equipment (dict) – A dictionary containing equipment parameters and configurations.

  • input_power (float, optional) – The input power in dBm, used for estimating Raman gain (optional).

Returns:

The total span loss in dB.

Return type:

float

Raises:

ValueError – If the node is not properly configured or if required parameters are missing.

Notes:

  • The function caches the computed span loss in the design_span_loss attribute of the node to avoid redundant calculations.

  • If the node is passive, its loss is considered; otherwise, it is treated as zero.

gnpy.core.network.split_fiber(network, fiber, bounds, target_length)

Splits a fiber into multiple spans if its length exceeds specified boundaries.

If the length of the fiber exceeds the defined bounds, this function replaces the single span link with multiple spans of identical fiber types. It calculates the new lengths and positions for each span.

Parameters:

  • network (DiGraph) – The network graph containing nodes and links.

  • fiber (elements.Fiber) – The fiber node to be split into multiple spans.

  • bounds (range) – The range of lengths to determine if the fiber should be split.

  • target_length (float) – The target length for each span after splitting.

Returns:

None

Raises:

NetworkTopologyError – If the fiber is not properly connected in the network topology.

Notes:

  • The function calculates the number of spans required and their respective lengths.

  • It updates the network by removing the original fiber and adding the new spans with updated positions.

gnpy.core.network.target_power(network: DiGraph, node: Fiber | Roadm | Fused, equipment: Dict, deviation_db: float) → float

Computes the target power deviation (delta_p) for a given node in the network.

This function uses the methodology described by J. -L. Auge, V. Curri, and E. Le Rouzic in “Open Design for Multi-Vendor Optical Networks,” OFC 2019, specifically equation 4.

Parameters:

  • network (DiGraph) – The network object containing the topology and elements.

  • node (elements.Fiber) – The node for which the target power is being calculated.

  • equipment (dict) – A dictionary containing equipment parameters and configurations.

  • deviation_db (float) – The deviation in dB to be applied to the calculated power, for example due to SRS power tilt.

Returns:

The computed target power deviation in dB.

Return type:

float

Raises:

ConfigurationError – If the delta power range is not defined correctly in the equipment configuration.

Notes:

  • If the node is a ROADM, the function returns 0.

  • The target power is calculated based on the span loss and adjusted by the specified deviation.

  • In theory at the optimum, the slope should be 1/3 (~0.3)

  • the returned delta_p will be the optimum deviation with respect to the span_loss_ref.

gnpy.core.network.update_design_bands_spacing(node: Roadm | Transceiver, default_spacing: float)

Update the spacing of design bands for a given node.

This function iterates through the design bands associated with the node and updates their spacing based on the frequency range defined by ‘f_min’ and ‘f_max’. If a specific spacing cannot be determined from the design bands, the default spacing is used.

Parameters:

  • node (Union[elements.Roadm, elements.Transceiver]) – The node object which can be either a Roadm or Transceiver instance.

  • default_spacing (float) – The default spacing to use if no specific spacing can be determined.

gnpy.core.parameters

This module contains all parameters to configure standard network elements.

class gnpy.core.parameters.EdfaOperational(**operational)

Bases: object

default_values = {'delta_p': None, 'gain_target': None, 'in_voa': 0, 'out_voa': None, 'tilt_target': None}
update_attr(kwargs)
class gnpy.core.parameters.EdfaParams(**params)

Bases: object

default_values = {'advance_configurations_from_json': None, 'allowed_for_design': False, 'bands': None, 'booster_variety': None, 'dgt': None, 'dual_stage_model': None, 'f_max': None, 'f_min': None, 'f_ripple_ref': None, 'gain_flatmax': None, 'gain_min': None, 'gain_ripple': 0, 'multi_band': None, 'nf0': None, 'nf_coef': None, 'nf_fit_coeff': None, 'nf_max': None, 'nf_min': None, 'nf_model': None, 'nf_ripple': 0, 'out_voa_auto': False, 'p_max': None, 'pdl': 0, 'pmd': 0, 'preamp_variety': None, 'raman': False, 'tilt_ripple': 0, 'type_def': '', 'type_variety': ''}
update_params(kwargs)
class gnpy.core.parameters.FiberParams(**kwargs)

Bases: Parameters

asdict()
property att_in
property con_in
property con_out
property dispersion
property dispersion_slope
effective_area_overlap(frequency_stokes_wave, frequency_pump)
effective_area_scaling(frequency)
property f_dispersion_ref
property f_loss_ref
property gamma
gamma_scaling(frequency)
property latency
property length
property loss_coef
property lumped_losses
property pmd_coef
property pmd_coef_defined
property raman_coefficient
property ref_frequency
property ref_wavelength
class gnpy.core.parameters.FrequencyBand(f_min: float, f_max: float)

Bases: object

Frequency band

f_max: float
f_min: float
class gnpy.core.parameters.FusedParams(**kwargs)

Bases: Parameters

class gnpy.core.parameters.MultiBandParams(**params)

Bases: object

default_values = {'allowed_for_design': False, 'bands': [], 'type_def': None, 'type_variety': ''}
update_attr(kwargs)
class gnpy.core.parameters.NLIParams(method='gn_model_analytic', dispersion_tolerance=4, phase_shift_tolerance=0.1, computed_channels=None, computed_number_of_channels=None)

Bases: Parameters

to_json()
class gnpy.core.parameters.Parameters

Bases: object

asdict()
class gnpy.core.parameters.PumpParams(power, frequency, propagation_direction)

Bases: Parameters

class gnpy.core.parameters.RamanGainCoefficient(normalized_gamma_raman, frequency_offset)

Bases: RamanGainCoefficient

Raman Gain Coefficient Parameters

Based on:

Andrea D’Amico, Bruno Correia, Elliot London, Emanuele Virgillito, Giacomo Borraccini, Antonio Napoli, and Vittorio Curri, “Scalable and Disaggregated GGN Approximation Applied to a C+L+S Optical Network,” J. Lightwave Technol. 40, 3499-3511 (2022) Section III.D

class gnpy.core.parameters.RamanParams(flag=False, method='perturbative', order=2, result_spatial_resolution=10000.0, solver_spatial_resolution=10000.0)

Bases: Parameters

to_json()
class gnpy.core.parameters.RoadmImpairment(params)

Bases: object

Generic definition of impairments for express, add and drop

default_values = {'minloss': None, 'pmin': None, 'ptyp': None, 'roadm-cd': None, 'roadm-inband-crosstalk': None, 'roadm-maxloss': 0, 'roadm-noise-figure': None, 'roadm-osnr': None, 'roadm-pdl': None, 'roadm-pmax': None, 'roadm-pmd': None, 'typloss': None}
class gnpy.core.parameters.RoadmParams(**kwargs)

Bases: Parameters

get_roadm_path_impairments(path_impairments_list)

Get the ROADM list of profiles for impairments definition

transform the ietf model into gnpy internal model: add a path-type in the attributes

class gnpy.core.parameters.RoadmPath(from_degree, to_degree, path_type, impairment_id=None, impairment=None)

Bases: object

class gnpy.core.parameters.SimParams

Bases: Parameters

_shared_dict = {'nli_params': <gnpy.core.parameters.NLIParams object>, 'raman_params': <gnpy.core.parameters.RamanParams object>}
property nli_params
property raman_params
classmethod set_params(sim_params)
class gnpy.core.parameters.TransceiverParams(**params)

Bases: object

gnpy.core.parameters.find_band_name(band: FrequencyBand) → str

return the default band name (CBAND, LBAND, …) that corresponds to the band frequency range Use the band center frequency: if center frequency is inside the band then returns CBAND. This is to flexibly encompass all kind of bands definitions. returns the first matching band name.

gnpy.core.science_utils

Solver definitions to calculate the Raman effect and the nonlinear interference noise

The solvers take as input instances of the spectral information, the fiber and the simulation parameters

class gnpy.core.science_utils.NliSolver

Bases: object

This class implements the NLI models. Model and method can be specified in sim_params.nli_params.method. List of implemented methods: ‘gn_model_analytic’: eq. 120 from arXiv:1209.0394 ‘ggn_spectrally_separated’: eq. 21 from arXiv: 1710.02225 ‘ggn_approx’: eq. 24-25 jlt:9741324

SPM_WEIGHT = 0.5925925925925926
XPM_WEIGHT = 1.1851851851851851
static _approx_psi(df, frequency, baud_rate, beta2, loss_profile, z)

Computes the approximated psi function similarly to the one used in the GN model. The method uses eq. 25 of https://ieeexplore.ieee.org/document/9741324

static _fast_generalized_psi(f_eval, cut_frequency, cut_baud_rate, cut_roll_off, pump_frequency, pump_baud_rate, pump_roll_off, f_cut_resolution, srs, alpha, beta2, beta3, f_ref_beta)

Computes the generalized psi function similarly to the one used in the GN model.

static _frequency_offset_threshold(beta2, symbol_rate)
static _generalized_psi(f_eval, cut_frequency, cut_baud_rate, cut_roll_off, pump_frequency, pump_baud_rate, pump_roll_off, f_cut_resolution, f_pump_resolution, srs, alpha, beta2, beta3, f_ref_beta)

Computes the generalized psi function similarly to the one used in the GN model.

static _generalized_rho_nli(delta_beta, rho_pump, z, alpha)
static _ggn_approx(cut_indices, spectral_info: SpectralInformation, fiber, srs, spm_weight=0.5925925925925926, xpm_weight=1.1851851851851851)

Computes the nonlinear interference power evaluated at the fiber input. The method uses eq. 24-25 of https://ieeexplore.ieee.org/document/9741324

static _ggn_spectrally_separated(cut_indices, spectral_info, fiber, srs, spm_weight=0.5925925925925926, xpm_weight=1.1851851851851851)

Computes the nonlinear interference power evaluated at the fiber input. The method uses eq. 21 from arXiv: 1710.02225

static _gn_analytic(spectral_info, fiber, spm_weight=0.5925925925925926, xpm_weight=1.1851851851851851)

Computes the nonlinear interference power evaluated at the fiber input. The method uses eq. 120 from arXiv:1209.0394

static _psi(df, baud_rate, beta2, effective_length, asymptotic_length)

Calculates eq. 123 from arXiv:1209.0394

static compute_nli(spectral_info: SpectralInformation, srs: StimulatedRamanScattering, fiber)

Compute NLI power generated by the WDM comb *carriers on the channel under test carrier at the end of the fiber span.

static effective_length(alpha, length)

The effective length identify the region in which the NLI has a significant contribution to the signal degradation.

class gnpy.core.science_utils.RamanSolver

Bases: object

This class contains the methods to calculate the Raman scattering effect.

static _create_lumped_losses(z, lumped_losses, z_lumped_losses)
static calculate_attenuation_profile(spectral_info: SpectralInformation, fiber)

Evaluates the attenuation profile along the z axis for all the frequency propagating in the fiber without considering the stimulated Raman scattering.

static calculate_spontaneous_raman_scattering(spectral_info: SpectralInformation, srs: StimulatedRamanScattering, fiber)

Evaluates the Raman profile along the z axis for all the frequency propagated in the fiber including the Raman pumps co- and counter-propagating.

static calculate_stimulated_raman_scattering(spectral_info: SpectralInformation, fiber)

Evaluates the Raman profile along the z axis for all the frequency propagated in the fiber including the Raman pumps co- and counter-propagating

static calculate_unidirectional_stimulated_raman_scattering(power_in, alpha, cr, z, lumped_losses)

Solves the Raman equation

Parameters:

  • power_in – launch power array

  • alpha – loss coefficient array

  • cr – Raman efficiency coefficients matrix

  • z – z position array

  • lumped_losses – concentrated losses array along the fiber span

Returns:

power profile matrix

static iterative_algorithm(co_initial_guess_power, cnt_initial_guess_power, co_frequency, cnt_frequency, z, fiber, lumped_losses)

Solves the Raman equation in case of both co- and counter-propagating frequencies

Parameters:

  • co_initial_guess_power – co-propagationg Raman first order derivative equation solution

  • cnt_initial_guess_power – counter-propagationg Raman first order derivative equation solution

  • co_frequency – co-propagationg frequencies

  • cnt_frequency – counter-propagationg frequencies

  • z – z position array

  • fiber – instance of gnpy.core.elements.Fiber or gnpy.core.elements.RamanFiber

  • lumped_losses – concentrated losses array along the fiber span

Returns:

co- and counter-propagatng power profile matrix

class gnpy.core.science_utils.StimulatedRamanScattering(power_profile, loss_profile, frequency, z)

Bases: object

gnpy.core.science_utils.estimate_nf_model(type_variety, gain_min, gain_max, nf_min, nf_max)
gnpy.core.science_utils.raised_cosine(frequency, channel_frequency, channel_baud_rate, channel_roll_off)

Returns a unitary raised cosine profile for the given parame

Parameters:

  • frequency – numpy array of frequencies in Hz for the resulting raised cosine

  • channel_frequency – channel frequencies in Hz

  • channel_baud_rate – channel baud rate in Hz

  • channel_roll_off – channel roll off

gnpy.core.utils

This module contains utility functions that are used with gnpy.

gnpy.core.utils.arrange_frequencies(length, start, stop)

Create an array of frequencies

Parameters:

  • length (integer) – number of elements

  • start (float) – Start frequency in THz

  • stop (float) – Stop frequency in THz

Returns:

an array of frequencies determined by the spacing parameter

Return type:

numpy.ndarray

gnpy.core.utils.automatic_fmax(f_min, spacing, nch)

Find the high-frequenecy boundary of a spectrum

:param f_min Start of the spectrum (lowest frequency edge) [Hz] :param spacing Grid/channel spacing [Hz] :param nch Number of channels :return End of the spectrum (highest frequency) [Hz]

>>> automatic_fmax(191.325e12, 50e9, 96)
196125000000000.0
gnpy.core.utils.automatic_nch(f_min, f_max, spacing)

How many channels are available in the spectrum

:param f_min Lowest frequenecy [Hz] :param f_max Highest frequency [Hz] :param spacing Channel width [Hz] :return Number of uniform channels

>>> automatic_nch(191.325e12, 196.125e12, 50e9)
96
>>> automatic_nch(193.475e12, 193.525e12, 50e9)
1
gnpy.core.utils.calculate_absolute_min_or_zero(x: array) → array

Calculates the element-wise absolute minimum between the x and zero.

Parameters: x (array): The first input array.

Returns: array: The element-wise absolute minimum between x and zero.

Example: >>> x = array([-1, 2, -3]) >>> calculate_absolute_min_or_zero(x) array([1., 0., 3.])

gnpy.core.utils.calculate_spacing(first: dict, second: dict, default_spacing: float, default_design_bands: List[Dict] | None, f_min: float, f_max: float) → float

Calculate the spacing for the given frequency range.

Parameters:

  • first (dict) – The first amplifier band dictionary.

  • second (dict) – The second amplifier band dictionary.

  • default_spacing (float) – The default spacing to use if no specific spacing can be determined.

  • default_design_bands (Union[List[Dict], None]) – Optional list of design bands to determine spacing from.

  • f_min (float) – The minimum frequency of the range.

  • f_max (float) – The maximum frequency of the range.

Returns:

The calculated spacing for the given frequency range.

Return type:

float

gnpy.core.utils.convert_empty_to_none(json_data: list | dict) → dict

Convert all instances of “a”: [None] into “a”: None

Parameters:

json_data (dict) – the input data.

Returns:

the converted data.

Return type:

dict

>>> json_data = {
...     "uid": "[east edfa in Lannion",
...     "type_variety": "multiband_booster",
...     "metadata": {
...         "location": {
...             "latitude": 0.000000,
...             "longitude": 0.000000,
...             "city": "Zion",
...             "region": ""
...         }
...     },
...     "type": "Multiband_amplifier",
...     "amplifiers": [{
...             "type_variety": "multiband_booster_LOW_C",
...             "operational": {
...                 "gain_target": 12.22,
...                 "delta_p": 4.19,
...                 "out_voa": [None],
...                 "tilt_target": 0.00,
...                 "f_min": 191.3,
...                 "f_max": 196.1
...             }
...         }, {
...             "type_variety": "multiband_booster_LOW_L",
...             "operational": {
...                 "gain_target": 12.05,
...                 "delta_p": 4.19,
...                 "out_voa": [None],
...                 "tilt_target": 0.00,
...                 "f_min": 186.1,
...                 "f_max": 190.9
...             }
...         }
...     ]
... }
>>> convert_empty_to_none(json_data)
{'uid': '[east edfa in Lannion', 'type_variety': 'multiband_booster', 'metadata': {'location': {'latitude': 0.0, 'longitude': 0.0, 'city': 'Zion', 'region': ''}}, 'type': 'Multiband_amplifier', 'amplifiers': [{'type_variety': 'multiband_booster_LOW_C', 'operational': {'gain_target': 12.22, 'delta_p': 4.19, 'out_voa': None, 'tilt_target': 0.0, 'f_min': 191.3, 'f_max': 196.1}}, {'type_variety': 'multiband_booster_LOW_L', 'operational': {'gain_target': 12.05, 'delta_p': 4.19, 'out_voa': None, 'tilt_target': 0.0, 'f_min': 186.1, 'f_max': 190.9}}]}
gnpy.core.utils.convert_length(value, units)

Convert length into basic SI units

>>> convert_length(1, 'km')
1000.0
>>> convert_length(2.0, 'km')
2000.0
>>> convert_length(123, 'm')
123.0
>>> convert_length(123.0, 'm')
123.0
>>> convert_length(42.1, 'km')
42100.0
>>> convert_length(666, 'yards')
Traceback (most recent call last):
    ...
gnpy.core.exceptions.ConfigurationError: Cannot convert length in "yards" into meters
gnpy.core.utils.convert_none_to_empty(json_data: list | dict) → dict

Convert all instances of “a”: None into “a”: [None], to be compliant with RFC7951.

Parameters:

json_data (dict) – the input data.

Returns:

the converted data.

Return type:

dict

>>> a = {'uid': '[east edfa in Lannion', 'type_variety': 'multiband_booster',
... 'metadata': {'location': {'latitude': 0.0, 'longitude': 0.0, 'city': 'Zion', 'region': ''}},
... 'type': 'Multiband_amplifier', 'amplifiers': [{'type_variety': 'multiband_booster_LOW_C',
... 'operational': {'gain_target': 12.22, 'delta_p': 4.19, 'out_voa': None, 'tilt_target': 0.0,
... 'f_min': 191.3, 'f_max': 196.1}}, {'type_variety': 'multiband_booster_LOW_L',
... 'operational': {'gain_target': 12.05, 'delta_p': 4.19, 'out_voa': None, 'tilt_target': 0.0,
... 'f_min': 186.1, 'f_max': 190.9}}]}
>>> convert_none_to_empty(a)
{'uid': '[east edfa in Lannion', 'type_variety': 'multiband_booster', 'metadata': {'location': {'latitude': 0.0, 'longitude': 0.0, 'city': 'Zion', 'region': ''}}, 'type': 'Multiband_amplifier', 'amplifiers': [{'type_variety': 'multiband_booster_LOW_C', 'operational': {'gain_target': 12.22, 'delta_p': 4.19, 'out_voa': [None], 'tilt_target': 0.0, 'f_min': 191.3, 'f_max': 196.1}}, {'type_variety': 'multiband_booster_LOW_L', 'operational': {'gain_target': 12.05, 'delta_p': 4.19, 'out_voa': [None], 'tilt_target': 0.0, 'f_min': 186.1, 'f_max': 190.9}}]}
gnpy.core.utils.convert_pmd_lineic(pmd: float | None, length: float, length_unit: str) → float | None

Convert PMD value of the span in ps into pmd_lineic in s/sqrt(km)

Parameters:

  • pmd (Union[float, None]) – value in ps

  • length (float) – value in length_unit

  • length_unit (str) – ‘km’ or ‘m’

Returns:

lineic PMD s/sqrt(m)

Return type:

Union[float, None]

>>> convert_pmd_lineic(10, 0.001, 'km')
1e-11
gnpy.core.utils.db2lin(value)

Convert logarithimic units to linear

>>> round(db2lin(10.0), 2)
10.0
>>> round(db2lin(20.0), 2)
100.0
>>> round(db2lin(1.0), 2)
1.26
>>> round(db2lin(0.0), 2)
1.0
>>> round(db2lin(-10.0), 2)
0.1
gnpy.core.utils.dbm2watt(value)

Convert dBm units to Watt

>>> round(dbm2watt(0), 4)
0.001
>>> round(dbm2watt(-3), 4)
0.0005
>>> round(dbm2watt(13), 4)
0.02
gnpy.core.utils.deltaf2deltawl(delta_f, frequency)

convert delta frequency to delta wavelength

Units for delta_wl and wavelength must be same.

Parameters:

  • delta_f (float or numpy.ndarray) – delta frequency in same units as frequency

  • frequency (float) – frequency BW is relevant for

Returns:

The BW in wavelength units

Return type:

float or ndarray

gnpy.core.utils.deltawl2deltaf(delta_wl, wavelength)

deltawl2deltaf(delta_wl, wavelength): delta_wl is BW in wavelength units wavelength is the center wl units for delta_wl and wavelength must be same

Parameters:

  • delta_wl (float or numpy.ndarray) – delta wavelength BW in same units as wavelength

  • wavelength (float) – wavelength BW is relevant for

Returns:

The BW in frequency units

Return type:

float or ndarray

gnpy.core.utils.filter_valid_amp_bands(amp_bands: List[List[dict]]) → List[List[dict]]

Filter out invalid amplifier bands that lack f_min or f_max.

Parameters:

amp_bands (List[List[dict]]) – A list of lists containing amplifier band dictionaries.

Returns:

A filtered list of amplifier bands that contain valid f_min and f_max.

Return type:

List[List[dict]]

gnpy.core.utils.find_common_range(amp_bands: List[List[dict]], default_band_f_min: float | None, default_band_f_max: float | None, default_spacing: float, default_design_bands: List[Dict] | None = None) → List[dict]

Find the common frequency range of amplifier bands.

If there are no amplifiers in the path, then use the default band parameters.

Parameters:

  • amp_bands (List[List[dict]]) – A list of lists containing amplifier band dictionaries, each with ‘f_min’, ‘f_max’, and optionally ‘spacing’.

  • default_band_f_min (Union[float, None]) – The minimum frequency of the default band.

  • default_band_f_max (Union[float, None]) – The maximum frequency of the default band.

  • default_spacing (float) – The default spacing to use if no specific spacing can be determined.

  • default_design_bands (Union[List[Dict], None]) – Optional list of design bands to determine spacing from.

Returns:

A list of dictionaries representing the common frequency ranges with their respective spacings.

Return type:

List[dict]

>>> amp_bands = [[{'f_min': 191e12, 'f_max' : 195e12, 'spacing': 70e9}, {'f_min': 186e12, 'f_max' : 190e12}],                      [{'f_min': 185e12, 'f_max' : 189e12}, {'f_min': 192e12, 'f_max' : 196e12}],                      [{'f_min': 186e12, 'f_max': 193e12}]]
>>> find_common_range(amp_bands, 190e12, 195e12, 50e9)
[{'f_min': 186000000000000.0, 'f_max': 189000000000000.0, 'spacing': 50000000000.0}, {'f_min': 192000000000000.0, 'f_max': 193000000000000.0, 'spacing': 70000000000.0}]

>>> amp_bands = [[{'f_min': 191e12, 'f_max' : 195e12}, {'f_min': 186e12, 'f_max' : 190e12}],                      [{'f_min': 185e12, 'f_max' : 189e12}, {'f_min': 192e12, 'f_max' : 196e12}],                      [{'f_min': 186e12, 'f_max': 192e12}]]
>>> find_common_range(amp_bands, 190e12, 195e12, 50e9)
[{'f_min': 186000000000000.0, 'f_max': 189000000000000.0, 'spacing': 50000000000.0}]
gnpy.core.utils.get_spacing_from_band(design_bands: List[Dict], f_min, f_max)

Retrieve the spacing for a frequency range based on design bands.

This function checks if the midpoint of the provided frequency range (f_min, f_max) falls within any of the design bands. If it does, the corresponding spacing is returned.

Parameters:

  • design_bands (List[Dict]) – A list of design band dictionaries, each containing ‘f_min’, ‘f_max’, and ‘spacing’.

  • f_min (float) – The minimum frequency of the range.

  • f_max (float) – The maximum frequency of the range.

Returns:

The spacing corresponding to the design band that contains the midpoint of the range, or None if no such band exists.

Return type:

Union[float, None]

gnpy.core.utils.lin2db(value)

Convert linear unit to logarithmic (dB)

>>> lin2db(0.001)
-30.0
>>> round(lin2db(1.0), 2)
0.0
>>> round(lin2db(1.26), 2)
1.0
>>> round(lin2db(10.0), 2)
10.0
>>> round(lin2db(100.0), 2)
20.0
gnpy.core.utils.merge_amplifier_restrictions(dict1, dict2)

Update contents of dicts recursively

>>> d1 = {'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}}}
>>> d2 = {'params': {'target_pch_out_db': -20}}
>>> merge_amplifier_restrictions(d1, d2)
{'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}, 'target_pch_out_db': -20}}

>>> d3 = {'params': {'restrictions': {'preamp_variety_list': ['foo'], 'booster_variety_list': ['bar']}}}
>>> merge_amplifier_restrictions(d1, d3)
{'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}}}
gnpy.core.utils.nice_column_str(data: List[List[str]], max_length: int = 30, padding: int = 1) → str

data is a list of rows, creates strings with nice alignment per colum and padding with spaces letf justified

>>> table_data = [['aaa', 'b', 'c'], ['aaaaaaaa', 'bbb', 'c'], ['a', 'bbbbbbbbbb', 'c']]
>>> print(nice_column_str(table_data))
aaa      b          c 
aaaaaaaa bbb        c 
a        bbbbbbbbbb c
gnpy.core.utils.order_slots(slots)

Order frequency slots from larger slots to smaller ones up to None

>>> l = [{'N': 3, 'M': None}, {'N': 2, 'M': 1}, {'N': None, 'M': None},{'N': 7, 'M': 2},{'N': None, 'M': 1} , {'N': None, 'M': 0}]
>>> order_slots(l)
([7, 2, None, None, 3, None], [2, 1, 1, 0, None, None], [3, 1, 4, 5, 0, 2])
gnpy.core.utils.per_label_average(values, labels)

computes the average per defined spectrum band, using labels

>>> labels = ['A', 'A', 'A', 'A', 'A', 'B', 'B', 'B', 'B', 'B', 'B', 'B', 'B', 'C', 'D', 'D', 'D', 'D']
>>> values = [28.51, 28.23, 28.15, 28.17, 28.36, 28.53, 28.64, 28.68, 28.7, 28.71, 28.72, 28.73, 28.74, 28.91, 27.96, 27.85, 27.87, 28.02]
>>> per_label_average(values, labels)
{'A': 28.28, 'B': 28.68, 'C': 28.91, 'D': 27.92}
gnpy.core.utils.power_dbm_to_psd_mw_ghz(power_dbm, baudrate_baud)

computes power spectral density in mW/GHz based on baudrate in bauds and power in dBm

>>> power_dbm_to_psd_mw_ghz(0, 64e9)
0.015625
>>> round(power_dbm_to_psd_mw_ghz(3, 64e9), 6)
0.031176
>>> round(power_dbm_to_psd_mw_ghz(3, 32e9), 6)
0.062352
gnpy.core.utils.pretty_summary_print(summary)

Build a prettty string that shows the summary dict values per label with 2 digits

gnpy.core.utils.psd2powerdbm(psd_mwperghz, baudrate_baud)

computes power in dBm based on baudrate in bauds and psd in mW/GHz

>>> round(psd2powerdbm(0.031176, 64e9),3)
3.0
>>> round(psd2powerdbm(0.062352, 32e9),3)
3.0
>>> round(psd2powerdbm(0.015625, 64e9),3)
0.0
gnpy.core.utils.psd_mw_per_ghz(power_watt, baudrate_baud)

computes power spectral density in mW/GHz based on baudrate in bauds and power in W

>>> psd_mw_per_ghz(2e-3, 32e9)
0.0625
>>> psd_mw_per_ghz(1e-3, 64e9)
0.015625
>>> psd_mw_per_ghz(0.5e-3, 32e9)
0.015625
gnpy.core.utils.remove_duplicates(amp_bands: List[List[dict]]) → List[List[dict]]

Remove duplicate amplifier bands.

Parameters:

amp_bands (List[List[dict]]) – A list of lists containing amplifier band dictionaries.

Returns:

A list of unique amplifier bands.

Return type:

List[List[dict]]

gnpy.core.utils.reorder_per_degree_design_bands(per_degree_design_bands: dict)

Sort the design bands for each degree by their minimum frequency (f_min).

This function modifies the input dictionary in place, sorting the design bands for each unique identifier.

Parameters:

per_degree_design_bands (Dict[str, List[Dict]]) – A dictionary where keys are unique identifiers and values are lists of design band dictionaries.

gnpy.core.utils.replace_none(dictionary)

Replaces None with inf values in a frequency slots dict

>>> replace_none({'N': 3, 'M': None})
{'N': 3, 'M': inf}
gnpy.core.utils.restore_order(elements, order)

Use order to re-order the element of the list, and ignore None values

>>> restore_order([7, 2, None, None, 3, None], [3, 1, 4, 5, 0, 2])
[3, 2, 7]
gnpy.core.utils.round2float(number, step)

Round a floating point number so that its “resolution” is not bigger than ‘step’

The finest step is fixed at 0.01; smaller values are silently changed to 0.01.

>>> round2float(123.456, 1000)
0.0
>>> round2float(123.456, 100)
100.0
>>> round2float(123.456, 10)
120.0
>>> round2float(123.456, 1)
123.0
>>> round2float(123.456, 0.1)
123.5
>>> round2float(123.456, 0.01)
123.46
>>> round2float(123.456, 0.001)
123.46
>>> round2float(123.249, 0.5)
123.0
>>> round2float(123.250, 0.5)
123.0
>>> round2float(123.251, 0.5)
123.5
>>> round2float(123.300, 0.2)
123.2
>>> round2float(123.301, 0.2)
123.4
gnpy.core.utils.rrc(ffs, baud_rate, alpha)

compute the root-raised cosine filter function

Parameters:

  • ffs (numpy.ndarray) – A numpy array of frequencies

  • baud_rate (float) – The Baud Rate of the System

  • alpha (float) – The roll-off factor of the filter

Returns:

hf a numpy array of the filter shape

Return type:

numpy.ndarray

gnpy.core.utils.silent_remove(this_list, elem)

Remove matching elements from a list without raising ValueError

>>> li = [0, 1]
>>> li = silent_remove(li, 1)
>>> li
[0]
>>> li = silent_remove(li, 1)
>>> li
[0]
gnpy.core.utils.snr_sum(snr, bw, snr_added, bw_added=12500000000.0)

Adding snr contributions

gnpy.core.utils.transform_data(data: str) → List[int] | None

Transforms a float into an list of one integer or a string separated by “|” into a list of integers.

Args:

data (float or str): The data to transform.

Returns:

list of int: The transformed data as a list of integers.

Examples:
>>> transform_data(5.0)
[5]

>>> transform_data('1 | 2 | 3')
[1, 2, 3]
gnpy.core.utils.unique_ordered(elements)
gnpy.core.utils.use_pmd_coef(dict1: dict, dict2: dict)

If Fiber dict1 is missing the pmd_coef value then use the one of dict2. In addition records in “pmd_coef_defined” key the pmd_coef if is was defined in dict1.

Parameters:

  • dict1 (dict) – A dictionnary that contains “pmd_coef” key.

  • dict2 (dict) – Another dictionnary that contains “pmd_coef” key.

>>> dict1 = {'a': 1, 'pmd_coef': 1.5e-15}
>>> dict2 = {'a': 2, 'pmd_coef': 2e-15}
>>> use_pmd_coef(dict1, dict2)
>>> dict1
{'a': 1, 'pmd_coef': 1.5e-15, 'pmd_coef_defined': True}

>>> dict1 = {'a': 1}
>>> use_pmd_coef(dict1, dict2)
>>> dict1
{'a': 1, 'pmd_coef_defined': False, 'pmd_coef': 2e-15}
gnpy.core.utils.watt2dbm(value)

Convert Watt units to dBm

>>> round(watt2dbm(0.001), 1)
0.0
>>> round(watt2dbm(0.02), 1)
13.0
gnpy.core.utils.write_csv(obj, filename)

Convert dictionary items to a CSV file the dictionary format:

{'result category 1':
                [
                # 1st line of results
                {'header 1' : value_xxx,
                 'header 2' : value_yyy},
                 # 2nd line of results: same headers, different results
                {'header 1' : value_www,
                 'header 2' : value_zzz}
                ],
'result_category 2':
                [
                {},{}
                ]
}

The generated csv file will be:

result_category 1
header 1    header 2
value_xxx   value_yyy
value_www   value_zzz
result_category 2
...