scottk/oopt-gnpy
1
0
Fork 0
mirror of https://github.com/Telecominfraproject/oopt-gnpy.git synced 2025-10-30 17:47:50 +00:00
Code Issues Packages Projects Releases 10 Wiki Activity

fix documentation: harmonize titles

Browse Source 
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I827b4dcd1418017d925b63e50f95514dc1a0eed8
This commit is contained in:
EstherLerouzic
2025-02-14 14:06:13 +01:00
parent 689c2fb038
commit d5491c9ace
13 changed files with 120 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/amplifier_models_description.rst
View File

@@ -1,11 +1,12 @@
.. _amp_models: .. _amp_models:
Amplifier models and configuration **********************************
================================== Amplifier models and Configuration
**********************************
1. Equipment configuration description 1. Equipment configuration description
-------------------------------------- ======================================
Equipment description defines equipment types and parameters. Equipment description defines equipment types and parameters.
It takes place in the equipment library such as **eqpt_config.json** file defined in example-data folder. It takes place in the equipment library such as **eqpt_config.json** file defined in example-data folder.
@@ -13,7 +14,7 @@ By default **gnpy-transmission-example** uses **eqpt_config.json** file and that
can be changed with **-e** or **--equipment** command line parameter. can be changed with **-e** or **--equipment** command line parameter.
2. Amplifier parameters and subtypes 2. Amplifier parameters and subtypes
------------------------------------ ====================================
Several amplifiers can be used by GNpy, so they are defined as an array of equipment parameters in **eqpt_config.json** file. Several amplifiers can be used by GNpy, so they are defined as an array of equipment parameters in **eqpt_config.json** file.
@@ -143,7 +144,7 @@ Several amplifiers can be used by GNpy, so they are defined as an array of equip
3. Amplifier models 3. Amplifier models
------------------- ===================
In an opensource and multi-vendor environnement, it is needed to support different use cases and context. Therefore several models are supported for amplifiers. In an opensource and multi-vendor environnement, it is needed to support different use cases and context. Therefore several models are supported for amplifiers.
@@ -282,7 +283,7 @@ In an opensource and multi-vendor environnement, it is needed to support differe
4. advanced_config_from_json 4. advanced_config_from_json
---------------------------- ============================
The build_oa_json.py library in ``gnpy/example-data/edfa_model/`` can be used to build the json file required for the amplifier advanced_model type_def: The build_oa_json.py library in ``gnpy/example-data/edfa_model/`` can be used to build the json file required for the amplifier advanced_model type_def:
@@ -315,4 +316,3 @@ the json input file should have the following fields:
"gain_ripple": "DFG_filename.txt", "gain_ripple": "DFG_filename.txt",
"dgt": "DGT_filename.txt" "dgt": "DGT_filename.txt"
} }

41
docs/cli_options.rst
View File

