From 688d1b8a571dd686359f7d3802aa974deb576bba Mon Sep 17 00:00:00 2001 From: EstherLerouzic Date: Mon, 21 Oct 2024 09:17:26 +0200 Subject: [PATCH] Add documentation for multiband Signed-off-by: EstherLerouzic Change-Id: Iadf6d9edd8c67c1389c4a0d482466a8c52198621 --- docs/json.rst | 184 +++++++++++++++++++++++++++++++++++------ docs/release-notes.rst | 182 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 339 insertions(+), 27 deletions(-) diff --git a/docs/json.rst b/docs/json.rst index ddc0bdd06..d16fb0e2c 100644 --- a/docs/json.rst +++ b/docs/json.rst @@ -19,7 +19,7 @@ EDFA ~~~~ The EDFA equipment library is a list of supported amplifiers. New amplifiers -can be added and existing ones removed. Three different noise models are available: +can be added and existing ones removed. Various noise models are available. 1. ``'type_def': 'variable_gain'`` is a simplified model simulating a 2-coil EDFA with internal, input and output VOAs. The NF vs gain response is calculated accordingly based on the input parameters: ``nf_min``, ``nf_max``, and ``gain_flatmax``. @@ -35,8 +35,12 @@ can be added and existing ones removed. Three different noise models are availab A detailed JSON configuration file is required (by default `gnpy/example-data/std_medium_gain_advanced_config.json `_). It uses a 3rd order polynomial where NF = f(gain), NF_ripple = f(frequency), gain_ripple = f(frequency), N-array dgt = f(frequency). Compared to the previous models, NF ripple and gain ripple are modelled. +6. ``'type_def': 'multi_band'`` defines an amplifier type composed of several amplifiers that amplify different spectrum bands. + The ``amplifiers`` list contains the list of single band amplifier type varieties that are allowed to compose such a multi + band amplifiers. It is possible to list several options for a same spectrum band. Only one can be sectlected + for the actual :ref:`Multiband_amplifier` element. -For all amplifier models: +For all single band amplifier models: +------------------------+-----------+-----------------------------------------+ | field | type | description | @@ -55,6 +59,30 @@ For all amplifier models: | | | be used as a manual input (from JSON or | | | | Excel template topology files.) | +------------------------+-----------+-----------------------------------------+ +| ``f_min`` | (number) | Optional. In :math:`Hz`. Minimum and | +| and ``f_max`` | | maximum frequency range for the | +| | | amplifier. Signal must fit entirely | +| | | within this range (center frequency and | +| | | spectrum width). | +| | | Default is 191.275e-12 Hz and | +| | | 196.125e-12 (tunable in | +| | | default_edfa_config.json) | ++------------------------+-----------+-----------------------------------------+ + + +For multi_band amplifier models: + ++------------------------+-----------+-----------------------------------------+ +| field | type | description | ++========================+===========+=========================================+ +| ``type_variety`` | (string) | A unique name to ID the amplifier in the| +| | | JSON template topology input file. | ++------------------------+-----------+-----------------------------------------+ +| ``allowed_for_design`` | (boolean) | If false, the amplifier will not be | +| | | picked by auto-design but it can still | +| | | be used as a manual input (from JSON or | +| | | Excel template topology files.) | ++------------------------+-----------+-----------------------------------------+ Fiber ~~~~~ @@ -447,14 +475,14 @@ Here is an example: "uid": "roadm SITE1", "type": "Roadm", "type_variety": "detailed_impairments", - "params": { - "per_degree_impairments": [ - { - "from_degree": "trx SITE1", - "to_degree": "east edfa in SITE1 to ILA1", - "impairment_id": 1 - }] - } + "params": { + "per_degree_impairments": [ + { + "from_degree": "trx SITE1", + "to_degree": "east edfa in SITE1 to ILA1", + "impairment_id": 1 + }] + } } It is not permitted to use a roadm-path-impairment-id for the wrong roadm path type (add impairment only for add path). @@ -727,6 +755,10 @@ In the simplest case, homogeneous channel allocation can be defined via the ``Sp +----------------------+-----------+-------------------------------------------+ | field | type | description | +======================+===========+===========================================+ +| ``type_variety`` | (string) | Optional. Default: ``default`` | +| | | A unique name to ID the band for | +| | | propagation or design. | ++----------------------+-----------+-------------------------------------------+ | ``f_min``, | (number) | In Hz. Define spectrum boundaries. Note | | ``f_max`` | | that due to backward compatibility, the | | | | first channel central frequency is placed | @@ -793,6 +825,13 @@ In the simplest case, homogeneous channel allocation can be defined via the ``Sp | | | transceiver OSNR. | +----------------------+-----------+-------------------------------------------+ +It is possible to define a set of bands in the SI block. In this case, type_variety must be use. +Each set defines a reference channel used for design functions and autodesign processes. + +If no spectrum is defined (--spectrum, or services) that the same channel type is +used for the simulation + + .. _mixed-rate: Arbitrary channel definition @@ -843,7 +882,7 @@ For example this example: .. code-block:: json { - "SI":[ + "spectrum":[ { "f_min": 191.4e12, "f_max":193.1e12, @@ -854,7 +893,7 @@ For example this example: }, { "f_min": 193.1625e12, - "f_max":195e12, + "f_max": 195e12, "baud_rate": 64e9, "delta_pdb": 3, "slot_width": 75e9, @@ -1100,6 +1139,8 @@ the maximum achievable total power. The exact layout used by simulation can be retrieved thanks to --save-network option. +.. _operational_field: + +----------------------+-----------+--------------------------------------------------+ | field | type | description | +======================+===========+==================================================+ @@ -1155,6 +1196,63 @@ The exact layout used by simulation can be retrieved thanks to --save-network op } } +.. _multiband_amps: + +Multiband_amplifier attributes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+-----------+--------------------------------------------------+ +| field | type | description | ++======================+===========+==================================================+ +| ``type`` | (string) | Mandatory: ``Multiband_amplifier`` | ++----------------------+-----------+--------------------------------------------------+ +| ``type_variety`` | (string) | Optional, value must be listed in the library | +| | | to be a valid type. If not defined, autodesign | +| | | will pick one in the library among the | +| | | ``allowed_for_design``. | ++----------------------+-----------+--------------------------------------------------+ +| ``amplifiers`` | (list of | Optional, configuration settings of the | +| | dict) | amplifiers composing the multiband amplifier. | +| | | Single band amplifier can be set with the | +| | | parameters of tables: | +| | | :ref:`operational_field`: | ++----------------------+-----------+--------------------------------------------------+ + +Example of Multiband_amplifier element setting: + + .. code-block:: json + + { + "uid": "east edfa in Site_A to Site_B", + "type": "Multiband_amplifier", + "type_variety": "std_medium_gain_multiband", + "amplifiers": [{ + "type_variety": "std_medium_gain_C", + "operational": { + "gain_target": 22.55, + "delta_p": 0.9, + "out_voa": 3.0, + "tilt_target": 0.0 + } + }, { + "type_variety": "std_medium_gain_L", + "operational": { + "gain_target": 21, + "delta_p": 3.0, + "out_voa": 3.0, + "tilt_target": 0.0 + } + } + ] + } + +The frequency band of the element is the concatenation of the individual amplifier's band composing +the Multiband_amplifier element. Only carriers within these bands are propagated through the Multiband_amplifier +element. If user defines a spectrum larger than these bands, carriers not matching the bands willbe filterred out. +User can define amplifiers +bandwidth in the library . f_min and f_max represent amplifier band (the entire channel must fit within). +Individual amplifier type_vaiety must be part of the allowed ``amplifiers`` list defined in the library. + Roadm ~~~~~ @@ -1186,32 +1284,70 @@ Roadm | | dict) | defined, it overrides the general values defined | | | | by type_variety. | +----------------------------------------+-----------+----------------------------------------------------+ +| ``design_bands`` | (list of | Optional. List of bands expressed as dictionnary, | +| | dict) | e.g. {"f_min": 191.3e12, "f_max": 195.1e12} | +| | | To be considered for autodesign on all degrees of | +| | | the ROADM, if nothing is defined on the degrees. | ++----------------------------------------+-----------+----------------------------------------------------+ +| ``per_degree_design_bands`` | (dict of | Optional. If defined, it overrides ROADM's general | +| | string, | design_bands, on the degree identified with the | +| | list of | key string. Value is a list of bands defined by | +| | dict) | their frequency bounds ``f_min`` and ``f_max`` | +| | | expressed in THz. | ++----------------------------------------+-----------+----------------------------------------------------+ + Definition example: -.. code-block:: json + .. code-block:: json { "uid": "roadm SITE1", "type": "Roadm", "type_variety": "detailed_impairments", - "params": { - "per_degree_impairments": [ - { - "from_degree": "trx SITE1", - "to_degree": "east edfa in SITE1 to ILA1", - "impairment_id": 1 - }], - "per_degree_pch_out_db": { + "params": { + "per_degree_impairments": [ + { + "from_degree": "trx SITE1", + "to_degree": "east edfa in SITE1 to ILA1", + "impairment_id": 1 + }], + "per_degree_pch_out_db": { "east edfa in SITE1 to ILA1": -13.5 - } - } + } + } } In this example, all «implicit» express roadm-path are assigned as roadm-path-impairment-id = 0, and the target power is set according to the value defined in the library except for the direction heading to "east edfa in SITE1 to ILA1", where constant power equalization is used to reach -13.5 dBm target power. + .. code-block:: json + + { + "uid": "roadm SITE1", + "type": "Roadm", + "params": { + "per_degree_design_bands": { + "east edfa in SITE1 to ILA1": [ + {"f_min": 191.3e12, "f_max": 196.0e12}, + {"f_min": 187.0e12, "f_max": 190.0e12} + ] + } + } + } + +In this example the OMS starting from east edfa in SITE1 to ILA1 is defined as a multiband OMS. This means that +If there is no setting in all or some of the amplifiers in the OMS, the autodesign function will select +amplifiers among those which have ``multi_band`` amplifiers ``type_def``. + +Default ``design_bands`` is inferred from the :ref:`SI` block. + +Note that ``design_bands`` and amplifiers' ``type_variety`` must be consistent: + + - it is not possible to mix single band and multi band amplifiers on the same OMS ; + - amplifiers' frequency range must encompass ``design_bands``. + Fused ~~~~~ @@ -1221,7 +1357,7 @@ A fused element connected to the egress of a ROADM will disable the automatic bo Fused ``params`` only contains a ``loss`` value in dB. -.. code-block:: json + .. code-block:: json "params": { "loss": 2 diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 7a3d70288..a569ecd63 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -6,6 +6,182 @@ Release change log Each release introduces some changes and new features. (prepare text for next release) + +v2.11 +----- + +**New feature** + +A new type_def for amplifiers has been introduced: multi_band. This allows the definition of a +multiband amplifier composed of several amplifiers per band (a typical application is C+L). The +release also includes autodesign for links (Optical Multiplex Section, OMS) composed of +multi_band amplifiers. The multi_band autodesign includes basic tilt and tilt_target computation +when the Raman flag is enabled with the --sim-params option. The spectrum is demultiplexed before +propagation into the amplifier and multiplexed in the output fiber at the amplifier output. + +In the library: + + .. code-block:: json + + { + "type_variety": "std_medium_gain_C", + "f_min": 191.225e12, + "f_max": 196.125e12, + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 21, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": false + }, + { + "type_variety": "std_medium_gain_L", + "f_min": 186.5e12, + "f_max": 190.1e12, + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 21, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": true + }, + { + "type_variety": "std_medium_gain_multiband", + "type_def": "multi_band", + "amplifiers": [ + "std_medium_gain_C", + "std_medium_gain_L" + ], + "allowed_for_design": false + }, + +In the network topology: + + .. code-block:: json + + { + "uid": "east edfa in Site_A to Site_B", + "type": "Multiband_amplifier", + "type_variety": "std_medium_gain_multiband", + "amplifiers": [{ + "type_variety": "std_medium_gain_C", + "operational": { + "gain_target": 22.55, + "delta_p": 0.9, + "out_voa": 3.0, + "tilt_target": 0.0 + } + }, { + "type_variety": "std_medium_gain_L", + "operational": { + "gain_target": 21, + "delta_p": 3.0, + "out_voa": 3.0, + "tilt_target": 0.0 + } + } + ] + } + +**Network design** + +Users can optionally define design target per OMS (single or multi_band), with specific frequency ranges. +Default design bands are defined in the SI. + + .. code-block:: json + + { + "uid": "roadm Site_A", + "type": "Roadm", + "params": { + "target_pch_out_db": -20, + "design_bands": [{"f_min": 191.3e12, "f_max": 195.1e12}] + } + } + +It is possible to define a set of bands in SI block instead of a unique Spectrum Information. +In this case type_variety must be use. +Each set defines a reference channel used for design functions and autodesign. + +The default design settings has been modifiedfor path-request-run script. +Now, design is performed once for the reference channel defined in the SI block of the eqpt_config, +and requests are propagated based on this design. +The --redesign-per-request option can be used to restore previous behaviour +(design using request channel types). + +The autodesign function has been updated to insert multiband booster, preamp or inline amplifiers based on the OMS +nature. If nothing is stated, then it uses Edfas. + +**Propagation** + +Only carriers within amplifier bandwidth are propagated, enhancing system consistency. This stricter verification +of the spectrum to be propagated and the amplifiers' bandwidth may lead to changes in the total number of channels +compared to previous releases. It is possible to adjust the range by adjusting ``f_min`` and ``f_max`` in the +amplifier library. + +``f_min`` and ``f_max`` represent amplification bandwidth (the entire channel must fit within this range). +In the example below, a signal center frequency of 190.05THz with a 50GHz width cannot fit within the amplifier band. +Note that this has a different meaning in the SI or Transceiver blocks, where ``f_min`` and ``f_max`` refers to the +minimum / maximum values of the carrier center frequency. + + .. code-block:: json + + { + "type_variety": "std_booster_L", + "f_min": 186.55e12, + "f_max": 190.05e12, + "type_def": "fixed_gain", + "gain_flatmax": 21, + "gain_min": 20, + "p_max": 21, + "nf0": 5, + "allowed_for_design": false + } + + +**Display** + +The CLI output for the transmission_main_example now displays the channels used for design and simulation, +as well as the tilt target of amplifiers. + + .. code-block:: text + + Reference used for design: (Input optical power reference in span = 0.00dBm, + spacing = 50.00GHz + nb_channels = 76) + + Channels propagating: (Input optical power deviation in span = 0.00dB, + spacing = 50.00GHz, + transceiver output power = 0.00dBm, + nb_channels = 76) + +The CLI output displays the settings of each amplifier: + + .. code-block:: text + + Multiband_amplifier east edfa in Site_A to Site_B + type_variety: std_medium_gain_multiband + type_variety: std_medium_gain_C type_variety: std_medium_gain_L + effective gain(dB): 20.90 effective gain(dB): 22.19 + (before att_in and before output VOA) (before att_in and before output VOA) + tilt-target(dB) 0.00 tilt-target(dB) 0.00 + noise figure (dB): 6.38 noise figure (dB): 6.19 + (including att_in) (including att_in) + pad att_in (dB): 0.00 pad att_in (dB): 0.00 + Power In (dBm): -1.08 Power In (dBm): -1.49 + Power Out (dBm): 19.83 Power Out (dBm): 20.71 + Delta_P (dB): 0.90 Delta_P (dB): 2.19 + target pch (dBm): 0.90 target pch (dBm): 3.00 + actual pch out (dBm): -2.09 actual pch out (dBm): -0.80 + output VOA (dB): 3.00 output VOA (dB): 3.00 + +v2.10 +----- + ROADM impairments can be defined per degree and roadm-path type (add, drop or express). Minimum loss when crossing a ROADM is no more 0 dB. It can be set per ROADM degree with roadm-path-impairments. @@ -225,15 +401,15 @@ involute manner to get a vanishing beta3 , and this was a mere artifact for NLI beta2 and beta3, not for total dispersion accumulation). Now, the evaluation of beta2 and beta3 is performed explicitly in the element.py module. -2. The effective area is provided as a scalar value evaluated at the Fiber reference frequency and properly scaled +1. The effective area is provided as a scalar value evaluated at the Fiber reference frequency and properly scaled considering the Fiber refractive indices n1 and n2, and the core radius. These quantities are assumed to be fixed and are hard coded in the parameters.py module. Essential change: The effective area is always scaled along the frequency. -3. The Raman gain coefficient is properly scaled considering the overlapping of fiber effective area values scaled at +1. The Raman gain coefficient is properly scaled considering the overlapping of fiber effective area values scaled at the interacting frequencies. Essential change: In previous version the Raman gain coefficient depends only on the frequency offset. -4. The nonlinear coefficient ``'gamma'`` is properly scaled considering the refractive index n2 and the scaling +1. The nonlinear coefficient ``'gamma'`` is properly scaled considering the refractive index n2 and the scaling effective area. Essential change: As the effective area, the nonlinear coefficient is always scaled along the frequency.