diff --git a/docs/json.rst b/docs/json.rst index 5c708d8c9..0695cec9b 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 corresponding to an amplification site composed of multiple amplifier elements, where each amplifies a different band of the spectrum. + The ``amplifiers`` list contains the list of single-band amplifier type varieties that can compose such multiband + amplifiers. Several options can be listed for the same spectrum band. Only one can be selected + 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). @@ -751,6 +779,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 | @@ -817,6 +849,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 used. +Each set defines a reference channel used for design functions and autodesign processes. + +If no spectrum is defined (--spectrum or --services), then the same type of reference channel is +also used for simulation. + + .. _mixed-rate: Arbitrary channel definition @@ -867,7 +906,7 @@ For example this example: .. code-block:: json { - "SI":[ + "spectrum":[ { "f_min": 191.4e12, "f_max":193.1e12, @@ -878,7 +917,7 @@ For example this example: }, { "f_min": 193.1625e12, - "f_max":195e12, + "f_max": 195e12, "baud_rate": 64e9, "delta_pdb": 3, "slot_width": 75e9, @@ -1124,6 +1163,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 | +======================+===========+==================================================+ @@ -1179,6 +1220,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 bands of each individual amplifier contained in +the Multiband_amplifier element. Only carriers within these bands are propagated through the Multiband_amplifier +element. If the user defines a spectrum larger than these bands, carriers that do not match the bands will be +filtered out. The user can define the bandwidth of the amplifiers in the library. f_min and f_max represent the +bandwidth of the amplifier (the entire channel must fit). The individual amplifier type_variety must be part of the +allowed ``amplifiers`` list defined in the library. + Roadm ~~~~~ @@ -1210,32 +1308,69 @@ 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 +from those that have ``multi_band`` ``type_def`` amplifiers. + +The default ``design_bands`` is inferred from the :ref:`SI` block. + +Note that ``design_bands`` and ``type_variety`` amplifiers must be consistent: +- you cannot mix single band and multiband amplifiers on the same OMS; +- the frequency range of the amplifiers must include ``design_bands``. + Fused ~~~~~ @@ -1245,7 +1380,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..0f9a10f3d 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -6,6 +6,200 @@ 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 site composed of several amplifiers per band (a typical application is C+L transmission). The +release also includes autodesign for links (Optical Multiplex Section, OMS) composed of multi_band amplifiers. +Multi_band autodesign includes basic tilt and tilt_target calculation when the Raman flag is enabled with the +--sim-params option. The spectrum is demultiplexed before propagation in 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** + +Optionally, users can define a 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 the SI block instead of a single Spectrum Information. +In this case type_variety must be used. +Each set defines a reference channel used for design functions and autodesign. + +The default design settings for the path-request-run script have been modified. +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 (no amplifier defined in the OMS, no design_bands attribute in the ROADM), then +it uses single band Edfas. + +**Propagation** + +Only carriers within the amplifier bandwidth are propagated, improving system coherence. This more rigorous checking +of the spectrum to be propagated and the amplifier bandwidth may lead to changes in the total number of channels +compared to previous releases. The range can be adjusted by changing the values ​​of ``f_min`` and ``f_max`` +in the amplifier library. + + +``f_min`` and ``f_max`` represent the boundary frequencies of the 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 + + +**New feature** + +The preturbative Raman and the approximated GGN models are introduced for a faster evaluation of the Raman and +Kerr effects, respectively. +These implementation are intended to reduce the computational effort required by multiband transmission scenarios. + +Both the novel models have been validated with exstensive simulations +(see `arXiv:2304.11756 `_ for the new Raman model and +`jlt:9741324 `_ for the new NLI model). +Additionally, they have been experimentally validated in a laboratory setup composed of commertial equipment +(see `icton:10648172 `_). + + +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.