@@ -1,13 +1,14 @@
.. _cli-options: .. _cli-options:
Options Documentation for `gnpy-path-request` and `gnpy-transmission-example` ***********************************************************
============================================================================= `gnpy-path-request` and `gnpy-transmission-example` scripts
***********************************************************
Common options Common options
-------------- ==============
**Option**: `--no-insert-edfas` **Option**: `--no-insert-edfas`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
**Purpose**: Disables the automatic insertion of EDFAs after ROADMs and fibers, as well as the splitting **Purpose**: Disables the automatic insertion of EDFAs after ROADMs and fibers, as well as the splitting
of fibers during the auto-design process. of fibers during the auto-design process.
@@ -37,7 +38,7 @@ When the `--no-insert-edfas` option is specified:
**Option**: `--equipment`, `-e` **Option**: `--equipment`, `-e`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
**Description**: Specifies the equipment library file. **Description**: Specifies the equipment library file.
@@ -52,7 +53,7 @@ When the `--no-insert-edfas` option is specified:
**Functionality**: This option allows users to load a specific equipment configuration that defines the characteristics of the network elements. **Functionality**: This option allows users to load a specific equipment configuration that defines the characteristics of the network elements.
**Option**: `--extra-equipment` and `--extra-config` **Option**: `--extra-equipment` and `--extra-config`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------------
The `--extra-equipment` and `--extra-config` options allow users to extend the default equipment library and configuration The `--extra-equipment` and `--extra-config` options allow users to extend the default equipment library and configuration
settings used by the GNPy program. This feature is particularly useful for users who need to incorporate additional settings used by the GNPy program. This feature is particularly useful for users who need to incorporate additional
@@ -98,8 +99,6 @@ equipment types or specific configurations that are not included in the standard
The program will load the configurations from the specified files and consider them instead of the The program will load the configurations from the specified files and consider them instead of the
default configurations for the amplifiers that use the "default_config_from_json" or "advanced_config_from_json" keywords. default configurations for the amplifiers that use the "default_config_from_json" or "advanced_config_from_json" keywords.
Example
-------
To run the program with additional equipment and configuration files, you can use the following command: To run the program with additional equipment and configuration files, you can use the following command:
.. code-block:: shell-session .. code-block:: shell-session
@@ -116,7 +115,7 @@ In this example:
**Option**: `--save-network` **Option**: `--save-network`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
**Description**: Saves the final network configuration to a specified JSON file. **Description**: Saves the final network configuration to a specified JSON file.
@@ -130,7 +129,7 @@ In this example:
**Option**: `--save-network-before-autodesign` **Option**: `--save-network-before-autodesign`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
**Description**: Dumps the network into a JSON file prior to autodesign. **Description**: Dumps the network into a JSON file prior to autodesign.
@@ -144,7 +143,7 @@ In this example:
**Option**: `--sim-params` **Option**: `--sim-params`
~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------
**Description**: Path to the JSON file containing simulation parameters. **Description**: Path to the JSON file containing simulation parameters.
@@ -163,10 +162,10 @@ The tuning of the parameters is detailed here: :ref:`json input sim-params<sim-p
`gnpy-transmission-example` options `gnpy-transmission-example` options
----------------------------------- ===================================
**Option**: `--show-channels` **Option**: `--show-channels`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
**Description**: Displays the final per-channel OSNR and GSNR summary. **Description**: Displays the final per-channel OSNR and GSNR summary.
@@ -181,7 +180,7 @@ and generalized signal-to-noise ratio (GSNR) for each channel after the simulati
**Option**: `-pl`, `--plot` **Option**: `-pl`, `--plot`
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
**Description**: Generates plots of the results. **Description**: Generates plots of the results.
@@ -195,7 +194,7 @@ and generalized signal-to-noise ratio (GSNR) for each channel after the simulati
**Option**: `-l`, `--list-nodes` **Option**: `-l`, `--list-nodes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
**Description**: Lists all transceiver nodes in the network. **Description**: Lists all transceiver nodes in the network.
@@ -208,7 +207,7 @@ and generalized signal-to-noise ratio (GSNR) for each channel after the simulati
**Functionality**: This option provides a quick way to view all transceiver nodes present in the network topology. **Functionality**: This option provides a quick way to view all transceiver nodes present in the network topology.
**Option**: `-po`, `--power` **Option**: `-po`, `--power`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
**Description**: Specifies the reference channel power in span in dBm. **Description**: Specifies the reference channel power in span in dBm.
@@ -223,7 +222,7 @@ It replaces the value specified in the `SI` section of the equipment library (:r
**Option**: `--spectrum` **Option**: `--spectrum`
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
**Description**: Specifies a user-defined mixed rate spectrum JSON file for propagation. **Description**: Specifies a user-defined mixed rate spectrum JSON file for propagation.
@@ -238,7 +237,7 @@ include varying channel rates and configurations. More details here: :ref:`mixed
Options for `path_requests_run` Options for `path_requests_run`
------------------------------- ===============================
The `gnpy-path-request` script provides a simple path computation function that supports routing, transceiver mode selection, and spectrum assignment. The `gnpy-path-request` script provides a simple path computation function that supports routing, transceiver mode selection, and spectrum assignment.
@@ -254,7 +253,7 @@ The `gnpy-path-request` computes:
**Option**: `-bi`, `--bidir` **Option**: `-bi`, `--bidir`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
**Description**: Indicates that all demands are bidirectional. **Description**: Indicates that all demands are bidirectional.
@@ -270,7 +269,7 @@ attribute to true in the service file, possibly affecting feasibility if one dir
**Option**: `-o`, `--output` **Option**: `-o`, `--output`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
**Description**: Stores computation results requests into a JSON or CSV file. **Description**: Stores computation results requests into a JSON or CSV file.
@@ -285,7 +284,7 @@ for further analysis.
**Option**: `--redesign-per-request` **Option**: `--redesign-per-request`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------
**Description**: Redesigns the network for each request using the request as the reference channel **Description**: Redesigns the network for each request using the request as the reference channel
(replaces the `SI` section of the equipment library with the request specifications). (replaces the `SI` section of the equipment library with the request specifications).

17
docs/concepts.rst
View File

@@ -1,7 +1,8 @@
.. _concepts: .. _concepts:
*****************************
Simulating networks with GNPy Simulating networks with GNPy
============================= *****************************
Running simulations with GNPy requires three pieces of information: Running simulations with GNPy requires three pieces of information:
@@ -12,7 +13,7 @@ Running simulations with GNPy requires three pieces of information:
.. _concepts-topology: .. _concepts-topology:
Network Topology Network Topology
---------------- ================
The *topology* acts as a "digital self" of the simulated network. The *topology* acts as a "digital self" of the simulated network.
When given a network topology, GNPy can either run a specific simulation as-is, or it can *optimize* the topology before performing the simulation. When given a network topology, GNPy can either run a specific simulation as-is, or it can *optimize* the topology before performing the simulation.
@@ -34,7 +35,7 @@ The topology is specified via :ref:`XLS files<excel>` or via :ref:`JSON<legacy-j
.. _complete-vs-incomplete: .. _complete-vs-incomplete:
Fully Specified vs. Partially Designed Networks Fully Specified vs. Partially Designed Networks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------
Let's consider a simple triangle topology with three :abbr:`PoPs (Points of Presence)` covering three cities: Let's consider a simple triangle topology with three :abbr:`PoPs (Points of Presence)` covering three cities:
@@ -208,7 +209,7 @@ In other cases where the location of amplifier huts is already known, but the sp
.. _concepts-equipment: .. _concepts-equipment:
The Equipment Library The Equipment Library
--------------------- =====================
In order to produce an accurate simulation, GNPy needs to know the physical properties of each entity which affects the optical signal. In order to produce an accurate simulation, GNPy needs to know the physical properties of each entity which affects the optical signal.
Entries in the equipment library correspond to actual real-world, tangible entities. Entries in the equipment library correspond to actual real-world, tangible entities.
@@ -231,7 +232,7 @@ GNPy currently does not take into consideration the spectrum filtering penalties
.. _concepts-nf-model: .. _concepts-nf-model:
Amplifier Noise Figure Models Amplifier Noise Figure Models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
One of the key parameters of an amplifier is the method to use for computing the Noise Figure (NF). One of the key parameters of an amplifier is the method to use for computing the Noise Figure (NF).
GNPy supports several different noise models with varying level of accuracy. GNPy supports several different noise models with varying level of accuracy.
@@ -244,7 +245,7 @@ For scenarios where the vendor has not yet contributed an accurate EDFA NF descr
.. _nf-model-min-max-NF: .. _nf-model-min-max-NF:
Min-max NF Min-max NF
********** ^^^^^^^^^^
This is an operator-focused model where performance is defined by the *minimal* and *maximal NF*. This is an operator-focused model where performance is defined by the *minimal* and *maximal NF*.
These are especially suited to model a dual-coil EDFA with a VOA in between. These are especially suited to model a dual-coil EDFA with a VOA in between.
@@ -254,7 +255,7 @@ The worst (maximal) NF applies when the EDFA operates at its minimal gain.
This model is suitable for use when the vendor has not provided a more accurate performance description of the EDFA. This model is suitable for use when the vendor has not provided a more accurate performance description of the EDFA.
Raman Approximation Raman Approximation
******************* ^^^^^^^^^^^^^^^^^^^
While GNPy is fully Raman-aware, under certain scenarios it is useful to be able to run a simulation without an accurate Raman description. While GNPy is fully Raman-aware, under certain scenarios it is useful to be able to run a simulation without an accurate Raman description.
For these purposes the :ref:`polynomial NF<ext-nf-model-polynomial-NF>` model with :math:`\text{a} = \text{b} = \text{c} = 0`, and :math:`\text{d} = NF` can be used. For these purposes the :ref:`polynomial NF<ext-nf-model-polynomial-NF>` model with :math:`\text{a} = \text{b} = \text{c} = 0`, and :math:`\text{d} = NF` can be used.
@@ -262,7 +263,7 @@ For these purposes the :ref:`polynomial NF<ext-nf-model-polynomial-NF>` model wi
.. _concepts-simulation: .. _concepts-simulation:
Simulation Simulation
---------- ==========
When the network model has been instantiated and the physical properties and operational settings of the actual physical devices are known, GNPy can start simulating how the signal propagate through the optical fiber. When the network model has been instantiated and the physical properties and operational settings of the actual physical devices are known, GNPy can start simulating how the signal propagate through the optical fiber.

13
docs/excel.rst
View File

@@ -1,7 +1,8 @@
.. _excel: .. _excel:
*****************************
Excel (XLS, XLSX) input files Excel (XLS, XLSX) input files
============================= *****************************
``gnpy-transmission-example`` gives the possibility to use an excel input file instead of a json file. The program then will generate the corresponding json file for you. ``gnpy-transmission-example`` gives the possibility to use an excel input file instead of a json file. The program then will generate the corresponding json file for you.
@@ -21,7 +22,7 @@ In order to work the excel file MUST contain at least 2 sheets:
.. _excel-nodes-sheet: .. _excel-nodes-sheet:
`Nodes` sheet `Nodes` sheet
------------- =============
`Nodes` sheet contains nine columns. `Nodes` sheet contains nine columns.
Each line represents a 'node' (`ROADM` site or an in line amplifier site `ILA` or a `Fused`):: Each line represents a 'node' (`ROADM` site or an in line amplifier site `ILA` or a `Fused`)::
@@ -51,7 +52,7 @@ Each line represents a 'node' (`ROADM` site or an in line amplifier site `ILA` o
.. _excel-links-sheet: .. _excel-links-sheet:
Links sheet Links sheet
----------- ===========
Links sheet must contain sixteen columns:: Links sheet must contain sixteen columns::
@@ -121,7 +122,7 @@ and a fiber span from node3 to node6::
.. _excel-equipment-sheet: .. _excel-equipment-sheet:
Eqpt sheet Eqpt sheet
---------- ==========
The equipment sheet (named "Eqpt") is optional. The equipment sheet (named "Eqpt") is optional.
If provided, it specifies types of boosters and preamplifiers for all ROADM degrees of all ROADM nodes, and for all ILA nodes. If provided, it specifies types of boosters and preamplifiers for all ROADM degrees of all ROADM nodes, and for all ILA nodes.
@@ -196,7 +197,7 @@ This generates a text file meshTopologyExampleV2_eqt_sheet.txt whose content ca
.. _excel-roadms-sheet: .. _excel-roadms-sheet:
Roadms sheet Roadms sheet
------------ ============
The ROADM sheet (named "Roadms") is optional. The ROADM sheet (named "Roadms") is optional.
If provided, it can be used to specify: If provided, it can be used to specify:
@@ -234,7 +235,7 @@ This sheet contains six columns:
.. _excel-service-sheet: .. _excel-service-sheet:
Service sheet Service sheet
------------- =============
Service sheet is optional. It lists the services for which path and feasibility must be computed with ``gnpy-path-request``. Service sheet is optional. It lists the services for which path and feasibility must be computed with ``gnpy-path-request``.

23
docs/extending.rst
View File

@@ -1,7 +1,8 @@
.. _extending: .. _extending:
****************************************
Extending GNPy with vendor-specific data Extending GNPy with vendor-specific data
======================================== ****************************************
GNPy ships with an :ref:`equipment library<concepts-equipment>` containing machine-readable datasheets of networking equipment. GNPy ships with an :ref:`equipment library<concepts-equipment>` containing machine-readable datasheets of networking equipment.
Vendors who are willing to contribute descriptions of their supported products are encouraged to `submit a patch <https://review.gerrithub.io/Documentation/intro-gerrit-walkthrough-github.html>`__ -- or just :ref:`get in touch with us directly<contributing>`. Vendors who are willing to contribute descriptions of their supported products are encouraged to `submit a patch <https://review.gerrithub.io/Documentation/intro-gerrit-walkthrough-github.html>`__ -- or just :ref:`get in touch with us directly<contributing>`.
@@ -11,7 +12,7 @@ This chapter discusses option for modeling performance of :ref:`EDFA amplifiers<
.. _extending-edfa: .. _extending-edfa:
EDFAs EDFAs
----- =====
An accurate description of the :abbr:`EDFA (Erbium-Doped Fiber Amplifier)` and especially its noise characteristics is required. An accurate description of the :abbr:`EDFA (Erbium-Doped Fiber Amplifier)` and especially its noise characteristics is required.
GNPy describes this property in terms of the **Noise Figure (NF)** of an amplifier model as a function of its operating point. GNPy describes this property in terms of the **Noise Figure (NF)** of an amplifier model as a function of its operating point.
@@ -20,7 +21,7 @@ GNPy supports several different :ref:`noise models<concepts-nf-model>`, and vend
.. _ext-nf-model-polynomial-NF: .. _ext-nf-model-polynomial-NF:
Polynomial NF Polynomial NF
************* -------------
This model computes the NF as a function of the difference between the optimal gain and the current gain. This model computes the NF as a function of the difference between the optimal gain and the current gain.
The NF is expressed as a third-degree polynomial: The NF is expressed as a third-degree polynomial:
@@ -43,7 +44,7 @@ In that case, use:
.. _ext-nf-model-polynomial-OSNR-OpenROADM: .. _ext-nf-model-polynomial-OSNR-OpenROADM:
Polynomial OSNR (OpenROADM-style for inline amplifier) Polynomial OSNR (OpenROADM-style for inline amplifier)
****************************************************** ------------------------------------------------------
This model is useful for amplifiers compliant to the OpenROADM specification for ILA (an in-line amplifier). This model is useful for amplifiers compliant to the OpenROADM specification for ILA (an in-line amplifier).
The amplifier performance is evaluated via its incremental OSNR, which is a function of the input power. The amplifier performance is evaluated via its incremental OSNR, which is a function of the input power.
@@ -55,7 +56,7 @@ The amplifier performance is evaluated via its incremental OSNR, which is a func
.. _ext-nf-model-noise-mask-OpenROADM: .. _ext-nf-model-noise-mask-OpenROADM:
Noise mask (OpenROADM-style for combined preamp and booster) Noise mask (OpenROADM-style for combined preamp and booster)
************************************************************ ------------------------------------------------------------
Unlike GNPy which simluates the preamplifier and the booster separately as two amplifiers for best accuracy, the OpenROADM specification mandates a certain performance level for a combination of these two amplifiers. Unlike GNPy which simluates the preamplifier and the booster separately as two amplifiers for best accuracy, the OpenROADM specification mandates a certain performance level for a combination of these two amplifiers.
For the express path, the effective noise mask comprises the preamplifier and the booster. For the express path, the effective noise mask comprises the preamplifier and the booster.
@@ -70,7 +71,7 @@ GNPy emulates this specification via two special NF models:
.. _ext-nf-model-min-max-NF: .. _ext-nf-model-min-max-NF:
Min-max NF Min-max NF
********** ----------
When the vendor prefers not to share the amplifier description in full detail, GNPy also supports describing the NF characteristics via the *minimal* and *maximal NF*. When the vendor prefers not to share the amplifier description in full detail, GNPy also supports describing the NF characteristics via the *minimal* and *maximal NF*.
This approximates a more accurate polynomial description reasonably well for some models of a dual-coil EDFA with a VOA in between. This approximates a more accurate polynomial description reasonably well for some models of a dual-coil EDFA with a VOA in between.
@@ -80,7 +81,7 @@ The worst (maximal) NF applies when the EDFA operates at the minimal gain.
.. _ext-nf-model-dual-stage-amplifier: .. _ext-nf-model-dual-stage-amplifier:
Dual-stage Dual-stage
********** ----------
Dual-stage amplifier combines two distinct amplifiers. Dual-stage amplifier combines two distinct amplifiers.
Vendors which provide an accurate description of their preamp and booster stages separately can use the dual-stage model for an aggregate description of the whole amplifier. Vendors which provide an accurate description of their preamp and booster stages separately can use the dual-stage model for an aggregate description of the whole amplifier.
@@ -88,7 +89,7 @@ Vendors which provide an accurate description of their preamp and booster stages
.. _ext-nf-model-advanced: .. _ext-nf-model-advanced:
Advanced Specification Advanced Specification
********************** ----------------------
The amplifier performance can be further described in terms of gain ripple, NF ripple, and the dynamic gain tilt. The amplifier performance can be further described in terms of gain ripple, NF ripple, and the dynamic gain tilt.
When provided, the amplifier characteristic is fine-tuned as a function of carrier frequency. Note that in this advanced When provided, the amplifier characteristic is fine-tuned as a function of carrier frequency. Note that in this advanced
@@ -97,7 +98,7 @@ specification tilt is defined vs frequency while tilt_target specified in EDFA i
.. _extending-raman: .. _extending-raman:
Raman Amplifiers Raman Amplifiers
---------------- ================
An accurate simulation of Raman amplification requires knowledge of: An accurate simulation of Raman amplification requires knowledge of:
@@ -113,7 +114,7 @@ This is also useful to quickly approximate a hybrid EDFA+Raman amplifier.
.. _extending-transponder: .. _extending-transponder:
Transponders Transponders
------------ ============
Since transponders are usually capable of operating in a variety of modes, these are described separately. Since transponders are usually capable of operating in a variety of modes, these are described separately.
A *mode* usually refers to a particular performance point that is defined by a combination of the symbol rate, modulation format, and :abbr:`FEC (Forward Error Correction)`. A *mode* usually refers to a particular performance point that is defined by a combination of the symbol rate, modulation format, and :abbr:`FEC (Forward Error Correction)`.
@@ -152,7 +153,7 @@ GNPy does not directly track the FEC performance, so the type of chosen FEC is l
.. _extending-roadm: .. _extending-roadm:
ROADMs ROADMs
------ ======
In a :abbr:`ROADM (Reconfigurable Add/Drop Multiplexer)`, GNPy simulates the impairments of the preamplifiers and boosters of line degrees :ref:`separately<topo-roadm-preamp-booster>`. In a :abbr:`ROADM (Reconfigurable Add/Drop Multiplexer)`, GNPy simulates the impairments of the preamplifiers and boosters of line degrees :ref:`separately<topo-roadm-preamp-booster>`.
The set of parameters for each ROADM model therefore includes: The set of parameters for each ROADM model therefore includes:

4
docs/gnpy-api.rst
View File

@@ -2,8 +2,8 @@
API Reference Documentation API Reference Documentation
*************************** ***************************
``gnpy`` package GNPy package
================ ============
.. automodule:: gnpy .. automodule:: gnpy

10
docs/index.rst
View File

@@ -1,5 +1,6 @@
************************************
GNPy: Optical Route Planning Library GNPy: Optical Route Planning Library
===================================================================== ************************************
`GNPy <http://github.com/telecominfraproject/gnpy>`_ is an open-source, `GNPy <http://github.com/telecominfraproject/gnpy>`_ is an open-source,
community-developed library for building route planning and optimization tools community-developed library for building route planning and optimization tools
@@ -7,8 +8,9 @@ in real-world mesh optical networks. It is based on the Gaussian Noise Model.
.. toctree:: .. toctree::
:maxdepth: 4 :maxdepth: 4
:caption: Contents
intro intro
concepts concepts
install install
cli_options cli_options
@@ -22,9 +24,11 @@ in real-world mesh optical networks. It is based on the Gaussian Noise Model.
gnpy-api gnpy-api
release-notes release-notes
publications publications
genindex
modindex
Indices and tables Indices and tables
================== ------------------
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex` * :ref:`modindex`

9
docs/install.rst
View File

@@ -1,5 +1,6 @@
***************
Installing GNPy Installing GNPy
--------------- ***************
There are several methods on how to obtain GNPy. There are several methods on how to obtain GNPy.
The easiest option for a non-developer is probably going via our :ref:`Docker images<install-docker>`. The easiest option for a non-developer is probably going via our :ref:`Docker images<install-docker>`.
@@ -9,7 +10,7 @@ Note that this needs a :ref:`working installation of Python<install-python>`, fo
.. _install-docker: .. _install-docker:
Using prebuilt Docker images Using prebuilt Docker images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ============================
Our `Docker images <https://hub.docker.com/r/telecominfraproject/oopt-gnpy>`_ contain everything needed to run all examples from this guide. Our `Docker images <https://hub.docker.com/r/telecominfraproject/oopt-gnpy>`_ contain everything needed to run all examples from this guide.
Docker transparently fetches the image over the network upon first use. Docker transparently fetches the image over the network upon first use.
@@ -35,7 +36,7 @@ Remove that directory if you want to start from scratch.
.. _install-python: .. _install-python:
Using Python on your computer Using Python on your computer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============================
**Note**: `gnpy` supports Python 3 only. Python 2 is not supported. **Note**: `gnpy` supports Python 3 only. Python 2 is not supported.
`gnpy` requires Python ≥3.8 `gnpy` requires Python ≥3.8
@@ -89,7 +90,7 @@ exact version of Python you are using.
.. _install-pip: .. _install-pip:
Installing the Python package Installing the Python package
***************************** -----------------------------
From within your Anaconda Python 3 environment, you can clone the master branch From within your Anaconda Python 3 environment, you can clone the master branch
of the `gnpy` repo and install it with: of the `gnpy` repo and install it with:

5
docs/intro.rst
View File

@@ -1,7 +1,8 @@
.. _intro: .. _intro:
************
Introduction Introduction
============ ************
``gnpy`` is a library for building route planning and optimization tools. ``gnpy`` is a library for building route planning and optimization tools.
@@ -55,7 +56,7 @@ interference noise.
.. |Pnli| replace:: P\ :sub:`nli` .. |Pnli| replace:: P\ :sub:`nli`
Further Instructions for Use Further Instructions for Use
---------------------------- ============================
Simulations are driven by a set of `JSON <json.rst>`__ or `XLS <excel.rst>`__ files. Simulations are driven by a set of `JSON <json.rst>`__ or `XLS <excel.rst>`__ files.

71
docs/json_instance_examples.rst
View File

@@ -1,11 +1,11 @@
.. _json-instance-examples: .. _json-instance-examples:
********************************************* *************
Equipment and Network description definitions JSON examples
********************************************* *************
1. Equipment description 1. Equipment description
######################## ========================
Equipment description defines equipment types and those parameters. Equipment description defines equipment types and those parameters.
Description is made in JSON file with predefined structure. By default Description is made in JSON file with predefined structure. By default
@@ -17,10 +17,10 @@ Parsing of JSON file is made with
value is a dictionary of format **dict[`equipment type`][`subtype`]=object** value is a dictionary of format **dict[`equipment type`][`subtype`]=object**
1.1. Structure definition 1.1. Structure definition
************************* -------------------------
1.1.1. Equipment types 1.1.1. Equipment types
********************** ^^^^^^^^^^^^^^^^^^^^^^
Every equipment type is defined in JSON equipment library root with according name and Every equipment type is defined in JSON equipment library root with according name and
array of parameters as value. array of parameters as value.
@@ -41,7 +41,7 @@ possible types:
1.1.2. Equipment parameters and subtypes 1.1.2. Equipment parameters and subtypes
***************************************** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Array of parameters is a list of objects with unordered parameter name Array of parameters is a list of objects with unordered parameter name
@@ -88,10 +88,10 @@ it will be marked with **”default”** value.
1.2. Equipment parameters by type 1.2. Equipment parameters by type
********************************* ---------------------------------
1.2.1. Amplifier types 1.2.1. Amplifier types
********************** ^^^^^^^^^^^^^^^^^^^^^^
Several types of amplfiers definition are possible: Several types of amplfiers definition are possible:
@@ -219,7 +219,7 @@ Several types of amplfiers definition are possible:
] ]
Composed amplifier types Composed amplifier types
------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~
- `multiband` - `multiband`
This type enables the definition of multiband amplifiers that consist of multiple This type enables the definition of multiband amplifiers that consist of multiple
@@ -332,7 +332,7 @@ Composed amplifier types
} }
1.2.2. Fiber and RamanFiber types 1.2.2. Fiber and RamanFiber types
********************************* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Fiber type with its parameters: Fiber type with its parameters:
@@ -383,7 +383,7 @@ is only available in RamanFiber, which requires the flag to be set to True, maki
use of the --sim-params option mandatory. use of the --sim-params option mandatory.
1.2.3 Roadm types 1.2.3 Roadm types
***************** ^^^^^^^^^^^^^^^^^
Roadm element with its parameters: Roadm element with its parameters:
@@ -491,7 +491,7 @@ CCAMP optical impairment topology <https://github.com/ietf-ccamp-wg/draft-ietf-c
] ]
1.2.5. Transceiver type 1.2.5. Transceiver type
************************** ^^^^^^^^^^^^^^^^^^^^^^^
Transceiver element with its parameters. **”mode”** can contain multiple Transceiver element with its parameters. **”mode”** can contain multiple
Transceiver operation formats. Transceiver operation formats.
@@ -532,7 +532,7 @@ Note that ``OSNR`` parameter refers to the receiver's minimal OSNR threshold for
] ]
1.2.3. Spans element 1.2.3. Spans element
******************** ^^^^^^^^^^^^^^^^^^^^
Spans element with its parameters: Spans element with its parameters:
@@ -553,7 +553,7 @@ Spans element with its parameters:
1.2.4. Spectral Information 1.2.4. Spectral Information
*************************** ^^^^^^^^^^^^^^^^^^^^^^^^^^^
Spectral information with its parameters: Spectral information with its parameters:
@@ -576,7 +576,7 @@ Spectral information with its parameters:
2. Network description 2. Network description
###################### ======================
Network description defines network elements with additional to Network description defines network elements with additional to
equipment description parameters, metadata and elements interconnection. equipment description parameters, metadata and elements interconnection.
@@ -590,10 +590,10 @@ equipment_description)** and return value is **DiGraph** object which
mimics network description. mimics network description.
2.1. Structure definition 2.1. Structure definition
########################## -------------------------
2.1.1. File root structure 2.1.1. File root structure
*************************** ^^^^^^^^^^^^^^^^^^^^^^^^^^
Network description JSON file root consist of three unordered parts: Network description JSON file root consist of three unordered parts:
@@ -618,7 +618,7 @@ Network description JSON file root consist of three unordered parts:
2.1.2. Elements parameters and subtypes 2.1.2. Elements parameters and subtypes
**************************************** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The list of network element objects consist of unordered parameter names The list of network element objects consist of unordered parameter names
and those values. In case of **"type_variety"** absence, the and those values. In case of **"type_variety"** absence, the
@@ -626,10 +626,10 @@ and those values. In case of **"type_variety"** absence, the
**"type_variety"** must be defined in equipment library. **"type_variety"** must be defined in equipment library.
2.2. Element parameters by type 2.2. Element parameters by type
********************************* -------------------------------
2.2.1. Transceiver element 2.2.1. Transceiver element
*************************** ^^^^^^^^^^^^^^^^^^^^^^^^^^
Transceiver element with its parameters. Transceiver element with its parameters.
@@ -657,7 +657,7 @@ Without any definition, default :ref:`SI<spectral_info>` values of the library a
2.2.2. ROADM element 2.2.2. ROADM element
********************* ^^^^^^^^^^^^^^^^^^^^
ROADM element with its parameters. **“params”** is optional, if nothing is defined, ROADM element with its parameters. **“params”** is optional, if nothing is defined,
it uses default values from equipment library. it uses default values from equipment library.
@@ -707,7 +707,7 @@ it uses default values from equipment library.
2.2.3. Fused element 2.2.3. Fused element
********************* ^^^^^^^^^^^^^^^^^^^^
Fused element with its parameters. **“params”** is optional, if not used Fused element with its parameters. **“params”** is optional, if not used
default loss value of 1dB is used. default loss value of 1dB is used.
@@ -732,7 +732,7 @@ default loss value of 1dB is used.
2.2.4. Fiber element 2.2.4. Fiber element
********************* ^^^^^^^^^^^^^^^^^^^^
Fiber element with its parameters. Fiber element with its parameters.
@@ -782,7 +782,7 @@ Fiber element with its parameters.
2.2.5. RamanFiber element 2.2.5. RamanFiber element
************************* ^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: json .. code-block:: json
@@ -826,7 +826,7 @@ Fiber element with its parameters.
2.2.6. EDFA element 2.2.6. EDFA element
******************** ^^^^^^^^^^^^^^^^^^^
EDFA element with its parameters. EDFA element with its parameters.
@@ -851,7 +851,7 @@ EDFA element with its parameters.
} }
2.3. Connections objects 2.3. Connections objects
************************* ------------------------
Each unidirectional connection object in connections array consist of Each unidirectional connection object in connections array consist of
two unordered **”from_node”** and **”to_node”** name pair with values two unordered **”from_node”** and **”to_node”** name pair with values
@@ -866,7 +866,7 @@ corresponding to element **”uid”**
3. Simulation Parameters 3. Simulation Parameters
######################## ========================
Additional details of the simulation are controlled via ``sim_params.json``: Additional details of the simulation are controlled via ``sim_params.json``:
@@ -888,19 +888,19 @@ Additional details of the simulation are controlled via ``sim_params.json``:
4. Services file 4. Services file
################ ================
**gnpy-path-request** requires a second positional file that contains a list of services to be computed. **gnpy-path-request** requires a second positional file that contains a list of services to be computed.
4.1. Service Excel format 4.1. Service Excel format
************************* -------------------------
Services can be defined either via a :ref:`XLS files<excel-service-sheet>`. Services can be defined either via a :ref:`XLS files<excel-service-sheet>`.
4.2. Service JSON format 4.2. Service JSON format
************************ ------------------------
The JSON format is derived from draft-ietf-teas-yang-path-computation-01.txt. The JSON format is derived from draft-ietf-teas-yang-path-computation-01.txt.
@@ -915,7 +915,7 @@ to define disjunctions among services.
} }
4.2.1. requests 4.2.1. requests
*************** ^^^^^^^^^^^^^^^
**path-request** contains the path and transceiver details. **path-request** contains the path and transceiver details.
See :ref:`services<service>` for a detailed description of each parameter. See :ref:`services<service>` for a detailed description of each parameter.
@@ -985,7 +985,7 @@ See :ref:`services<service>` for a detailed description of each parameter.
} }
4.2.2. synchronization 4.2.2. synchronization
********************** ^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: json .. code-block:: json
@@ -1002,9 +1002,8 @@ See :ref:`services<service>` for a detailed description of each parameter.
} }
**************** 5. Spectrum file
1. Spectrum file ================
****************
**gnpy-transmission-example** supports a `--spectrum` option to specify non identical type **gnpy-transmission-example** supports a `--spectrum` option to specify non identical type
of channels derailed in a JSON file (details :ref:`here<mixed-rate>`). Note that **gnpy-path-request** of channels derailed in a JSON file (details :ref:`here<mixed-rate>`). Note that **gnpy-path-request**

