diff --git a/docs/extending.rst b/docs/extending.rst index 6ac4fd6a..7720e4b3 100644 --- a/docs/extending.rst +++ b/docs/extending.rst @@ -119,38 +119,32 @@ A *mode* usually refers to a particular performance point that is defined by a c The following data are required for each mode: -``bit-rate`` - Data bit rate, in :math:`\text{Gbits}\times s^{-1}`. -``baud-rate`` - Symbol modulation rate, in :math:`\text{Gbaud}`. -``required-osnr`` - Minimal allowed OSNR for the receiver. +``bit_rate`` + Data bit rate, in :math:`\text{bits}\times s^{-1}`. +``baud_rate`` + Symbol modulation rate, in :math:`\text{baud}`. +``OSNR`` + Minimal required OSNR for the receiver. In :math:`\text{dB}` ``tx-osnr`` - Initial OSNR at the transmitter's output. -``grid-spacing`` + Initial OSNR at the transmitter's output. In :math:`\text{dB}` +``min-spacing`` Minimal grid spacing, i.e., an effective channel spectral bandwidth. In :math:`\text{Hz}`. -``tx-roll-off`` +``roll-off`` Roll-off parameter (:math:`\beta`) of the TX pulse shaping filter. This assumes a raised-cosine filter. ``rx-power-min`` and ``rx-power-max`` - The allowed range of power at the receiver. + (work in progress) The allowed range of power at the receiver. In :math:`\text{dBm}`. -``cd-max`` - Maximal allowed Chromatic Dispersion (CD). - In :math:`\text{ps}/\text{nm}`. -``pmd-max`` - Maximal allowed Polarization Mode Dispersion (PMD). - In :math:`\text{ps}`. -``cd-penalty`` - *Work-in-progress.* - Describes the increase of the requires GSNR as the :abbr:`CD (Chromatic Dispersion)` deteriorates. -``dgd-penalty`` - *Work-in-progress.* - Describes the increase of the requires GSNR as the :abbr:`DGD (Differential Group Delay)` deteriorates. -``pmd-penalty`` - *Work-in-progress.* - Describes the increase of the requires GSNR as the :abbr:`PMD (Polarization Mode Dispersion)` deteriorates. +``penalties`` + Impairments such as Chromatic Dispersion (CD), Polarization Mode Dispersion (PMD), and Polarization Dispersion Loss (PDL) + result in penalties at the receiver. The receiver's ability to handle these impairments can be defined for each mode as + a list of {impairment: in defined units, 'penalty_value' in dB} (see `transceiver section here `). + Maximum allowed CD, maximum allowed PMD, and maximum allowed PDL should be listed there with corresponding penalties. + Impairments experienced during propagation are linearly interpolated between given points to obtain the corresponding penalty. + The accumulated penalties are subtracted from the path GSNR before comparing with the minimum required OSNR. + Impairments: PMD in :math:`\text{ps}`, CD in :math:`\text{ps/nm}`, PDL in :math:`\text{dB}`, penalty_value in :math:`\text{dB}` + GNPy does not directly track the FEC performance, so the type of chosen FEC is likely indicated in the *name* of the selected transponder mode alone. @@ -168,6 +162,7 @@ The set of parameters for each ROADM model therefore includes: Per-channel target TX power towards the egress amplifier. Within GNPy, a ROADM is expected to attenuate any signal that enters the ROADM node to this level. This can be overridden on a per-link in the network topology. + Targets can be set using power or power spectral density (see `roadm section here `) ``pmd`` Polarization mode dispersion (PMD) penalty of the express path. In :math:`\text{ps}`. diff --git a/docs/intro.rst b/docs/intro.rst index 64119dcc..2a983163 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -14,28 +14,29 @@ fully-functional programs. specific, delineated use cases to drive requirements for future development.* -This example demonstrates how GNPy can be used to check the expected SNR at the end of the line by varying the channel input power: +This example demonstrates how GNPy can be used to check the expected SNR at the end of the line by varying the channel input power, +or to run a planning script to check SNR of several services: -.. image:: https://telecominfraproject.github.io/oopt-gnpy/docs/images/transmission_main_example.svg +.. image:: images/gnpy-transmission-example.svg :width: 100% :align: left :alt: Running a simple simulation example -By default, this script operates on a single span network defined in -`gnpy/example-data/edfa_example_network.json `_ +By default, the gnpy-transmission-example script operates on a single span network defined in +`gnpy/example-data/edfa_example_network.json <../gnpy/example-data/edfa_example_network.json>`_ You can specify a different network at the command line as follows. For example, to use the CORONET Global network defined in -`gnpy/example-data/CORONET_Global_Topology.json `_: +`gnpy/example-data/CORONET_Global_Topology.json <../gnpy/example-data/CORONET_Global_Topology.json>`_: .. code-block:: shell-session $ gnpy-transmission-example $(gnpy-example-data)/CORONET_Global_Topology.json It is also possible to use an Excel file input (for example -`gnpy/example-data/CORONET_Global_Topology.xls `_). +`gnpy/example-data/CORONET_Global_Topology.xls <../gnpy/example-data/CORONET_Global_Topology.xls>`_). The Excel file will be processed into a JSON file with the same prefix. -Further details about the Excel data structure are available `in the documentation `__. +Further details about the Excel data structure are available `in the documentation `__. The main transmission example will calculate the average signal OSNR and SNR across network elements (transceiver, ROADMs, fibers, and amplifiers) @@ -56,7 +57,7 @@ interference noise. Further Instructions for Use ---------------------------- -Simulations are driven by a set of `JSON `__ or `XLS `__ files. +Simulations are driven by a set of `JSON `__ or `XLS `__ files. The ``gnpy-transmission-example`` script propagates a spectrum of channels at 32 Gbaud, 50 GHz spacing and 0 dBm/channel. Launch power in fiber spans can be overridden by using the ``--power`` argument. @@ -71,8 +72,8 @@ An experimental support for Raman amplification is available: $(gnpy-example-data)/raman_edfa_example_network.json \ --sim $(gnpy-example-data)/sim_params.json --show-channels -Configuration of Raman pumps (their frequencies, power and pumping direction) is done via the `RamanFiber element in the network topology `_. -General numeric parameters for simulation control are provided in the `gnpy/example-data/sim_params.json `_. +Configuration of Raman pumps (their frequencies, power and pumping direction) is done via the `RamanFiber element in the network topology <../gnpy/example-data/raman_edfa_example_network.json>`_. +General numeric parameters for simulation control are provided in the `gnpy/example-data/sim_params.json <../gnpy/example-data/sim_params.json>`_. Use ``gnpy-path-request`` to request several paths at once: @@ -82,7 +83,7 @@ Use ``gnpy-path-request`` to request several paths at once: $ gnpy-path-request -o output_file.json \ meshTopologyExampleV2.xls meshTopologyExampleV2_services.json -This program operates on a network topology (`JSON `__ or `Excel `__ format), processing the list of service requests (JSON or XLS again). +This program operates on a network topology (`JSON `__ or `Excel `__ format), processing the list of service requests (JSON or XLS again). The service requests and reply formats are based on the `draft-ietf-teas-yang-path-computation-01 `__ with custom extensions (e.g., for transponder modes). An example of the JSON input is provided in file `service-template.json`, while results are shown in `path_result_template.json`. diff --git a/docs/json.rst b/docs/json.rst index 6098c10c..6e536e6b 100644 --- a/docs/json.rst +++ b/docs/json.rst @@ -154,6 +154,8 @@ it is suggested to include an estimation of the loss coefficient for the Raman p a dictionary-like definition of the ``RamanFiber.params.loss_coef`` (e.g. ``loss_coef = {"value": [0.18, 0.18, 0.20, 0.20], "frequency": [191e12, 196e12, 200e12, 210e12]}``). +.. _transceiver: + Transceiver ~~~~~~~~~~~ @@ -235,6 +237,8 @@ for example: } ] +.. _roadm: + ROADM ~~~~~