Merge "fix: image of the script and documentation"

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``
+``bit_rate``
-  Data bit rate, in :math:`\text{Gbits}\times s^{-1}`.
+  Data bit rate, in :math:`\text{bits}\times s^{-1}`.
-``baud-rate``
+``baud_rate``
-  Symbol modulation rate, in :math:`\text{Gbaud}`.
+  Symbol modulation rate, in :math:`\text{baud}`.
-``required-osnr``
+``OSNR``
-  Minimal allowed OSNR for the receiver.
+  Minimal required OSNR for the receiver. In :math:`\text{dB}`
 ``tx-osnr``
-  Initial OSNR at the transmitter's output.
+  Initial OSNR at the transmitter's output. In :math:`\text{dB}`
-``grid-spacing``
+``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``
+``penalties``
-  Maximal allowed Chromatic Dispersion (CD).
+  Impairments such as Chromatic Dispersion (CD), Polarization Mode Dispersion (PMD), and Polarization Dispersion Loss (PDL)
-  In :math:`\text{ps}/\text{nm}`.
+  result in penalties at the receiver. The receiver's ability to handle these impairments can be defined for each mode as
-``pmd-max``
+  a list of {impairment: in defined units, 'penalty_value' in dB} (see `transceiver section here <json.rst#_transceiver>`).
-  Maximal allowed Polarization Mode Dispersion (PMD).
+  Maximum allowed CD, maximum allowed PMD, and maximum allowed PDL should be listed there with corresponding penalties.
-  In :math:`\text{ps}`.
+  Impairments experienced during propagation are linearly interpolated between given points to obtain the corresponding penalty.
-``cd-penalty``
+  The accumulated penalties are subtracted from the path GSNR before comparing with the minimum required OSNR.
-  *Work-in-progress.*
+  Impairments: PMD in :math:`\text{ps}`, CD in :math:`\text{ps/nm}`, PDL in :math:`\text{dB}`, penalty_value in :math:`\text{dB}`
-  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.
 
 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 <json.rst#__roadm>`)
 ``pmd``
   Polarization mode dispersion (PMD) penalty of the express path.
   In :math:`\text{ps}`.

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
+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>`_
+`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 <../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 <../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 <docs/excel.rst>`__.
+Further details about the Excel data structure are available `in the documentation <excel.rst>`__.
 
 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 <docs/json.rst>`__ or `XLS <docs/excel.rst>`__ files.
+Simulations are driven by a set of `JSON <json.rst>`__ or `XLS <excel.rst>`__ 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 <gnpy/example-data/raman_edfa_example_network.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>`_.
+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 <docs/json.rst>`__ or `Excel <docs/excel.rst>`__ format), processing the list of service requests (JSON or XLS again).
+This program operates on a network topology (`JSON <json.rst>`__ or `Excel <excel.rst>`__ 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 <https://tools.ietf.org/html/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`.
 

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
 ~~~~~