7
docs/model.rst
View File

@@ -1,10 +1,11 @@
.. _physical-model: .. _physical-model:
***************************
Physical Model used in GNPy Physical Model used in GNPy
=========================== ***************************
QoT-E including ASE noise and NLI accumulation QoT-E including ASE noise and NLI accumulation
---------------------------------------------- ==============================================
The operations of PSE simulative framework are based on the capability to The operations of PSE simulative framework are based on the capability to
estimate the QoT of one or more channels operating lightpaths over a given estimate the QoT of one or more channels operating lightpaths over a given
@@ -83,7 +84,7 @@ ps/nm/km, the analytical approximation ensures an excellent accuracy
with a computational time compatible with real-time operations. with a computational time compatible with real-time operations.
The Gaussian Noise Model to evaluate the NLI The Gaussian Noise Model to evaluate the NLI
-------------------------------------------- ============================================
As previously stated, fiber propagation of multilevel modulation formats As previously stated, fiber propagation of multilevel modulation formats
relying on the polarization-division-multiplexing generates impairments that relying on the polarization-division-multiplexing generates impairments that

3
docs/publications.rst
View File

@@ -1,7 +1,8 @@
.. _publications: .. _publications:
************
Publications Publications
============ ************
Below is a chronological list of notable publications that emerged from the PSE group's collaborative work. Below is a chronological list of notable publications that emerged from the PSE group's collaborative work.
These articles detail the evolution of GNPy and confirm its performance through experimental trials: These articles detail the evolution of GNPy and confirm its performance through experimental trials:

13
docs/release-notes.rst
View File

@@ -1,7 +1,8 @@
.. _release-notes: .. _release-notes:
******************
Release change log Release change log
================== ******************
Each release introduces some changes and new features. Each release introduces some changes and new features.
@@ -16,7 +17,7 @@ This change streamlines the configuration process but requires users to explicit
model if the default values do not suit their needs. model if the default values do not suit their needs.
v2.11 v2.11
----- =====
**New feature** **New feature**
@@ -206,7 +207,7 @@ Additionally, they have been experimentally validated in a laboratory setup comp
v2.10 v2.10
----- =====
ROADM impairments can be defined per degree and roadm-path type (add, drop or express). 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. Minimum loss when crossing a ROADM is no more 0 dB. It can be set per ROADM degree with roadm-path-impairments.
@@ -314,7 +315,7 @@ can now be set using a different parameter. It can be set as:
} }
v2.9 v2.9
---- ====
The revision introduces a major refactor that separates design and propagation. Most of these changes have no impact The revision introduces a major refactor that separates design and propagation. Most of these changes have no impact
on the user experience, except the following ones: on the user experience, except the following ones:
@@ -359,7 +360,7 @@ contribution). Note that "actual pch out (dBm)" is the actual propagated total p
band definition at the output of the amplifier element, including noises and out VOA contribution. band definition at the output of the amplifier element, including noises and out VOA contribution.
v2.8 v2.8
---- ====
**Spectrum assignment**: requests can now support multiple slots. **Spectrum assignment**: requests can now support multiple slots.
The definition in service file supports multiple assignments (unchanged syntax): The definition in service file supports multiple assignments (unchanged syntax):
@@ -468,4 +469,4 @@ the deviation from the general equalisation strategy defined in ROADMs.
] ]
v2.7 v2.7
---- ====