Floating point formatting of elements' operational parameters

The current JSON data loader preserves (some) integers as integers. When
printed, the value might not contain any decimal points. The YANG patch
series, however, forces floats when floats are expected (while still
allowing None). This makes the output subtly different.

Change-Id: I0e0c013eb3abddb4aeac1ba43bf0d473fed731d4

.bandit

@@ -0,0 +1,2 @@
+[bandit]
+skips: B101

.codecov.yml

@@ -0,0 +1,9 @@
+comment: off
+coverage:
+  status:
+    project:
+      default:
+        threshold: 5%
+    patch:
+      default:
+        only_pulls: true

.docker-entry.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+cp -nr /oopt-gnpy/gnpy/example-data /shared
+exec "$@"

.docker-travis.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+set -e
+
+IMAGE_NAME=telecominfraproject/oopt-gnpy
+IMAGE_TAG=$(git describe --tags)
+
+ALREADY_FOUND=0
+docker pull ${IMAGE_NAME}:${IMAGE_TAG} && ALREADY_FOUND=1
+
+if [[ $ALREADY_FOUND == 0 ]]; then
+  docker build . -t ${IMAGE_NAME}
+  docker tag ${IMAGE_NAME} ${IMAGE_NAME}:${IMAGE_TAG}
+
+  # shared directory setup: do not clobber the real data
+  mkdir trash
+  cd trash
+  docker run -it --rm --volume $(pwd):/shared ${IMAGE_NAME} gnpy-transmission-example
+else
+  echo "Image ${IMAGE_NAME}:${IMAGE_TAG} already available, will just update the other tags"
+fi
+
+docker images
+
+do_docker_login() {
+  echo "${DOCKER_PASSWORD}" | docker login -u "${DOCKER_USERNAME}" --password-stdin
+}
+
+if [[ "${TRAVIS_PULL_REQUEST}" == "false" ]]; then
+  if [[ "${TRAVIS_BRANCH}" == "develop" || "${TRAVIS_BRANCH}" == "docker" ]]; then
+    echo "Publishing latest"
+    docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:latest
+    do_docker_login
+    if [[ $ALREADY_FOUND == 0 ]]; then
+      docker push ${IMAGE_NAME}:${IMAGE_TAG}
+    fi
+    docker push ${IMAGE_NAME}:latest
+  elif [[ "${TRAVIS_BRANCH}" == "master" ]]; then
+    echo "Publishing stable"
+    docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:stable
+    do_docker_login
+    if [[ $ALREADY_FOUND == 0 ]]; then
+      docker push ${IMAGE_NAME}:${IMAGE_TAG}
+    fi
+    docker push ${IMAGE_NAME}:stable
+  fi
+fi

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+# Thanks for contributing to GNPy
+
+If it isn't much trouble, please send your contribution as patches to our Gerrit.
+Here's [how to submit patches](https://review.gerrithub.io/Documentation/intro-gerrit-walkthrough-github.html), and here's a [list of stuff we are currently working on](https://review.gerrithub.io/q/project:Telecominfraproject/oopt-gnpy+status:open).
+Just sign in via your existing GitHub account.
+
+However, if you feel more comfortable with filing GitHub PRs, we can work with that too.

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 .ipynb_checkpoints
+.idea
 
 # C extensions
 *.so

.gitreview

@@ -0,0 +1,4 @@
+[gerrit]
+host=review.gerrithub.io
+project=Telecominfraproject/oopt-gnpy
+defaultrebase=0

.readthedocs.yml

@@ -1,4 +1,5 @@
 build:
     image: latest
 python:
-    version: 3.6
+    version: 3.8
+requirements_file: docs/requirements.txt

.travis.yml

@@ -1,10 +1,29 @@
+dist: focal
+os: linux
 language: python
+services: docker
 python:
   - "3.6"
-# command to install dependencies
-install:
-  - python setup.py install
-# command to run tests
-before_script:
+  - "3.7"
+  - "3.8"
+  - "3.9"
+before_install:
+  - sudo apt-get -y install graphviz
+install: skip
 script:
-  - pytest
+  - pip install --editable .
+  - pip install pytest-cov rstcheck
+  - pytest --cov-report=xml --cov=gnpy -v
+  - pip install -r docs/requirements.txt
+  - rstcheck --ignore-roles cite *.rst
+  - sphinx-build -W --keep-going docs/ x-throwaway-location
+after_success:
+  - bash <(curl -s https://codecov.io/bash)
+jobs:
+  include:
+    - stage: test
+      name: Docker image
+      script:
+        - git fetch --unshallow
+        - ./.docker-travis.sh
+        - docker images

.zuul.yaml

@@ -0,0 +1,45 @@
+---
+- project:
+    check:
+      jobs:
+        - tox-py38-cover
+        - coverage-diff:
+            voting: false
+            dependencies:
+              - tox-py38-cover-previous
+              - tox-py38-cover
+            vars:
+              coverage_job_name_previous: tox-py38-cover-previous
+              coverage_job_name_current: tox-py38-cover
+        - tox-linters-diff-n-report:
+            voting: false
+        - tox-py36-el8
+        - tox-docs-f32
+        - tox-py38-cover-previous
+    gate:
+      jobs:
+        - tox-py38-f32
+        - tox-docs-f32
+    tag:
+      jobs:
+        - oopt-release-python:
+            secrets:
+              - secret: pypi-oopt-gnpy
+                name: pypi_info
+                pass-to-parent: true
+
+- secret:
+    name: pypi-oopt-gnpy
+    data:
+      username: __token__
+      password: !encrypted/pkcs1-oaep
+        - Taod9JmSMtVAvC5ShSbB3UWuccktQvutdySrj0G7a1Nk4tKFQIdwDXEnBuLpHsZVvsU9Q
+          6uk4wRVQABDSdNNI/+M/1FwmZfoxuOXa02U5S1deuxW/rBHTxzYcuB8xriwhArBvTiDMk
+          zyWHVysgDsjlR+85h/DkEhvsaMRDLYWqFwYgXizMoGNKVkwDVIH+qkhBmbggQfDpcYPKT
+          1gq0d6fw0eKVJtO8+vonMEcE0sWZvHmZvSSu0H++gxoe1W/JtzbCteH3Ak0zktwBHI8Qt
+          WBqFvY3laad335tpkFJN5b949N+DP8svCWwRwXmkZlHplPYZWF6QpYbEEXL/6Q0H6VwL+
+          om4f7ybYpKe9Gl939uv2INnXaKe5EU6CMsSw40r2XZCjnSTjWOTgh9pUn2PsoHnqUlALW
+          VR4Z+ipnCrEbu8aTmX3ROcnwYNS7OXkq4uhwDU1u9QjzyMHet6NQQhwhGtimsTo9KhL4E
+          TEUNiRlbAgow9WOwM5r3vRzddO8T2HZZSGaWj75qNRX46XPQWRWgB7ItAwyXgwLZ8UzWl
+          HdztjS3D7Hlsqno3zxNOVlhA5/vl9uVnhFbJnMtUOJAB07YoTJOeR+LjQ0avx/VzopxXc
+          RA/WvJXVZSBrlAHY0+ip4wPZvdi4Ph90gpmvHJvoH82KVfp2j5jxzUhsage94I=

AUTHORS.rst

@@ -6,16 +6,24 @@ To learn how to contribute, please see CONTRIBUTING.md
 (*in alphabetical order*)
 
 - Alessio Ferrari (Politecnico di Torino) <alessio.ferrari@polito.it>
+- Anders Lindgren (Telia Company) <Anders.X.Lindgren@teliacompany.com>
+- Andrea D'Amico (Politecnico di Torino) <andrea.damico@polito.it>
 - Brian Taylor (Facebook) <briantaylor@fb.com>
 - David Boertjes (Ciena) <dboertje@ciena.com>
+- Diego Landa (Facebook) <dlanda@fb.com>
 - Esther Le Rouzic (Orange) <esther.lerouzic@orange.com>
 - Gabriele Galimberti (Cisco) <ggalimbe@cisco.com>
 - Gert Grammel (Juniper Networks) <ggrammel@juniper.net>
 - Gilad Goldfarb (Facebook) <giladg@fb.com>
 - James Powell (Telecom Infra Project) <james.powell@telecominfraproject.com>
+- Jan Kundrát (Telecom Infra Project) <jan.kundrat@telecominfraproject.com>
 - Jeanluc Augé (Orange) <jeanluc.auge@orange.com>
 - Jonas Mårtensson (RISE) <jonas.martensson@ri.se>
 - Mattia Cantono (Politecnico di Torino) <mattia.cantono@polito.it>
+- Miguel Garrich (University Catalunya) <miquel.garrich@upct.es>
+- Raj Nagarajan (Lumentum) <raj.nagarajan@lumentum.com>
 - Roberts Miculens (Lattelecom) <roberts.miculens@lattelecom.lv>
+- Shengxiang Zhu (University of Arizona) <szhu@email.arizona.edu>
+- Stefan Melin (Telia Company) <Stefan.Melin@teliacompany.com>
 - Vittorio Curri (Politecnico di Torino) <vittorio.curri@polito.it>
 - Xufeng Liu (Jabil) <xufeng_liu@jabil.com>

Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.9-slim
+COPY . /oopt-gnpy
+WORKDIR /oopt-gnpy
+RUN apt update; apt install -y git
+RUN pip install .
+WORKDIR /shared/example-data
+ENTRYPOINT ["/oopt-gnpy/.docker-entry.sh"]
+CMD ["/bin/bash"]

README.md

@@ -0,0 +1,29 @@
+# GNPy: Optical Route Planning and DWDM Network Optimization
+
+[![Install via pip](https://img.shields.io/pypi/v/gnpy)](https://pypi.org/project/gnpy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gnpy)](https://pypi.org/project/gnpy/)
+[![Documentation status](https://readthedocs.org/projects/gnpy/badge/?version=master)](http://gnpy.readthedocs.io/en/master/?badge=master)
+[![CI](https://travis-ci.com/Telecominfraproject/oopt-gnpy.svg?branch=master)](https://travis-ci.com/Telecominfraproject/oopt-gnpy)
+[![Gerrit](https://img.shields.io/badge/patches-via%20Gerrit-blue)](https://review.gerrithub.io/q/project:Telecominfraproject/oopt-gnpy+is:open)
+[![Contributors](https://img.shields.io/github/contributors-anon/Telecominfraproject/oopt-gnpy)](https://github.com/Telecominfraproject/oopt-gnpy/graphs/contributors)
+[![Code Quality via LGTM.com](https://img.shields.io/lgtm/grade/python/github/Telecominfraproject/oopt-gnpy)](https://lgtm.com/projects/g/Telecominfraproject/oopt-gnpy/)
+[![Code Coverage via codecov](https://img.shields.io/codecov/c/github/Telecominfraproject/oopt-gnpy)](https://codecov.io/gh/Telecominfraproject/oopt-gnpy)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3458319.svg)](https://doi.org/10.5281/zenodo.3458319)
+
+GNPy is an open-source, community-developed library for building route planning and optimization tools in real-world mesh optical networks.
+We are a consortium of operators, vendors, and academic researchers sponsored via the [Telecom Infra Project](http://telecominfraproject.com)'s [OOPT/PSE](https://telecominfraproject.com/open-optical-packet-transport) working group.
+Together, we are building this tool for rapid development of production-grade route planning tools which is easily extensible to include custom network elements and performant to the scale of real-world mesh optical networks.
+
+![GNPy with an OLS system](docs/images/GNPy-banner.png)
+
+## Quick Start
+
+Install either via [Docker](docs/install.rst#install-docker), or as a [Python package](docs/install.rst#install-pip).
+Read our [documentation](https://gnpy.readthedocs.io/), learn from the demos, and [get in touch with us](https://github.com/Telecominfraproject/oopt-gnpy/discussions).
+
+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:
+
+[![Running a simple simulation example](https://telecominfraproject.github.io/oopt-gnpy/docs/images/transmission_main_example.svg)](https://asciinema.org/a/252295)
+
+GNPy can do much more, including acting as a Path Computation Engine, tracking bandwidth requests, or advising the SDN controller about a best possible path through a large DWDM network.
+Learn more about this [in the documentation](https://gnpy.readthedocs.io/).

README.rst

@@ -1,605 +0,0 @@
-====================================================================
-`gnpy`: mesh optical network route planning and optimization library
-====================================================================
-
-|docs| |build|
-
-**`gnpy` is an open-source, community-developed library for building route
-planning and optimization tools in real-world mesh optical networks.**
-
-`gnpy <http://github.com/telecominfraproject/oopt-gnpy>`__ is:
-
-- a sponsored project of the `OOPT/PSE <https://telecominfraproject.com/open-optical-packet-transport/>`_ working group of the `Telecom Infra Project <http://telecominfraproject.com>`_
-- fully community-driven, fully open source library
-- driven by a consortium of operators, vendors, and academic researchers
-- intended for rapid development of production-grade route planning tools
-- easily extensible to include custom network elements
-- performant to the scale of real-world mesh optical networks
-
-Documentation: https://gnpy.readthedocs.io
-
-Branches and Tagged Releases
-----------------------------
-
-- the `master <https://github.com/Telecominfraproject/oopt-gnpy/tree/master>`_ branch contains stable, validated code. It is updated from develop on a release schedule determined by the OOPT-PSE Working Group. For more information about the validation process, see: https://github.com/Telecominfraproject/oopt-gnpy/wiki/Testing-for-Quality
-- the `develop <https://github.com/Telecominfraproject/oopt-gnpy/tree/develop>`_ branch contains the latest code under active development, which may not be fully validated and tested.
-- the `phase-1 <https://github.com/Telecominfraproject/oopt-gnpy/tree/phase-1>`_ branch contains code for Phase I of the OOPT-PSE efforts and is kept only for reference. This branch is unmaintained.
-
-A brief outline of major (tagged) `gnpy` releases:
-
-+---------------+-------------+-----------------------------------------------+
-| release date  | version tag | notes                                         |
-+===============+=============+===============================================+
-| Mar 5, 2019   | v1.2        | - plotting fixes                              |
-|               |             | - documentation clean-up                      |
-|               |             | - bug fixes                                   |
-+---------------+-------------+-----------------------------------------------+
-| Jan 30, 2019  | v1.1        | - XLS parser enhancements                     |
-|               |             | - Transponder and Roadm add-drop noise        |
-|               |             |   contribution and system margin included     |
-|               |             | - Automatic transponders’ mode selection      |
-|               |             | - Route selection with disjunction constraints|
-|               |             | - Detailed carrier information inspection on  |
-|               |             |   each element  along propagation             |
-|               |             | - OpenRoadm noise models                      | 
-|               |             | - bug fixes                                   |
-+---------------+-------------+-----------------------------------------------+
-| Oct 16, 2018  | v1.0        | - first "production"-ready release            |
-|               |             | - open network element model (EDFA, GN-model) |
-|               |             | - auto-design functionality                   |
-|               |             | - path request functionality                  |
-+---------------+-------------+-----------------------------------------------+
-
-How to Install
---------------
-
-   **Note**: `gnpy` supports Python 3 only. Python 2 is not supported.
-   `gnpy` requires Python ≥3.6
-
-   **Note**: the `gnpy` maintainers strongly recommend the use of Anaconda for
-   managing dependencies.
-
-It is recommended that you use a "virtual environment" when installing `gnpy`.
-Do not install `gnpy` on your system Python.
-
-We recommend the use of the Anaconda Python distribution
-(https://www.anaconda.com/download) which comes with many scientific computing
-dependencies pre-installed. Anaconda creates a base "virtual environment" for
-you automatically. You can also create and manage your conda "virtual
-environments" yourself (see:
-https://conda.io/docs/user-guide/tasks/manage-environments.html)
-
-To activate your Anaconda virtual environment, you may need to do the
-following:
-
-.. code-block:: shell
-
-    $ source /path/to/anaconda/bin/activate # activate Anaconda base environment
-    (base) $                                # note the change to the prompt
-
-You can check which Anaconda environment you are using with:
-
-.. code-block:: shell
-
-    (base) $ conda env list                          # list all environments
-    # conda environments:
-    #
-    base                  *  /src/install/anaconda3
-
-    (base) $ echo $CONDA_DEFAULT_ENV                 # show default environment
-    base
-
-You can check your version of Python with the following. If you are using
-Anaconda's Python 3, you should see similar output as below. Your results may
-be slightly different depending on your Anaconda installation path and the
-exact version of Python you are using.
-
-.. code-block:: shell
-
-    $ which python                   # check which Python executable is used
-    /path/to/anaconda/bin/python
-    $ python -V                      # check your Python version
-    Python 3.6.5 :: Anaconda, Inc.
-
-From within your Anaconda Python 3 environment, you can clone the master branch
-of the `gnpy` repo and install it with:
-
-.. code-block:: shell
-
-    $ git clone https://github.com/Telecominfraproject/oopt-gnpy # clone the repo
-    $ cd oopt-gnpy
-    $ python setup.py install                                    # install
-
-To test that `gnpy` was successfully installed, you can run this command. If it
-executes without a `ModuleNotFoundError`, you have successfully installed
-`gnpy`.
-
-.. code-block:: shell
-
-    $ python -c 'import gnpy' # attempt to import gnpy
-
-    $ cd oopt-gnpy
-    $ pytest                  # run tests
-
-Instructions for First Use
---------------------------
-
-``gnpy`` is a library for building route planning and optimization tools.
-
-It ships with a number of example programs. Release versions will ship with
-fully-functional programs.
-
-    **Note**: *If you are a network operator or involved in route planning and
-    optimization for your organization, please contact project maintainer James
-    Powell <james.powell@telecominfraproject>. gnpy is looking for users with
-    specific, delineated use cases to drive requirements for future
-    development.*
-
-**To get started, run the main transmission example:**
-
-    **Note**: *Examples should be run from the examples/ folder.*
-
-.. code-block:: shell
-    $ pwd
-    /path/to/oopt-gnpy
-    $ cd examples
-    $ python transmission_main_example.py
-
-By default, this script operates on a single span network defined in
-`examples/edfa_example_network.json <examples/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
-`examples/CORONET_Global_Topology.json <examples/CORONET_Global_Topology.json>`_:
-
-.. code-block:: shell
-
-    $ cd examples
-    $ python transmission_main_example.py CORONET_Global_Topology.json
-
-It is also possible to use an Excel file input (for example
-`examples/CORONET_Global_Topology.xls <examples/CORONET_Global_Topology.xls>`_).
-The Excel file will be processed into a JSON file with the same prefix. For
-further instructions on how to prepare the Excel input file, see
-`Excel_userguide.rst <Excel_userguide.rst>`_.
-
-The main transmission example will calculate the average signal OSNR and SNR
-across network elements (transceiver, ROADMs, fibers, and amplifiers)
-between two transceivers selected by the user. Additional details are provided by doing ``transmission_main_example.py -h``. (By default, for the CORONET Global
-network, it will show the transmission of spectral information between Abilene and Albany)
-
-This script calculates the average signal OSNR = |OSNR| and SNR = |SNR|.
-
-.. |OSNR| replace:: P\ :sub:`ch`\ /P\ :sub:`ase`
-.. |SNR| replace:: P\ :sub:`ch`\ /(P\ :sub:`nli`\ +\ P\ :sub:`ase`)
-
-|Pase| is the amplified spontaneous emission noise, and |Pnli| the non-linear
-interference noise.
-
-.. |Pase| replace:: P\ :sub:`ase`
-.. |Pnli| replace:: P\ :sub:`nli`
-
-Further Instructions for Use (`transmission_main_example.py`, `path_requests_run.py`)
--------------------------------------------------------------------------------------
-
-Design and transmission parameters are defined in a dedicated json file. By
-default, this information is read from `examples/eqpt_config.json
-<examples/eqpt_config.json>`_. This file defines the equipment libraries that
-can be customized (EDFAs, fibers, and transceivers).
-
-It also defines the simulation parameters (spans, ROADMs, and the spectral
-information to transmit.)
-
-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:
-
-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`. It is not a simple interpolation but a 2-stage NF calculation.
-2. `'type_def': 'fixed_gain'` is a fixed gain model.  `NF == Cte == nf0` if `gain_min < gain < gain_flatmax`
-3. `'type_def': None` is an advanced model. A detailed json configuration file is required (by default `examples/std_medium_gain_advanced_config.json <examples/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.
-
-For all amplifier models:
-
-+----------------------+-----------+-----------------------------------------+
-| field                |   type    | description                             |
-+======================+===========+=========================================+
-| `type_variety`       | (string)  | a unique name to ID the amplifier in the|
-|                      |           | JSON/Excel template topology input file |
-+----------------------+-----------+-----------------------------------------+
-| `out_voa_auto`       | (boolean) | auto_design feature to optimize the     |
-|                      |           | amplifier output VOA. If true, output   |
-|                      |           | VOA is present and will be used to push |
-|                      |           | amplifier gain to its maximum, within   |
-|                      |           | EOL power margins.                      |
-+----------------------+-----------+-----------------------------------------+
-| `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.)         |
-+----------------------+-----------+-----------------------------------------+
-
-The fiber library currently describes SSMF and NZDF but additional fiber types can be entered by the user following the same model:
-
-+----------------------+-----------+-----------------------------------------+
-| field                | type      | description                             |
-+======================+===========+=========================================+
-| `type_variety`       | (string)  | a unique name to ID the fiber in the    |
-|                      |           | JSON or Excel template topology input   |
-|                      |           | file                                    |
-+----------------------+-----------+-----------------------------------------+
-| `dispersion`         | (number)  | (s.m-1.m-1)                             |
-+----------------------+-----------+-----------------------------------------+
-| `gamma`              | (number)  | 2pi.n2/(lambda*Aeff) (w-2.m-1)          |
-+----------------------+-----------+-----------------------------------------+
-
-The transceiver equipment library is a list of supported transceivers. New
-transceivers can be added and existing ones removed at will by the user. It is
-used to determine the service list path feasibility when running the
-path_request_run.py routine.
-
-+----------------------+-----------+-----------------------------------------+
-| field                | type      | description                             |
-+======================+===========+=========================================+
-|  `type_variety`      | (string)  | a unique name to ID the transceiver in  |
-|                      |           | the JSON or Excel template topology     |
-|                      |           | input file                              |
-+----------------------+-----------+-----------------------------------------+
-|  `frequency`         | (number)  | Min/max as below.                       |
-+----------------------+-----------+-----------------------------------------+
-|  `mode`              | (number)  | a list of modes supported by the        |
-|                      |           | transponder. New modes can be added at  |
-|                      |           | will by the user. The modes are specific|
-|                      |           | to each transponder type_variety.       |
-|                      |           | Each mode is described as below.        |
-+----------------------+-----------+-----------------------------------------+
-
-The modes are defined as follows:
-
-+----------------------+-----------+-----------------------------------------+
-| field                | type      | description                             |
-+======================+===========+=========================================+
-| `format`             | (string)  | a unique name to ID the mode.           |
-+----------------------+-----------+-----------------------------------------+
-| `baud_rate`          | (number)  | in Hz                                   |
-+----------------------+-----------+-----------------------------------------+
-| `OSNR`               | (number)  | min required OSNR in 0.1nm (dB)         |
-+----------------------+-----------+-----------------------------------------+
-| `bit_rate`           | (number)  | in bit/s                                |
-+----------------------+-----------+-----------------------------------------+
-| `roll_off`           | (number)  | Not used.                               |
-+----------------------+-----------+-----------------------------------------+
-| `tx_osnr`            | (number)  | In dB. OSNR out from transponder.       |
-+----------------------+-----------+-----------------------------------------+
-| `cost`               | (number)  | Arbitrary unit                          |
-+----------------------+-----------+-----------------------------------------+
-
-Simulation parameters are defined as follows.
-
-Auto-design automatically creates EDFA amplifier network elements when they are
-missing, after a fiber, or between a ROADM and a fiber. This auto-design
-functionality can be manually and locally deactivated by introducing a `Fused`
-network element after a `Fiber` or a `Roadm` that doesn't need amplification.
-The amplifier is chosen in the EDFA list of the equipment library based on
-gain, power, and NF criteria. Only the EDFA that are marked
-`'allowed_for_design': true` are considered.
-
-For amplifiers defined in the topology JSON input but whose gain = 0
-(placeholder), auto-design will set its gain automatically: see `power_mode` in
-the `Spans` library to find out how the gain is calculated.
-
-Span configuration is performed as follows. It is not a list (which may change
-in later releases) and the user can only modify the value of existing
-parameters:
-
-+------------------------+-----------+---------------------------------------------+
-| field                  | type      | description                                 |
-+========================+===========+=============================================+
-| `power_mode`           | (boolean) | If false, gain mode. Auto-design sets       |
-|                        |           | amplifier gain = preceding span loss,      |
-|                        |           | unless the amplifier exists and its         |
-|                        |           | gain > 0 in the topology input json.        |
-|                        |           | If true, power mode (recommended for        |
-|                        |           | auto-design and power sweep.)               |
-|                        |           | Auto-design sets amplifier power            |
-|                        |           | according to delta_power_range. If the      |
-|                        |           | amplifier exists with gain > 0 in the       |
-|                        |           | topology json input, then its gain is       |
-|                        |           | translated into a power target/channel.     |
-|                        |           | Moreover, when performing a power sweep     |
-|                        |           | (see power_range_db in the SI               |
-|                        |           | configuration library) the power sweep      |
-|                        |           | is performed w/r/t this power target,       |
-|                        |           | regardless of preceding amplifiers         |
-|                        |           | power saturation/limitations.               |
-+------------------------+-----------+---------------------------------------------+
-| `delta_power_range_db` | (number)  | Auto-design only, power-mode                |
-|                        |           | only. Specifies the [min, max, step]        |
-|                        |           | power excursion/span. It is a relative      |
-|                        |           | power excursion w/r/t the                   |
-|                        |           | power_dbm + power_range_db                  |
-|                        |           | (power sweep if applicable) defined in      |
-|                        |           | the SI configuration library. This          |
-|                        |           | relative power excursion is = 1/3 of        |
-|                        |           | the span loss difference with the           |
-|                        |           | reference 20 dB span. The 1/3 slope is      |
-|                        |           | derived from the GN model equations.        |
-|                        |           | For example, a 23 dB span loss will be      |
-|                        |           | set to 1 dB more power than a 20 dB         |
-|                        |           | span loss. The 20 dB reference spans        |
-|                        |           | will *always* be set to                     |
-|                        |           | power = power_dbm + power_range_db.         |
-|                        |           | To configure the same power in all          |
-|                        |           | spans, use `[0, 0, 0]`. All spans will      |
-|                        |           | be set to                                   |
-|                        |           | power = power_dbm + power_range_db.         |
-|                        |           | To configure the same power in all spans    |
-|                        |           | and 3 dB more power just for the longest    |
-|                        |           | spans: `[0, 3, 3]`. The longest spans are   |
-|                        |           | set to                                      |
-|                        |           | power = power_dbm + power_range_db + 3.     |
-|                        |           | To configure a 4 dB power range across      |
-|                        |           | all spans in 0.5 dB steps: `[-2, 2, 0.5]`.  |
-|                        |           | A 17 dB span is set to                      |
-|                        |           | power = power_dbm + power_range_db - 1,     |
-|                        |           | a 20 dB span to                             |
-|                        |           | power = power_dbm + power_range_db and      |
-|                        |           | a 23 dB span to                             |
-|                        |           | power = power_dbm + power_range_db + 1      |
-+------------------------+-----------+---------------------------------------------+
-| `max_length`           | (number)  | Split fiber lengths > max_length.           |
-|                        |           | Interest to support high level              |
-|                        |           | topologies that do not specify in line      |
-|                        |           | amplification sites. For example the        |
-|                        |           | CORONET_Global_Topology.xls defines         |
-|                        |           | links > 1000km between 2 sites: it          |
-|                        |           | couldn't be simulated if these links        |
-|                        |           | were not splitted in shorter span           |
-|                        |           | lengths.                                    |
-+------------------------+-----------+---------------------------------------------+
-| `length_unit`          | "m"/"km"  | Unit for max_length.                        |
-+------------------------+-----------+---------------------------------------------+
-| `max_loss`             | (number)  | Not used in the current code                |
-|                        |           | implementation.                             |
-+------------------------+-----------+---------------------------------------------+
-| `padding`              | (number)  | In dB. Min span loss before putting an      |
-|                        |           | attenuator before fiber. Attenuator         |
-|                        |           | value                                       |
-|                        |           | Fiber.att_in = max(0, padding - span_loss). |
-|                        |           | Padding can be set manually to reach a      |
-|                        |           | higher padding value for a given fiber      |
-|                        |           | by filling in the Fiber/params/att_in       |
-|                        |           | field in the topology json input [1]        |
-|                        |           | but if span_loss = length * loss_coef       |
-|                        |           | + att_in + con_in + con_out < padding,      |
-|                        |           | the specified att_in value will be          |
-|                        |           | completed to have span_loss = padding.      |
-|                        |           | Therefore it is not possible to set         |
-|                        |           | span_loss < padding.                        |
-+------------------------+-----------+---------------------------------------------+
-| `EOL`                  | (number)  | All fiber span loss ageing. The value       |
-|                        |           | is added to the con_out (fiber output       |
-|                        |           | connector). So the design and the path      |
-|                        |           | feasibility are performed with              |
-|                        |           | span_loss + EOL. EOL cannot be set          |
-|                        |           | manually for a given fiber span             |
-|                        |           | (workaround is to specify higher con_out    |
-|                        |           | loss for this fiber).                       |
-+------------------------+-----------+---------------------------------------------+
-| `con_in`, `con_out`    | (number)  | Default values if Fiber/params/con_in/out   |
-|                        |           | is None in the topology input               |
-|                        |           | description. This default value is          |
-|                        |           | ignored if a Fiber/params/con_in/out        |
-|                        |           | value is input in the topology for a        |
-|                        |           | given Fiber.                                |
-+------------------------+-----------+---------------------------------------------+
-
-**[1]**
-
-.. code-block:: json
-
-    {
-        "uid": "fiber (A1->A2)",
-        "type": "Fiber",
-        "type_variety": "SSMF",
-        "params":
-        {
-              "type_variety": "SSMF",
-              "length": 120.0,
-              "loss_coef": 0.2,
-              "length_units": "km",
-              "att_in": 0,
-              "con_in": 0,
-              "con_out": 0
-        }
-    }
-
-ROADMs can be configured as follows. The user can only modify the value of
-existing parameters:
-
-+-------------------------+-----------+---------------------------------------------+
-| field                   |   type    | description                                 |
-+=========================+===========+=============================================+
-|`gain_mode_default_loss` | (number)  | Default value if Roadm/params/loss is       |
-|                         |           | None in the topology input description.     |
-|                         |           | This default value is ignored if a          |
-|                         |           | params/loss value is input in the           |
-|                         |           | topology for a given ROADM.                 |
-+-------------------------+-----------+---------------------------------------------+
-|`power_mode_pref`        | (number)  | Power mode only. Auto-design sets the       |
-|                         |           | power of ROADM ingress amplifiers to        |
-|                         |           | power_dbm + power_range_db,                 |
-|                         |           | regardless of existing gain settings        |
-|                         |           | from the topology JSON input.               |
-|                         |           | Auto-design sets the Roadm loss so that     |
-|                         |           | its egress channel power = power_mode_pref, |
-|                         |           | regardless of existing loss settings        |
-|                         |           | from the topology JSON input. It means      |
-|                         |           | that the output power from a ROADM (and      |
-|                         |           | therefore its OSNR contribution) is Cte     |
-|                         |           | and not depending from power_dbm and        |
-|                         |           | power_range_db sweep settings. This         |
-|                         |           | choice is meant to reflect some typical     |
-|                         |           | control loop algorithms.                    |
-+-------------------------+-----------+---------------------------------------------+
-
-The `SpectralInformation` object can be configured as follows. The user can
-only modify the value of existing parameters. It defines a spectrum of N
-identical carriers. While the code libraries allow for different carriers and
-power levels, the current user parametrization only allows one carrier type and
-one power/channel definition.
-
-+----------------------+-----------+-------------------------------------------+
-| field                |   type    | description                               |
-+======================+===========+===========================================+
-| `f_min/max`          | (number)  | In Hz. Carrier min max excursion          |
-+----------------------+-----------+-------------------------------------------+
-| `baud_rate`          | (number)  | In Hz. Simulated baud rate.               |
-+----------------------+-----------+-------------------------------------------+
-| `spacing`            | (number)  | In Hz. Carrier spacing.                   |
-+----------------------+-----------+-------------------------------------------+
-| `roll_off`           | (number)  | Not used.                                 |
-+----------------------+-----------+-------------------------------------------+
-| `OSNR`               | (number)  | Not used.                                 |
-+----------------------+-----------+-------------------------------------------+
-| `bit_rate`           | (number)  | Not used.                                 |
-+----------------------+-----------+-------------------------------------------+
-| `tx_osnr`            | (number)  | In dB. OSNR out from transponder.         |
-+----------------------+-----------+-------------------------------------------+
-| `power_dbm`          | (number)  | Reference channel power. In gain mode     |
-|                      |           | (see spans/power_mode = false), all gain  |
-|                      |           | settings are offset w/r/t this reference  |
-|                      |           | power. In power mode, it is the           |
-|                      |           | reference power for                       |
-|                      |           | Spans/delta_power_range_db. For example,  |
-|                      |           | if delta_power_range_db = `[0,0,0]`, the  |
-|                      |           | same power=power_dbm is launched in every |
-|                      |           | spans. The network design is performed    |
-|                      |           | with the power_dbm value: even if a       |
-|                      |           | power sweep is defined (see after) the    |
-|                      |           | design is not repeated.                   |
-+----------------------+-----------+-------------------------------------------+
-| `power_range_db`     | (number)  | Power sweep excursion around power_dbm.   |
-|                      |           | It is not the min and max channel power   |
-|                      |           | values! The reference power becomes:      |
-|                      |           | power_range_db + power_dbm.               |
-+----------------------+-----------+-------------------------------------------+
-
-The `transmission_main_example.py <examples/transmission_main_example.py>`_
-script propagates a spectrum of channels at 32 Gbaud, 50 GHz spacing and 0
-dBm/channel. These are not yet parametrized but can be modified directly in the
-script (via the SpectralInformation structure) to accommodate any baud rate,
-spacing, power or channel count demand.
-
-Use `examples/path_requests_run.py <examples/path_requests_run.py>`_ to run multiple optimizations as follows:
-
-.. code-block:: shell
-
-     $ python path_requests_run.py -h
-     Usage: path_requests_run.py [-h] [-v] [-o OUTPUT] [network_filename] [service_filename] [eqpt_filename]
-
-The `network_filename` and `service_filename` can be an XLS or JSON file. The `eqpt_filename` must be a JSON file.
-
-To see an example of it, run:
-
-.. code-block:: shell
-
-    $ cd examples
-    $ python path_requests_run.py meshTopologyExampleV2.xls meshTopologyExampleV2_services.json eqpt_config.json -o output_file.json
-
-This program requires a list of connections to be estimated and the equipment
-library. The program computes performances for the list of services (accepts
-json or excel format) using the same spectrum propagation modules as
-transmission_main_example.py. Explanation on the Excel template is provided in
-the `Excel_userguide.rst <Excel_userguide.rst#service-sheet>`_. Template for
-the json format can be found here: `service-template.json
-<service-template.json>`_.
-
-Contributing
-------------
-
-``gnpy`` is looking for additional contributors, especially those with experience
-planning and maintaining large-scale, real-world mesh optical networks.
-
-To get involved, please contact James Powell
-<james.powell@telecominfraproject.com> or Gert Grammel <ggrammel@juniper.net>.
-
-``gnpy`` contributions are currently limited to members of `TIP
-<http://telecominfraproject.com>`_. Membership is free and open to all.
-
-See the `Onboarding Guide
-<https://github.com/Telecominfraproject/gnpy/wiki/Onboarding-Guide>`_ for
-specific details on code contributions.
-
-See `AUTHORS.rst <AUTHORS.rst>`_ for past and present contributors.
-
-Project Background
-------------------
-
-Data Centers are built upon interchangeable, highly standardized node and
-network architectures rather than a sum of isolated solutions. This also
-translates to optical networking. It leads to a push in enabling multi-vendor
-optical network by disaggregating HW and SW functions and focusing on
-interoperability. In this paradigm, the burden of responsibility for ensuring
-the performance of such disaggregated open optical systems falls on the
-operators. Consequently, operators and vendors are collaborating in defining
-control models that can be readily used by off-the-shelf controllers. However,
-node and network models are only part of the answer. To take reasonable
-decisions, controllers need to incorporate logic to simulate and assess optical
-performance. Hence, a vendor-independent optical quality estimator is required.
-Given its vendor-agnostic nature, such an estimator needs to be driven by a
-consortium of operators, system and component suppliers.
-
-Founded in February 2016, the Telecom Infra Project (TIP) is an
-engineering-focused initiative which is operator driven, but features
-collaboration across operators, suppliers, developers, integrators, and
-startups with the goal of disaggregating the traditional network deployment
-approach. The group’s ultimate goal is to help provide better connectivity for
-communities all over the world as more people come on-line and demand more
-bandwidth- intensive experiences like video, virtual reality and augmented
-reality.
-
-Within TIP, the Open Optical Packet Transport (OOPT) project group is chartered
-with unbundling monolithic packet-optical network technologies in order to
-unlock innovation and support new, more flexible connectivity paradigms.
-
-The key to unbundling is the ability to accurately plan and predict the
-performance of optical line systems based on an accurate simulation of optical
-parameters. Under that OOPT umbrella, the Physical Simulation Environment (PSE)
-working group set out to disrupt the planning landscape by providing an open
-source simulation model which can be used freely across multiple vendor
-implementations.
-
-.. |docs| image:: https://readthedocs.org/projects/gnpy/badge/?version=develop
-  :target: http://gnpy.readthedocs.io/en/develop/?badge=develop
-  :alt: Documentation Status
-  :scale: 100%
-
-.. |build| image:: https://travis-ci.com/Telecominfraproject/oopt-gnpy.svg?branch=develop
-  :target: https://travis-ci.com/Telecominfraproject/oopt-gnpy
-  :alt: Build Status
-  :scale: 100%
-
-TIP OOPT/PSE & PSE WG Charter
------------------------------
-
-We believe that openly sharing ideas, specifications, and other intellectual
-property is the key to maximizing innovation and reducing complexity
-
-TIP OOPT/PSE's goal is to build an end-to-end simulation environment which
-defines the network models of the optical device transfer functions and their
-parameters.  This environment will provide validation of the optical
-performance requirements for the TIP OLS building blocks.
-
-- The model may be approximate or complete depending on the network complexity.
-  Each model shall be validated against the proposed network scenario.
-- The environment must be able to process network models from multiple vendors,
-  and also allow users to pick any implementation in an open source framework.
-- The PSE will influence and benefit from the innovation of the DTC, API, and
-  OLS working groups.
-- The PSE represents a step along the journey towards multi-layer optimization.
-
-License
--------
-
-``gnpy`` is distributed under a standard BSD 3-Clause License.
-
-See `LICENSE <LICENSE>`__ for more details.

bindep.txt

@@ -0,0 +1 @@
+graphviz

docs/about-project.md

@@ -0,0 +1,58 @@
+(about-gnpy)=
+# About the project
+
+GNPy is a sponsored project of the [OOPT/PSE](https://telecominfraproject.com/open-optical-packet-transport/) working group of the [Telecom Infra Project](http://telecominfraproject.com).
+
+There are weekly calls about our progress.
+Newcomers, users and telecom operators are especially welcome there.
+We encourage all interested people outside the TIP to [join the project](https://telecominfraproject.com/apply-for-membership/) and especially to [get in touch with us](https://github.com/Telecominfraproject/oopt-gnpy/discussions).
+
+## Contributing
+
+`gnpy` is looking for additional contributors, especially those with experience planning and maintaining large-scale, real-world mesh optical networks.
+
+To get involved, please contact [Jan Kundrát](mailto:jan.kundrat@telecominfraproject.com) or [Gert Grammel](mailto:ggrammel@juniper.net).
+
+`gnpy` contributions are currently limited to members of [TIP](http://telecominfraproject.com).
+Membership is free and open to all.
+
+See the [Onboarding Guide](https://github.com/Telecominfraproject/gnpy/wiki/Onboarding-Guide) for specific details on code contributions, or just [upload patches to our Gerrit](https://review.gerrithub.io/Documentation/intro-gerrit-walkthrough-github.html).
+Here is [what we are currently working on](https://review.gerrithub.io/q/project:Telecominfraproject/oopt-gnpy+status:open).
+
+## Project Background
+
+Data Centers are built upon interchangeable, highly standardized node and network architectures rather than a sum of isolated solutions.
+This also translates to optical networking.
+It leads to a push in enabling multi-vendor optical network by disaggregating HW and SW functions and focusing on interoperability.
+In this paradigm, the burden of responsibility for ensuring the performance of such disaggregated open optical systems falls on the operators.
+Consequently, operators and vendors are collaborating in defining control models that can be readily used by off-the-shelf controllers.
+However, node and network models are only part of the answer.
+To take reasonable decisions, controllers need to incorporate logic to simulate and assess optical performance.
+Hence, a vendor-independent optical quality estimator is required.
+Given its vendor-agnostic nature, such an estimator needs to be driven by a consortium of operators, system and component suppliers.
+
+Founded in February 2016, the Telecom Infra Project (TIP) is an engineering-focused initiative which is operator driven, but features collaboration across operators, suppliers, developers, integrators, and startups with the goal of disaggregating the traditional network deployment approach.
+The group’s ultimate goal is to help provide better connectivity for communities all over the world as more people come on-line and demand more bandwidth-intensive experiences like video, virtual reality and augmented reality.
+
+Within TIP, the Open Optical Packet Transport (OOPT) project group is chartered with unbundling monolithic packet-optical network technologies in order to unlock innovation and support new, more flexible connectivity paradigms.
+
+The key to unbundling is the ability to accurately plan and predict the performance of optical line systems based on an accurate simulation of optical parameters.
+Under that OOPT umbrella, the Physical Simulation Environment (PSE) working group set out to disrupt the planning landscape by providing an open source simulation model which can be used freely across multiple vendor implementations.
+
+## TIP OOPT/PSE & PSE WG Charter
+
+We believe that openly sharing ideas, specifications, and other intellectual property is the key to maximizing innovation and reducing complexity
+
+TIP OOPT/PSE's goal is to build an end-to-end simulation environment which defines the network models of the optical device transfer functions and their parameters.
+This environment will provide validation of the optical performance requirements for the TIP OLS building blocks.
+
+- The model may be approximate or complete depending on the network complexity.
+Each model shall be validated against the proposed network scenario.
+- The environment must be able to process network models from multiple vendors, and also allow users to pick any implementation in an open source framework.
+- The PSE will influence and benefit from the innovation of the DTC, API, and OLS working groups.
+- The PSE represents a step along the journey towards multi-layer optimization.
+
+License
+-------
+
+GNPy is distributed under a standard BSD 3-Clause License.

docs/biblio.bib

@@ -874,7 +874,7 @@ month={Sept},}
   number = {7},
   journal = {Optics Express},
   urlyear = {2017-11-14},
-  year = {2012-03-26},
+  date = {2012-03-26},
   year = {2012},
   pages = {7777},
   author = {Bononi, A. and Serena, P. and Rossi, N. and Grellier, E. and Vacondio, F.}
@@ -1114,7 +1114,7 @@ month={Sept},}
   number = {26},
   journal = {Optics Express},
   urlyear = {2017-11-16},
-  year = {2013-12-30},
+  date = {2013-12-30},
   year = {2013},
   pages = {32254},
   author = {Bononi, Alberto and Beucher, Ottmar and Serena, Paolo}

docs/concepts.rst

@@ -0,0 +1,269 @@
+.. _concepts:
+
+Simulating networks with GNPy
+=============================
+
+Running simulations with GNPy requires three pieces of information:
+
+- the :ref:`network topology<concepts-topology>`, which describes how the network looks like, what are the fiber lengths, what amplifiers are used, etc.,
+- the :ref:`equipment library<concepts-equipment>`, which holds machine-readable datasheets of the equipment used in the network,
+- the :ref:`simulation options<concepts-simulation>` holding instructions about what to simulate, and under which conditions.
+
+.. _concepts-topology:
+
+Network Topology
+----------------
+
+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.
+
+A network topology for GNPy is often a generic, mesh network.
+This enables GNPy to take into consideration the current spectrum allocation as well as availability and resiliency considerations.
+When the time comes to run a particular *propagation* of a signal and its impairments are computed, though, a linear path through the network is used.
+For this purpose, the *path* through the network refers to an ordered, acyclic sequence of *nodes* that are processed.
+This path is directional, and all "GNPy elements" along the path match the unidirectional part of a real-world network equipment.
+
+.. note::
+  In practical terms, an amplifier in GNPy refers to an entity with a single input port and a single output port.
+  A real-world inline EDFA enclosed in a single chassis will be therefore represented as two GNPy-level amplifiers.
+
+The network topology contains not just the physical topology of the network, but also references to the :ref:`equipment library<concepts-equipment>` and a set of *operating parameters* for each entity.
+These parameters include the **fiber length** of each fiber, the connector **attenutation losses**, or an amplifier's specific **gain setting**.
+
+.. _complete-vs-incomplete:
+
+Fully Specified vs. Partially Designed Networks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's consider a simple triangle topology with three :abbr:`PoPs (Points of Presence)` covering three cities:
+
+.. graphviz::
+  :layout: neato
+  :align: center
+
+  graph "High-level topology with three PoPs" {
+    A -- B
+    B -- C
+    C -- A
+  }
+
+In the real world, each city would probably host a ROADM and some transponders:
+
+.. graphviz::
+  :layout: neato
+  :align: center
+
+  graph "Simplified topology with transponders" {
+    "ROADM A" [pos="2,2!"]
+    "ROADM B" [pos="4,2!"]
+    "ROADM C" [pos="3,1!"]
+    "Transponder A" [shape=box, pos="0,2!"]
+    "Transponder B" [shape=box, pos="6,2!"]
+    "Transponder C" [shape=box, pos="3,0!"]
+
+    "ROADM A" -- "ROADM B"
+    "ROADM B" -- "ROADM C"
+    "ROADM C" -- "ROADM A"
+
+    "Transponder A" -- "ROADM A"
+    "Transponder B" -- "ROADM B"
+    "Transponder C" -- "ROADM C"
+  }
+
+GNPy simulation works by propagating the optical signal over a sequence of elements, which means that one has to add some preamplifiers and boosters.
+The amplifiers are, by definition, unidirectional, so the graph becomes quite complex:
+
+.. _topo-roadm-preamp-booster:
+
+.. graphviz::
+  :layout: neato
+  :align: center
+
+  digraph "Preamps and boosters are explicitly modeled in GNPy" {
+    "ROADM A" [pos="2,4!"]
+    "ROADM B" [pos="6,4!"]
+    "ROADM C" [pos="4,0!"]
+    "Transponder A" [shape=box, pos="1,5!"]
+    "Transponder B" [shape=box, pos="7,5!"]
+    "Transponder C" [shape=box, pos="4,-1!"]
+
+    "Transponder A" -> "ROADM A"
+    "Transponder B" -> "ROADM B"
+    "Transponder C" -> "ROADM C"
+    "ROADM A" -> "Transponder A"
+    "ROADM B" -> "Transponder B"
+    "ROADM C" -> "Transponder C"
+
+    "Booster A C" [shape=triangle, orientation=-150, fixedsize=true, width=0.5, height=0.5, pos="2.2,3.2!", color=red, label=""]
+    "Preamp A C" [shape=triangle, orientation=0, fixedsize=true, width=0.5, height=0.5, pos="1.5,3.0!", color=red, label=""]
+    "ROADM A" -> "Booster A C"
+    "Preamp A C" -> "ROADM A"
+
+    "Booster A B" [shape=triangle, orientation=-90, fixedsize=true, width=0.5, height=0.5, pos="3,4.3!", color=red, fontcolor=red, labelloc=b, label="\N\n\n"]
+    "Preamp A B" [shape=triangle, orientation=90, fixedsize=true, width=0.5, height=0.5, pos="3,3.6!", color=red, fontcolor=red, labelloc=t, label="\n        \N"]
+    "ROADM A" -> "Booster A B"
+    "Preamp A B" -> "ROADM A"
+
+    "Booster C B" [shape=triangle, orientation=-30, fixedsize=true, width=0.5, height=0.5, pos="4.7,0.9!", color=red, label=""]
+    "Preamp C B" [shape=triangle, orientation=120, fixedsize=true, width=0.5, height=0.5, pos="5.4,0.7!", color=red, label=""]
+    "ROADM C" -> "Booster C B"
+    "Preamp C B" -> "ROADM C"
+
+    "Booster C A" [shape=triangle, orientation=30, fixedsize=true, width=0.5, height=0.5, pos="2.6,0.7!", color=red, label=""]
+    "Preamp C A" [shape=triangle, orientation=-30, fixedsize=true, width=0.5, height=0.5, pos="3.3,0.9!", color=red, label=""]
+    "ROADM C" -> "Booster C A"
+    "Preamp C A" -> "ROADM C"
+
+    "Booster B A" [shape=triangle, orientation=90, fixedsize=true, width=0.5, height=0.5, pos="5,3.6!", labelloc=t, color=red, fontcolor=red, label="\n\N        "]
+    "Preamp B A" [shape=triangle, orientation=-90, fixedsize=true, width=0.5, height=0.5, pos="5,4.3!", labelloc=b, color=red, fontcolor=red, label="\N\n\n"]
+    "ROADM B" -> "Booster B A"
+    "Preamp B A" -> "ROADM B"
+
+    "Booster B C" [shape=triangle, orientation=-180, fixedsize=true, width=0.5, height=0.5, pos="6.5,3.0!", color=red, label=""]
+    "Preamp B C" [shape=triangle, orientation=-20, fixedsize=true, width=0.5, height=0.5, pos="5.8,3.2!", color=red, label=""]
+    "ROADM B" -> "Booster B C"
+    "Preamp B C" -> "ROADM B"
+
+    "Booster A C" -> "Preamp C A"
+    "Booster A B" -> "Preamp B A"
+    "Booster C A" -> "Preamp A C"
+    "Booster C B" -> "Preamp B C"
+    "Booster B C" -> "Preamp C B"
+    "Booster B A" -> "Preamp A B"
+  }
+
+In many regions, the ROADMs are not placed physically close to each other, so the long-haul fiber links (:abbr:`OMS (Optical Multiplex Section)`) are split into individual spans (:abbr:`OTS (Optical Transport Section)`) by in-line amplifiers, resulting in an even more complicated topology graphs:
+
+.. graphviz::
+  :layout: neato
+  :align: center
+
+  digraph "A subset of a real topology with inline amplifiers" {
+    "ROADM A" [pos="2,4!"]
+    "ROADM B" [pos="6,4!"]
+    "ROADM C" [pos="4,-3!"]
+    "Transponder A" [shape=box, pos="1,5!"]
+    "Transponder B" [shape=box, pos="7,5!"]
+    "Transponder C" [shape=box, pos="4,-4!"]
+
+    "Transponder A" -> "ROADM A"
+    "Transponder B" -> "ROADM B"
+    "Transponder C" -> "ROADM C"
+    "ROADM A" -> "Transponder A"
+    "ROADM B" -> "Transponder B"
+    "ROADM C" -> "Transponder C"
+
+    "Booster A C" [shape=triangle, orientation=-166, fixedsize=true, width=0.5, height=0.5, pos="2.2,3.2!", label=""]
+    "Preamp A C" [shape=triangle, orientation=0, fixedsize=true, width=0.5, height=0.5, pos="1.5,3.0!", label=""]
+    "ROADM A" -> "Booster A C"
+    "Preamp A C" -> "ROADM A"
+
+    "Booster A B" [shape=triangle, orientation=-90, fixedsize=true, width=0.5, height=0.5, pos="3,4.3!", label=""]
+    "Preamp A B" [shape=triangle, orientation=90, fixedsize=true, width=0.5, height=0.5, pos="3,3.6!", label=""]
+    "ROADM A" -> "Booster A B"
+    "Preamp A B" -> "ROADM A"
+
+    "Booster C B" [shape=triangle, orientation=-30, fixedsize=true, width=0.5, height=0.5, pos="4.7,-2.1!", label=""]
+    "Preamp C B" [shape=triangle, orientation=10, fixedsize=true, width=0.5, height=0.5, pos="5.4,-2.3!", label=""]
+    "ROADM C" -> "Booster C B"
+    "Preamp C B" -> "ROADM C"
+
+    "Booster C A" [shape=triangle, orientation=20, fixedsize=true, width=0.5, height=0.5, pos="2.6,-2.3!", label=""]
+    "Preamp C A" [shape=triangle, orientation=-30, fixedsize=true, width=0.5, height=0.5, pos="3.3,-2.1!", label=""]
+    "ROADM C" -> "Booster C A"
+    "Preamp C A" -> "ROADM C"
+
+    "Booster B A" [shape=triangle, orientation=90, fixedsize=true, width=0.5, height=0.5, pos="5,3.6!", label=""]
+    "Preamp B A" [shape=triangle, orientation=-90, fixedsize=true, width=0.5, height=0.5, pos="5,4.3!", label=""]
+    "ROADM B" -> "Booster B A"
+    "Preamp B A" -> "ROADM B"
+
+    "Booster B C" [shape=triangle, orientation=-180, fixedsize=true, width=0.5, height=0.5, pos="6.5,3.0!", label=""]
+    "Preamp B C" [shape=triangle, orientation=-20, fixedsize=true, width=0.5, height=0.5, pos="5.8,3.2!", label=""]
+    "ROADM B" -> "Booster B C"
+    "Preamp B C" -> "ROADM B"
+
+    "Inline A C 1" [shape=triangle, orientation=-166, fixedsize=true, width=0.5, pos="2.4,2.2!", label="                             \N", color=red, fontcolor=red]
+    "Inline A C 2" [shape=triangle, orientation=-166, fixedsize=true, width=0.5, pos="2.6,1.2!", label="                             \N", color=red, fontcolor=red]
+    "Inline A C 3" [shape=triangle, orientation=-166, fixedsize=true, width=0.5, pos="2.8,0.2!", label="                             \N", color=red, fontcolor=red]
+    "Inline A C n" [shape=triangle, orientation=-166, fixedsize=true, width=0.5, pos="3.0,-1.1!", label="                             \N", color=red, fontcolor=red]
+
+    "Booster A C" -> "Inline A C 1"
+    "Inline A C 1" -> "Inline A C 2"
+    "Inline A C 2" -> "Inline A C 3"
+    "Inline A C 3" -> "Inline A C n" [style=dotted]
+    "Inline A C n" -> "Preamp C A"
+    "Booster A B" -> "Preamp B A" [style=dotted]
+    "Booster C A" -> "Preamp A C" [style=dotted]
+    "Booster C B" -> "Preamp B C" [style=dotted]
+    "Booster B C" -> "Preamp C B" [style=dotted]
+    "Booster B A" -> "Preamp A B" [style=dotted]
+  }
+
+In such networks, GNPy's autodesign features becomes very useful.
+It is possible to connect ROADMs via "tentative links" which will be replaced by a sequence of actual fibers and specific amplifiers.
+In other cases where the location of amplifier huts is already known, but the specific EDFA models have not yet been decided, one can put in amplifier placeholders and let GNPy assign the best amplifier.
+
+.. _concepts-equipment:
+
+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.
+Entries in the equipment library correspond to actual real-world, tangible entities.
+Unlike a typical :abbr:`NMS (Network Management System)`, GNPy considers not just the active :abbr:`NEs (Network Elements)` such as amplifiers and :abbr:`ROADMs (Reconfigurable Optical Add/Drop Multiplexers)`, but also the passive ones, such as the optical fiber.
+
+As the signal propagates through the network, the largest source of optical impairments is the noise introduced from amplifiers.
+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.
+
+The amplifiers compensate power losses induced on the signal in the optical fiber.
+The linear losses, however, are just one phenomenon of a multitude of effects that affect the signals in a long fiber run.
+While a more detailed description is available :ref:`in the literature<physical-model>`, for the purpose of the equipment library, the description of the *optical fiber* comprises its **linear attenutation coefficient**, a set of parameters for the **Raman effect**, optical **dispersion**, etc.
+
+Signals are introduced into the network via *transponders*.
+The set of parameters that are required describe the physical properties of each supported *mode* of the transponder, including its **symbol rate**, spectral **width**, etc.
+
+In the junctions of the network, *ROADMs* are used for spectrum routing.
+GNPy currently does not take into consideration the spectrum filtering penalties of the :abbr:`WSSes (Wavelength Selective Switches)`, but the equipment library nonetheless contains a list of required parameters, such as the attenuation options, so that the network can be properly simulated.
+
+.. _concepts-nf-model:
+
+Amplifier Noise Figure Models
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+When in doubt, contact your vendor's technical support and ask them to :ref:`contribute their equipment descriptions<extending-edfa>` to GNPy.
+
+The most accurate noise models describe the resulting NF of an EDFA as a third-degree polynomial.
+GNPy understands polynomials as a NF-yielding function of the :ref:`gain difference from the optimal gain<ext-nf-model-polynomial-NF>`, or as a function of the input power resulting in an incremental OSNR as used in :ref:`OpenROADM inline amplifiers<ext-nf-model-polynomial-OSNR-OpenROADM>` and :ref:`OpenROADM booster/preamps in the ROADMs<ext-nf-model-noise-mask-OpenROADM>`.
+For scenarios where the vendor has not yet contributed an accurate EDFA NF description to GNPy, it is possible to approximate the characteristics via an operator-focused, min-max NF model.
+
+.. _nf-model-min-max-NF:
+
+Min-max 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.
+In these amplifiers, the minimal NF is achieved when the EDFA operates at its maximal (and usually optimal, in terms of flatness) gain.
+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.
+
+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.
+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.
+
+.. _concepts-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.
+
+This set of input parameters include options such as the *spectrum allocation*, i.e., the number of channels and their spacing.
+Various strategies for network optimization can be provided as well.

docs/conf.py

@@ -31,8 +31,17 @@ sys.path.insert(0, os.path.abspath('../'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.githubpages','sphinxcontrib.bibtex']
+              'sphinx.ext.mathjax',
+              'sphinx.ext.githubpages',
+              'sphinxcontrib.bibtex',
+              'sphinx.ext.graphviz',
+              'myst_parser',
+              ]
+
+myst_enable_extensions = [
+    "deflist",
+    "dollarmath",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -48,17 +57,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'gnpy'
-copyright = '2018, Telecom InfraProject - OOPT PSE Group'
-author = 'Telecom InfraProject - OOPT PSE Group'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.1'
-# The full version, including alpha/beta/rc tags.
-release = '0.1'
+copyright = '2018 - 2021, Telecom Infra Project - OOPT PSE Group'
+author = 'Telecom Infra Project - OOPT PSE Group'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -87,8 +87,17 @@ todo_include_todos = False
 on_rtd = os.environ.get('READTHEDOCS') == 'True'
 if on_rtd:
     html_theme = 'default'
+    html_theme_options = {
+        'logo_only': True,
+    }
 else:
     html_theme = 'alabaster'
+    html_theme_options = {
+        'logo': 'images/GNPy-logo.png',
+        'logo_name': False,
+    }
+
+html_logo = 'images/GNPy-logo.png'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -99,7 +108,7 @@ else:
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -148,7 +157,7 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'gnpy.tex', 'gnpy Documentation',
-     'Telecom InfraProject - OOPT PSE Group', 'manual'),
+     'Telecom Infra Project - OOPT PSE Group', 'manual'),
 ]
 
 
@@ -173,5 +182,11 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'private-members': True,
+    'show-inheritance': True,
+}
 
-
+graphviz_output_format = 'svg'

docs/excel.rst

@@ -1,8 +1,7 @@
+Excel (XLS, XLSX) input files
+=============================
 
-How to prepare the Excel input file
------------------------------------
-
-`examples/transmission_main_example.py <examples/transmission_main_example.py>`_ 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.
 
 The file named 'meshTopologyExampleV2.xls' is an example.
 
@@ -16,11 +15,13 @@ In order to work the excel file MUST contain at least 2 sheets:
 - Eqt
 - Service
 
+.. _excel-nodes-sheet:
+
 Nodes sheet
 -----------
 
-Nodes sheet contains seven columns.
-Each line represents a 'node' (ROADM site or an in line amplifier site ILA)::
+Nodes sheet contains nine columns.
+Each line represents a 'node' (ROADM site or an in line amplifier site ILA or a Fused)::
 
   City (Mandatory) ; State ; Country ; Region ; Latitude ; Longitude ; Type
 
@@ -34,13 +35,18 @@ Each line represents a 'node' (ROADM site or an in line amplifier site ILA)::
   - If filled, it can take "ROADM", "FUSED" or "ILA" values. If another string is used, it will be considered as not filled. FUSED means that ingress and egress spans will be fused together.  
 
 - *State*, *Country*, *Region* are not mandatory.
-  "Region" is a holdover from the CORONET topology reference file `CORONET_Global_Topology.xls <examples/CORONET_Global_Topology.xls>`_. CORONET separates its network into geographical regions (Europe, Asia, Continental US.) This information is not used by gnpy.
+  "Region" is a holdover from the CORONET topology reference file `CORONET_Global_Topology.xlsx <gnpy/example-data/CORONET_Global_Topology.xlsx>`_. CORONET separates its network into geographical regions (Europe, Asia, Continental US.) This information is not used by gnpy.
 
 - *Longitude*, *Latitude* are not mandatory. If filled they should contain numbers.
 
+- **Booster_restriction** and **Preamp_restriction** are not mandatory.
+  If used, they must contain one or several amplifier type_variety names separated by ' | '. This information is used to restrict types of amplifiers used in a ROADM node during autodesign. If a ROADM booster or preamp is already specified in the Eqpt sheet , the field is ignored. The field is also ignored if the node is not a ROADM node.
+
 **There MUST NOT be empty line(s) between two nodes lines**
 
 
+.. _excel-links-sheet:
+
 Links sheet
 -----------
 
@@ -77,11 +83,11 @@ and a fiber span from node3 to node6::
 
   - If filled it MUST contain numbers. If empty it is replaced by a default "80" km value. 
   - If value is below 150 km, it is considered as a single (bidirectional) fiber span.
-  - If value is over 150 km the `transmission_main_example.py <examples/transmission_main_example.py>`_ program will automatically suppose that intermediate span description are required and will generate fiber spans elements with "_1","_2", ... trailing strings which are not visible in the json output. The reason for the splitting is that current edfa usually do not support large span loss. The current assumption is that links larger than 150km will require intermediate amplification. This value will be revisited when Raman amplification is added”
+  - If value is over 150 km the `gnpy-transmission-example`` program will automatically suppose that intermediate span description are required and will generate fiber spans elements with "_1","_2", ... trailing strings which are not visible in the json output. The reason for the splitting is that current edfa usually do not support large span loss. The current assumption is that links larger than 150km will require intermediate amplification. This value will be revisited when Raman amplification is added”
 
 - **Fiber type** is not mandatory. 
 
-  If filled it must contain types listed in `eqpt_config.json <examples/eqpt_config.json>`_ in "Fiber" list "type_variety".
+  If filled it must contain types listed in `eqpt_config.json <gnpy/example-data/eqpt_config.json>`_ in "Fiber" list "type_variety".
   If not filled it takes "SSMF" as default value.
 
 - **Lineic att** is not mandatory. 
@@ -110,18 +116,22 @@ and a fiber span from node3 to node6::
 
 (in progress)
 
+.. _excel-equipment-sheet:
+
 Eqpt sheet 
 ----------
 
-Eqt sheet is optional. It lists the amplifiers types and characteristics on each degree of the *Node A* line.
-Eqpt sheet must contain twelve columns::
+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.
 
-                   <--           east cable from a to z        --> <--        west from z to a                 -->
-  Node A ; Node Z ; amp type ; att_in ; amp gain ; tilt ; att_out ; amp type ; att_in ; amp gain ; tilt ; att_out
+This sheet contains twelve columns::
 
-If the sheet is present, it MUST have as many lines as egress directions of ROADMs defined in Links Sheet. 
+                   <--           east cable from a to z                  --> <--        west from z to a                          -->
+  Node A ; Node Z ; amp type ; att_in ; amp gain ; tilt ; att_out ; delta_p ; amp type ; att_in ; amp gain ; tilt ; att_out ; delta_p
 
-For example, consider the following list of links (A,B and C being a ROADM and amp# ILAs)
+If the sheet is present, it MUST have as many lines as there are egress directions of ROADMs defined in Links Sheet, and all ILAs.
+
+For example, consider the following list of links (A, B and C being a ROADM and amp# ILAs):
 
 ::
 
@@ -133,8 +143,8 @@ For example, consider the following list of links (A,B and C being a ROADM and a
 
 then Eqpt sheet should contain:
   - one line for each ILAs: amp1, amp2, amp3 
-  - one line for each degree 1 ROADMs B and C  
-  - two lines for ROADM A  which is a degree 2 ROADM 
+  - one line for each one-degree ROADM (B and C in this example)
+  - two lines for each two-degree ROADM (just the ROADM A)
 
 ::
 
@@ -147,11 +157,11 @@ then Eqpt sheet should contain:
   C    - amp3
 
 
-In case you already have filled Nodes and Links sheets `create_eqpt_sheet.py <examples/create_eqpt_sheet.py>`_  can be used to automatically create a template for the mandatory entries of the list.
+In case you already have filled Nodes and Links sheets `create_eqpt_sheet.py <gnpy/example-data/create_eqpt_sheet.py>`_  can be used to automatically create a template for the mandatory entries of the list.
 
 .. code-block:: shell
 
-    $ cd examples
+    $ cd $(gnpy-example-data)
     $ python create_eqpt_sheet.py meshTopologyExampleV2.xls
 
 This generates a text file meshTopologyExampleV2_eqt_sheet.txt  whose content can be directly copied into the Eqt sheet of the excel file. The user then can fill the values in the rest of the columns.
@@ -164,26 +174,32 @@ This generates a text file meshTopologyExampleV2_eqt_sheet.txt  whose content ca
 - **Node Z** is mandatory. It is the egress direction from the *Node A* site. Multiple Links between the same Node A and NodeZ is not supported.
 
 - **amp type** is not mandatory. 
-  If filled it must contain types listed in `eqpt_config.json <examples/eqpt_config.json>`_ in "Edfa" list "type_variety".
+  If filled it must contain types listed in `eqpt_config.json <gnpy/example-data/eqpt_config.json>`_ in "Edfa" list "type_variety".
   If not filled it takes "std_medium_gain" as default value.
+  If filled with fused, a fused element with 0.0 dB loss will be placed instead of an amplifier. This might be used to avoid booster amplifier on a ROADM direction.
 
 - **amp_gain** is not mandatory. It is the value to be set on the amplifier (in dB).
   If not filled, it will be determined with design rules in the convert.py file.
   If filled, it must contain positive numbers.
 
-- *att_in* and *att_out* are not mandatory and are not used yet. They are the value of the attenautor at input and output of amplifier (in dB).
+- *att_in* and *att_out* are not mandatory and are not used yet. They are the value of the attenuator at input and output of amplifier (in dB).
   If filled they must contain positive numbers.
 
-- *tilt* --TODO--
+- **tilt**, in dB, is not mandatory. It is the target gain tilt over the full amplfifier bandwidth and is defined with regard to wavelength, i.e. negative tilt means lower gain
+  for higher wavelengths (lower frequencies). If not filled, the default value is 0.
+
+- **delta_p**, in dBm,  is not mandatory. If filled it is used to set the output target power per channel at the output of the amplifier, if power_mode is True. The output power is then set to power_dbm + delta_power.
 
 # to be completed #
 
 (in progress)
 
+.. _excel-service-sheet:
+
 Service sheet 
 -------------
 
-Service sheet is optional. It lists the services for which path and feasibility must be computed with path_requests_run.py.
+Service sheet is optional. It lists the services for which path and feasibility must be computed with ``gnpy-path-request``.
 
 Service sheet must contain 11 columns::  
 
@@ -212,36 +228,4 @@ Service sheet must contain 11 columns::
   - path: is the set of ROADM nodes that must be used by the path. It must contain the list of ROADM names that the path must cross. TODO : only ROADM nodes are accepted in this release. Relax this with any type of nodes. If filled it must contain ROADM ids separated by ' | '. Exact names are required. 
   - is loose?  'no' value means that the list of nodes should be strictly followed, while any other value means that the constraint may be relaxed if the node is not reachable. 
 
-- ** path bandwidth** is optional. It is the amount of capacity required between source and destination in Gbit/s. Default value is 0.0 Gbit/s. 
-
-path_requests_run.py
-------------------------
-
-**Usage**: path_requests_run.py [-h] [-v] [-o OUTPUT]
-                            [network_filename xls or json] [service_filename xls or json] [eqpt_filename json]
-
-.. code-block:: shell
-
-    $ cd examples
-    $ python path_requests_run.py meshTopologyExampleV2.xls service_file.json eqpt_file -o output_file.json
-
-A function that computes performances for a list of services provided in the service file (accepts json or excel format.
-
-if the service <file.xls> is in xls format, path_requests_run.py converts it to a json file <file_services.json> following the Yang model for requesting Path Computation defined in `draft-ietf-teas-yang-path-computation-01.txt <https://www.ietf.org/id/draft-ietf-teas-yang-path-computation-01.pdf>`_. For PSE use, additional fields with trx type and mode have been added to the te-bandwidth field. 
-
-A template for the json file can be found here: `service_template.json <service_template.json>`_
-
-
-If no output file is given, the computation is shown on standard output for demo.
-If a file is specified with the optional -o argument, the result of the computation is converted into a json format following  the Yang model for requesting Path Computation defined in `draft-ietf-teas-yang-path-computation-01.txt <https://www.ietf.org/id/draft-ietf-teas-yang-path-computation-01.pdf>`_. TODO: verify that this implementation is correct + give feedback to ietf on what is missing for our specific application.
-
-A template for the result of computation json file can be found here: `path_result_template.json <path_result_template.json>`_
-
-Important note: path_requests_run.py is not a network dimensionning tool : each service does not reserve spectrum, or occupy ressources such as transponders. It only computes path feasibility assuming the spectrum (between defined frequencies) is loaded with "nb of channels" spaced by "spacing" values as specified in the system parameters input in the service file, each cannel having the same characteristics in terms of baudrate, format, ... as the service transponder. The transceiver element acts as a "logical starting/stopping point" for the spectral information propagation. At that point it is not meant to represent the capacity of add drop ports
-As a result transponder type is not part of the network info. it is related to the list of services requests.
-
-In a next step we plan to provide required features to enable dimensionning : alocation of ressources, counting channels, limitation of the number of channels, ...
-
-(in progress)
-
-
+- **path bandwidth** is mandatory. It is the amount of capacity required between source and destination in Gbit/s. Value should be positive (non zero). It is used to compute the amount of required spectrum for the service.  

docs/extending.rst

@@ -0,0 +1,176 @@
+.. _extending:
+
+Extending GNPy with vendor-specific data
+========================================
+
+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>`__.
+
+This chapter discusses option for modeling performance of :ref:`EDFA amplifiers<extending-edfa>`, :ref:`Raman amplifiers<extending-raman>`, :ref:`transponders<extending-transponder>` and :ref:`ROADMs<extending-roadm>`.
+
+.. _extending-edfa:
+
+EDFAs
+-----
+
+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 supports several different :ref:`noise models<concepts-nf-model>`, and vendors are encouraged to pick one which describes performance of their equipment most accurately.
+
+.. _ext-nf-model-polynomial-NF:
+
+Polynomial NF
+*************
+
+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:
+
+.. math::
+
+       f(x) &= \text{a}x^3 + \text{b}x^2 + \text{c}x + \text{d}
+
+  \text{NF} &= f(G_\text{max} - G)
+
+This model can be also used for fixed-gain fixed-NF amplifiers.
+In that case, use:
+
+.. math::
+
+  a = b = c &= 0
+
+          d &= \text{NF}
+
+.. _ext-nf-model-polynomial-OSNR-OpenROADM:
+
+Polynomial OSNR (OpenROADM-style for inline 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.
+
+.. math::
+
+    \text{OSNR}_\text{inc}(P_\text{in}) = \text{a}P_\text{in}^3 + \text{b}P_\text{in}^2 + \text{c}P_\text{in} + \text{d}
+
+.. _ext-nf-model-noise-mask-OpenROADM:
+
+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.
+For the express path, the effective noise mask comprises the preamplifier and the booster.
+When terminating a channel, the same effective noise mask is mandated for a combination of the preamplifier and the drop stage.
+
+GNPy emulates this specification via two special NF models:
+
+- The ``openroadm_preamp`` NF model for preamplifiers.
+  This NF model provides all of the linear impairments to the signal, including those which are incured by the booster in a real network.
+- The ``openroadm_booster`` NF model is a special "zero noise" faux amplifier in place of the booster.
+
+.. _ext-nf-model-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*.
+This approximates a more accurate polynomial description reasonably well for some models of a dual-coil EDFA with a VOA in between.
+In these amplifiers, the minimal NF is achieved when the EDFA operates at its maximal (and usually optimal, in terms of flatness) gain.
+The worst (maximal) NF applies  when the EDFA operates at the minimal gain.
+
+.. _ext-nf-model-dual-stage-amplifier:
+
+Dual-stage
+**********
+
+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.
+
+.. _ext-nf-model-advanced:
+
+Advanced Specification
+**********************
+
+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.
+
+.. _extending-raman:
+
+Raman Amplifiers
+----------------
+
+An accurate simulation of Raman amplification requires knowledge of:
+
+- the *power* and *wavelength* of all Raman pumping lasers,
+- the *direction*, whether it is co-propagating or counter-propagating,
+- the Raman efficiency of the fiber,
+- the fiber temperature.
+
+Under certain scenarios it is useful to be able to run a simulation without an accurate Raman description.
+For these purposes, it is possible to approximate a Raman amplifier via a fixed-gain EDFA with the :ref:`polynomial NF<ext-nf-model-polynomial-NF>` model using :math:`\text{a} = \text{b} = \text{c} = 0`, and a desired effective :math:`\text{d} = NF`.
+This is also useful to quickly approximate a hybrid EDFA+Raman amplifier.
+
+.. _extending-transponder:
+
+Transponders
+------------
+
+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)`.
+
+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.
+``tx-osnr``
+  Initial OSNR at the transmitter's output.
+``grid-spacing``
+  Minimal grid spacing, i.e., an effective channel spectral bandwidth.
+  In :math:`\text{Hz}`.
+``tx-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.
+  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.
+
+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.
+
+.. _extending-roadm:
+
+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>`.
+The set of parameters for each ROADM model therefore includes:
+
+``add-drop-osnr``
+  OSNR penalty introduced by the Add and Drop stages of this ROADM type.
+``target-channel-out-power``
+  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.
+``pmd``
+  Polarization mode dispersion (PMD) penalty of the express path.
+  In :math:`\text{ps}`.
+
+Provisions are in place to define the list of all allowed booster and preamplifier types.
+This is useful for specifying constraints on what amplifier modules fit into ROADM chassis, and when using fully disaggregated ROADM topologies as well.

docs/gnpy-api-core.rst

@@ -0,0 +1,13 @@
+``gnpy.core``
+-------------
+
+.. automodule:: gnpy.core
+.. automodule:: gnpy.core.ansi_escapes
+.. automodule:: gnpy.core.elements
+.. automodule:: gnpy.core.equipment
+.. automodule:: gnpy.core.exceptions
+.. automodule:: gnpy.core.info
+.. automodule:: gnpy.core.network
+.. automodule:: gnpy.core.parameters
+.. automodule:: gnpy.core.science_utils
+.. automodule:: gnpy.core.utils

docs/gnpy-api-tools.rst

@@ -0,0 +1,9 @@
+``gnpy.tools``
+--------------
+
+.. automodule:: gnpy.tools
+.. automodule:: gnpy.tools.cli_examples
+.. automodule:: gnpy.tools.convert
+.. automodule:: gnpy.tools.json_io
+.. automodule:: gnpy.tools.plots
+.. automodule:: gnpy.tools.service_sheet

docs/gnpy-api-topology.rst

@@ -0,0 +1,6 @@
+``gnpy.topology``
+-----------------
+
+.. automodule:: gnpy.topology
+.. automodule:: gnpy.topology.request
+.. automodule:: gnpy.topology.spectrum_assignment

docs/gnpy-api.rst

@@ -0,0 +1,14 @@
+***************************
+API Reference Documentation
+***************************
+
+``gnpy`` package
+================
+
+.. automodule:: gnpy
+
+.. toctree::
+
+   gnpy-api-core
+   gnpy-api-topology
+   gnpy-api-tools

docs/index.rst

@@ -1,33 +1,22 @@
-.. gnpy documentation master file, created by
-   sphinx-quickstart on Mon Dec 18 14:41:01 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+GNPy: Optical Route Planning Library
+=====================================================================
 
-Welcome to gnpy's documentation!
-================================
-
-**gnpy is an open-source, community-developed library for building route planning
-and optimization tools in real-world mesh optical networks.**
-
-`gnpy <http://github.com/telecominfraproject/gnpy>`_ is:
-
-- a sponsored project of the `OOPT/PSE <http://telecominfraproject.com/project-groups-2/backhaul-projects/open-optical-packet-transport/>`_ working group of the `Telecom Infra Project <http://telecominfraproject.com>`_.
-- fully community-driven, fully open source library
-- driven by a consortium of operators, vendors, and academic researchers
-- intended for rapid development of production-grade route planning tools
-- easily extensible to include custom network elements
-- performant to the scale of real-world mesh optical networks
-
-Documentation
-=============
-
-The following pages are meant to describe specific implementation details and
-modeling assumptions behind gnpy. 
+`GNPy <http://github.com/telecominfraproject/gnpy>`_ is an open-source,
+community-developed library for building route planning and optimization tools
+in real-world mesh optical networks. It is based on the Gaussian Noise Model.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
 
+   intro
+   concepts
+   install
+   json
+   excel
+   extending
+   about-project
    model
+   gnpy-api
 
 Indices and tables
 ==================
@@ -36,57 +25,3 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-Contributors in alphabetical order
-==================================
-+----------+------------+-----------------------+--------------------------------------+
-| Name     | Surname    | Affiliation           | Contact                              |
-+==========+============+=======================+======================================+
-| Alessio  | Ferrari    | Politecnico di Torino | alessio.ferrari@polito.it            |
-+----------+------------+-----------------------+--------------------------------------+
-| Anders   | Lindgren   | Telia Company         | Anders.X.Lindgren@teliacompany.com   |
-+----------+------------+-----------------------+--------------------------------------+
-| Andrea   | d'Amico    | Politecnico di Torino | andrea.damico@polito.it              |
-+----------+------------+-----------------------+--------------------------------------+
-| Brian    | Taylor     | Facebook              | briantaylor@fb.com                   |
-+----------+------------+-----------------------+--------------------------------------+
-| David    | Boertjes   | Ciena                 | dboertje@ciena.com                   |
-+----------+------------+-----------------------+--------------------------------------+
-| Esther   | Le Rouzic  | Orange                | esther.lerouzic@orange.com           |
-+----------+------------+-----------------------+--------------------------------------+
-| Gabriele | Galimberti | Cisco                 | ggalimbe@cisco.com                   |
-+----------+------------+-----------------------+--------------------------------------+
-| Gert     | Grammel    | Juniper Networks      | ggrammel@juniper.net                 |
-+----------+------------+-----------------------+--------------------------------------+
-| Gilad    | Goldfarb   | Facebook              | giladg@fb.com                        |
-+----------+------------+-----------------------+--------------------------------------+
-| James    | Powell     | Telecom Infra Project | james.powell@telecominfraproject.com |
-+----------+------------+-----------------------+--------------------------------------+
-| Jeanluc  | Auge       | Orange                | jeanluc.auge@orange.com              |
-+----------+------------+-----------------------+--------------------------------------+
-| Jonas    | Martensson | RISE Research Sweden  | jonas.martensson@ri.se               |
-+----------+------------+-----------------------+--------------------------------------+
-| Mattia   | Cantono    | Politecnico di Torino | mattia.cantono@polito.it             |
-+----------+------------+-----------------------+--------------------------------------+
-| Miguel   | Garrich    | University Catalunya  | miquel.garrich@upct.es               |
-+----------+------------+-----------------------+--------------------------------------+
-| Stefan   | Melin      | Telia Company         | Stefan.Melin@teliacompany.com        |
-+----------+------------+-----------------------+--------------------------------------+
-| Raj      | Nagarajan  | Lumentum              | raj.nagarajan@lumentum.com           |
-+----------+------------+-----------------------+--------------------------------------+
-| Vittorio | Curri      | Politecnico di Torino | vittorio.curri@polito.it             |
-+----------+------------+-----------------------+--------------------------------------+
-
---------------
-
-- Goal is to build an end-to-end simulation environment which defines the
-  network models of the optical device transfer functions and their parameters.
-  This environment will provide validation of the optical performance
-  requirements for the TIP OLS building blocks.   
-- The model may be approximate or complete depending on the network complexity.
-  Each model shall be validated against the proposed network scenario. 
-- The environment must be able to process network models from multiple vendors,
-  and also allow users to pick any implementation in an open source framework. 
-- The PSE will influence and benefit from the innovation of the DTC, API, and
-  OLS working groups.
-- The PSE represents a step along the journey towards multi-layer optimization.
-

docs/install.rst

@@ -0,0 +1,111 @@
+Installing 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>`.
+Developers are encouraged to install the :ref:`Python package in the same way as any other Python package<install-pip>`.
+Note that this needs a :ref:`working installation of Python<install-python>`, for example :ref:`via Anaconda<install-anaconda>`.
+
+.. _install-docker:
+
+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.
+Docker transparently fetches the image over the network upon first use.
+On Linux and Mac, run:
+
+
+.. code-block:: shell-session
+
+    $ docker run -it --rm --volume $(pwd):/shared telecominfraproject/oopt-gnpy
+    root@bea050f186f7:/shared/example-data#
+
+On Windows, launch from Powershell as:
+
+.. code-block:: console
+
+    PS C:\> docker run -it --rm --volume ${PWD}:/shared telecominfraproject/oopt-gnpy
+    root@89784e577d44:/shared/example-data#
+
+In both cases, a directory named ``example-data/`` will appear in your current working directory.
+GNPy automaticallly populates it with example files from the current release.
+Remove that directory if you want to start from scratch.
+
+.. _install-python:
+
+Using Python on your computer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   **Note**: `gnpy` supports Python 3 only. Python 2 is not supported.
+   `gnpy` requires Python ≥3.6
+
+   **Note**: the `gnpy` maintainers strongly recommend the use of Anaconda for
+   managing dependencies.
+
+It is recommended that you use a "virtual environment" when installing `gnpy`.
+Do not install `gnpy` on your system Python.
+
+.. _install-anaconda:
+
+We recommend the use of the `Anaconda Python distribution <https://www.anaconda.com/download>`_ which comes with many scientific computing
+dependencies pre-installed. Anaconda creates a base "virtual environment" for
+you automatically. You can also create and manage your ``conda`` "virtual
+environments" yourself (see:
+https://conda.io/docs/user-guide/tasks/manage-environments.html)
+
+To activate your Anaconda virtual environment, you may need to do the
+following:
+
+.. code-block:: shell-session
+
+    $ source /path/to/anaconda/bin/activate # activate Anaconda base environment
+    (base) $                                # note the change to the prompt
+
+You can check which Anaconda environment you are using with:
+
+.. code-block:: shell-session
+
+    (base) $ conda env list                          # list all environments
+    # conda environments:
+    #
+    base                  *  /src/install/anaconda3
+
+    (base) $ echo $CONDA_DEFAULT_ENV                 # show default environment
+    base
+
+You can check your version of Python with the following. If you are using
+Anaconda's Python 3, you should see similar output as below. Your results may
+be slightly different depending on your Anaconda installation path and the
+exact version of Python you are using.
+
+.. code-block:: shell-session
+
+    $ which python                   # check which Python executable is used
+    /path/to/anaconda/bin/python
+    $ python -V                      # check your Python version
+    Python 3.6.5 :: Anaconda, Inc.
+
+.. _install-pip:
+
+Installing the Python package
+*****************************
+
+From within your Anaconda Python 3 environment, you can clone the master branch
+of the `gnpy` repo and install it with:
+
+.. code-block:: shell-session
+
+    $ git clone https://github.com/Telecominfraproject/oopt-gnpy # clone the repo
+    $ cd oopt-gnpy
+    $ pip install --editable . # note the trailing dot
+
+To test that `gnpy` was successfully installed, you can run this command. If it
+executes without a ``ModuleNotFoundError``, you have successfully installed
+`gnpy`.
+
+.. code-block:: shell-session
+
+    $ python -c 'import gnpy' # attempt to import gnpy
+
+    $ pytest                  # run tests

docs/intro.rst

@@ -0,0 +1,95 @@
+.. _intro:
+
+Introduction
+============
+
+``gnpy`` is a library for building route planning and optimization tools.
+
+It ships with a number of example programs. Release versions will ship with
+fully-functional programs.
+
+    **Note**: *If you are a network operator or involved in route planning and
+    optimization for your organization, please contact project maintainer Jan
+    Kundrát <jan.kundrat@telecominfraproject.com>. gnpy is looking for users with
+    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:
+
+.. image:: https://telecominfraproject.github.io/oopt-gnpy/docs/images/transmission_main_example.svg
+   :width: 100%
+   :align: left
+   :alt: Running a simple simulation example
+   :target: https://asciinema.org/a/252295
+
+By default, this 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>`_:
+
+.. 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>`_).
+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>`__.
+
+The main transmission example will calculate the average signal OSNR and SNR
+across network elements (transceiver, ROADMs, fibers, and amplifiers)
+between two transceivers selected by the user. Additional details are provided by doing ``gnpy-transmission-example -h``. (By default, for the CORONET Global
+network, it will show the transmission of spectral information between Abilene and Albany)
+
+This script calculates the average signal OSNR = |OSNR| and SNR = |SNR|.
+
+.. |OSNR| replace:: P\ :sub:`ch`\ /P\ :sub:`ase`
+.. |SNR| replace:: P\ :sub:`ch`\ /(P\ :sub:`nli`\ +\ P\ :sub:`ase`)
+
+|Pase| is the amplified spontaneous emission noise, and |Pnli| the non-linear
+interference noise.
+
+.. |Pase| replace:: P\ :sub:`ase`
+.. |Pnli| replace:: P\ :sub:`nli`
+
+Further Instructions for Use
+----------------------------
+
+Simulations are driven by a set of `JSON <docs/json.rst>`__ or `XLS <docs/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 can be overridden by using the ``--power`` argument.
+Spectrum information is not yet parametrized but can be modified directly in the ``eqpt_config.json`` (via the ``SpectralInformation`` -SI- structure) to accommodate any baud rate or spacing.
+The number of channel is computed based on ``spacing`` and ``f_min``, ``f_max`` values.
+
+An experimental support for Raman amplification is available:
+
+.. code-block:: shell-session
+
+     $ gnpy-transmission-example \
+       $(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>`_.
+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:
+
+.. code-block:: shell-session
+
+     $ cd $(gnpy-example-data)
+     $ 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).
+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`.
+
+Important note: ``gnpy-path-request`` is not a network dimensionning tool: each service does not reserve spectrum, or occupy ressources such as transponders. It only computes path feasibility assuming the spectrum (between defined frequencies) is loaded with "nb of channels" spaced by "spacing" values as specified in the system parameters input in the service file, each cannel having the same characteristics in terms of baudrate, format,... as the service transponder. The transceiver element acts as a "logical starting/stopping point" for the spectral information propagation. At that point it is not meant to represent the capacity of add drop ports.
+As a result transponder type is not part of the network info. it is related to the list of services requests.
+
+The current version includes a spectrum assigment features that enables to compute a candidate spectrum assignment for each service based on a first fit policy. Spectrum is assigned based on service specified spacing value, path_bandwidth value and selected mode for the transceiver. This spectrum assignment includes a basic capacity planning capability so that the spectrum resource is limited by the frequency min and max values defined for the links. If the requested services reach the link spectrum capacity, additional services feasibility are computed but marked as blocked due to spectrum reason.
+
+OpenROADM networks can be simulated via ``gnpy/example-data/eqpt_config_openroadm.json`` -- see ``gnpy/example-data/Sweden_OpenROADM_example_network.json`` as an example. 

docs/json.rst

@@ -0,0 +1,349 @@
+JSON Input Files
+================
+
+GNPy uses a set of JSON files for modeling the network.
+Some data (such as network topology or the service requests) can be also passed via :ref:`XLS files<excel-service-sheet>`.
+
+Equipment Library
+-----------------
+
+Design and transmission parameters are defined in a dedicated json file.
+By default, this information is read from `gnpy/example-data/eqpt_config.json <https://github.com/Telecominfraproject/oopt-gnpy/blob/master/gnpy/example-data/eqpt_config.json>`_.
+This file defines the equipment libraries that can be customized (EDFAs, fibers, and transceivers).
+
+It also defines the simulation parameters (spans, ROADMs, and the spectral information to transmit.)
+
+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:
+
+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``.
+   It is not a simple interpolation but a 2-stage NF calculation.
+2. ``'type_def': 'fixed_gain'`` is a fixed gain model.
+   `NF == Cte == nf0` if `gain_min < gain < gain_flatmax`
+3. ``'type_def': 'openroadm'`` models the incremental OSNR contribution as a function of input power.
+   It is suitable for inline amplifiers that conform to the OpenROADM specification.
+   The input parameters are coefficients of the :ref:`third-degree polynomial<ext-nf-model-polynomial-OSNR-OpenROADM>`.
+4. ``'type_def': 'openroadm_preamp'`` and ``openroadm_booster`` approximate the :ref:`preamp and booster within an OpenROADM network<ext-nf-model-noise-mask-OpenROADM>`.
+   No extra parameters specific to the NF model are accepted.
+5. ``'type_def': 'advanced_model'`` is an advanced model.
+   A detailed JSON configuration file is required (by default `gnpy/example-data/std_medium_gain_advanced_config.json <https://github.com/Telecominfraproject/oopt-gnpy/blob/master/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.
+
+For all amplifier models:
+
++------------------------+-----------+-----------------------------------------+
+| field                  |   type    | description                             |
++========================+===========+=========================================+
+| ``type_variety``       | (string)  | a unique name to ID the amplifier in the|
+|                        |           | JSON/Excel template topology input file |
++------------------------+-----------+-----------------------------------------+
+| ``out_voa_auto``       | (boolean) | auto_design feature to optimize the     |
+|                        |           | amplifier output VOA. If true, output   |
+|                        |           | VOA is present and will be used to push |
+|                        |           | amplifier gain to its maximum, within   |
+|                        |           | EOL power margins.                      |
++------------------------+-----------+-----------------------------------------+
+| ``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
+~~~~~
+
+The fiber library currently describes SSMF and NZDF but additional fiber types can be entered by the user following the same model:
+
++----------------------+-----------+------------------------------------------+
+| field                | type      | description                              |
++======================+===========+==========================================+
+| ``type_variety``     | (string)  | a unique name to ID the fiber in the     |
+|                      |           | JSON or Excel template topology input    |
+|                      |           | file                                     |
++----------------------+-----------+------------------------------------------+
+| ``dispersion``       | (number)  | In :math:`s \times m^{-1} \times m^{-1}`.|
++----------------------+-----------+------------------------------------------+
+| ``dispersion_slope`` | (number)  | In :math:`s \times m^{-1} \times m^{-1}  |
+|                      |           | \times m^{-1}`                           |
++----------------------+-----------+------------------------------------------+
+| ``gamma``            | (number)  | :math:`2\pi\times n^2/(\lambda*A_{eff})`,|
+|                      |           | in :math:`w^{-1} \times m^{-1}`.         |
++----------------------+-----------+------------------------------------------+
+| ``pmd_coef``         | (number)  | Polarization mode dispersion (PMD)       |
+|                      |           | coefficient. In                          |
+|                      |           | :math:`s\times\sqrt{m}^{-1}`.            |
++----------------------+-----------+------------------------------------------+
+
+Transceiver
+~~~~~~~~~~~
+
+The transceiver equipment library is a list of supported transceivers. New
+transceivers can be added and existing ones removed at will by the user. It is
+used to determine the service list path feasibility when running the
+``gnpy-path-request`` script.
+
++----------------------+-----------+-----------------------------------------+
+| field                | type      | description                             |
++======================+===========+=========================================+
+| ``type_variety``     | (string)  | A unique name to ID the transceiver in  |
+|                      |           | the JSON or Excel template topology     |
+|                      |           | input file                              |
++----------------------+-----------+-----------------------------------------+
+| ``frequency``        | (number)  | Min/max central channel frequency.      |
++----------------------+-----------+-----------------------------------------+
+| ``mode``             | (number)  | A list of modes supported by the        |
+|                      |           | transponder. New modes can be added at  |
+|                      |           | will by the user. The modes are specific|
+|                      |           | to each transponder type_variety.       |
+|                      |           | Each mode is described as below.        |
++----------------------+-----------+-----------------------------------------+
+
+The modes are defined as follows:
+
++----------------------+-----------+-----------------------------------------+
+| field                | type      | description                             |
++======================+===========+=========================================+
+| ``format``           | (string)  | a unique name to ID the mode            |
++----------------------+-----------+-----------------------------------------+
+| ``baud_rate``        | (number)  | in Hz                                   |
++----------------------+-----------+-----------------------------------------+
+| ``OSNR``             | (number)  | min required OSNR in 0.1nm (dB)         |
++----------------------+-----------+-----------------------------------------+
+| ``bit_rate``         | (number)  | in bit/s                                |
++----------------------+-----------+-----------------------------------------+
+| ``roll_off``         | (number)  | Pure number between 0 and 1. TX signal  |
+|                      |           | roll-off shape. Used by Raman-aware     |
+|                      |           | simulation code.                        |
++----------------------+-----------+-----------------------------------------+
+| ``tx_osnr``          | (number)  | In dB. OSNR out from transponder.       |
++----------------------+-----------+-----------------------------------------+
+| ``cost``             | (number)  | Arbitrary unit                          |
++----------------------+-----------+-----------------------------------------+
+
+ROADM
+~~~~~
+
+The user can only modify the value of existing parameters:
+
++--------------------------+-----------+---------------------------------------------+
+| field                    |   type    | description                                 |
++==========================+===========+=============================================+
+| ``target_pch_out_db``    | (number)  | Auto-design sets the ROADM egress channel   |
+|                          |           | power. This reflects typical control loop   |
+|                          |           | algorithms that adjust ROADM losses to      |
+|                          |           | equalize channels (eg coming from different |
+|                          |           | ingress direction or add ports)             |
+|                          |           | This is the default value                   |
+|                          |           | Roadm/params/target_pch_out_db if no value  |
+|                          |           | is given in the ``Roadm`` element in the    |
+|                          |           | topology input description.                 |
+|                          |           | This default value is ignored if a          |
+|                          |           | params/target_pch_out_db value is input in  |
+|                          |           | the topology for a given ROADM.             |
++--------------------------+-----------+---------------------------------------------+
+| ``add_drop_osnr``        | (number)  | OSNR contribution from the add/drop ports   |
++--------------------------+-----------+---------------------------------------------+
+| ``pmd``                  | (number)  | Polarization mode dispersion (PMD). (s)     |
++--------------------------+-----------+---------------------------------------------+
+| ``restrictions``         | (dict of  | If non-empty, keys ``preamp_variety_list``  |
+|                          |  strings) | and ``booster_variety_list`` represent      |
+|                          |           | list of ``type_variety`` amplifiers which   |
+|                          |           | are allowed for auto-design within ROADM's  |
+|                          |           | line degrees.                               |
+|                          |           |                                             |
+|                          |           | If no booster should be placed on a degree, |
+|                          |           | insert a ``Fused`` node on the degree       |
+|                          |           | output.                                     |
++--------------------------+-----------+---------------------------------------------+
+
+Global parameters
+-----------------
+
+The following options are still defined in ``eqpt_config.json`` for legacy reasons, but
+they do not correspond to tangible network devices.
+
+Auto-design automatically creates EDFA amplifier network elements when they are missing, after a fiber, or between a ROADM and a fiber.
+This auto-design functionality can be manually and locally deactivated by introducing a ``Fused`` network element after a ``Fiber`` or a ``Roadm`` that doesn't need amplification.
+The amplifier is chosen in the EDFA list of the equipment library based on gain, power, and NF criteria.
+Only the EDFA that are marked ``'allowed_for_design': true`` are considered.
+
+For amplifiers defined in the topology JSON input but whose ``gain = 0`` (placeholder), auto-design will set its gain automatically: see ``power_mode`` in the ``Spans`` library to find out how the gain is calculated.
+
+Span
+~~~~
+
+Span configuration is not a list (which may change in later releases) and the user can only modify the value of existing parameters:
+
++-------------------------------------+-----------+---------------------------------------------+
+| field                               | type      | description                                 |
++=====================================+===========+=============================================+
+| ``power_mode``                      | (boolean) | If false, gain mode. Auto-design sets       |
+|                                     |           | amplifier gain = preceding span loss,       |
+|                                     |           | unless the amplifier exists and its         |
+|                                     |           | gain > 0 in the topology input JSON.        |
+|                                     |           | If true, power mode (recommended for        |
+|                                     |           | auto-design and power sweep.)               |
+|                                     |           | Auto-design sets amplifier power            |
+|                                     |           | according to delta_power_range. If the      |
+|                                     |           | amplifier exists with gain > 0 in the       |
+|                                     |           | topology JSON input, then its gain is       |
+|                                     |           | translated into a power target/channel.     |
+|                                     |           | Moreover, when performing a power sweep     |
+|                                     |           | (see ``power_range_db`` in the SI           |
+|                                     |           | configuration library) the power sweep      |
+|                                     |           | is performed w/r/t this power target,       |
+|                                     |           | regardless of preceding amplifiers          |
+|                                     |           | power saturation/limitations.               |
++-------------------------------------+-----------+---------------------------------------------+
+| ``delta_power_range_db``            | (number)  | Auto-design only, power-mode                |
+|                                     |           | only. Specifies the [min, max, step]        |
+|                                     |           | power excursion/span. It is a relative      |
+|                                     |           | power excursion w/r/t the                   |
+|                                     |           | power_dbm + power_range_db                  |
+|                                     |           | (power sweep if applicable) defined in      |
+|                                     |           | the SI configuration library. This          |
+|                                     |           | relative power excursion is = 1/3 of        |
+|                                     |           | the span loss difference with the           |
+|                                     |           | reference 20 dB span. The 1/3 slope is      |
+|                                     |           | derived from the GN model equations.        |
+|                                     |           | For example, a 23 dB span loss will be      |
+|                                     |           | set to 1 dB more power than a 20 dB         |
+|                                     |           | span loss. The 20 dB reference spans        |
+|                                     |           | will *always* be set to                     |
+|                                     |           | power = power_dbm + power_range_db.         |
+|                                     |           | To configure the same power in all          |
+|                                     |           | spans, use `[0, 0, 0]`. All spans will      |
+|                                     |           | be set to                                   |
+|                                     |           | power = power_dbm + power_range_db.         |
+|                                     |           | To configure the same power in all spans    |
+|                                     |           | and 3 dB more power just for the longest    |
+|                                     |           | spans: `[0, 3, 3]`. The longest spans are   |
+|                                     |           | set to                                      |
+|                                     |           | power = power_dbm + power_range_db + 3.     |
+|                                     |           | To configure a 4 dB power range across      |
+|                                     |           | all spans in 0.5 dB steps: `[-2, 2, 0.5]`.  |
+|                                     |           | A 17 dB span is set to                      |
+|                                     |           | power = power_dbm + power_range_db - 1,     |
+|                                     |           | a 20 dB span to                             |
+|                                     |           | power = power_dbm + power_range_db and      |
+|                                     |           | a 23 dB span to                             |
+|                                     |           | power = power_dbm + power_range_db + 1      |
++-------------------------------------+-----------+---------------------------------------------+
+| ``max_fiber_lineic_loss_for_raman`` | (number)  | Maximum linear fiber loss for Raman         |
+|                                     |           | amplification use.                          |
++-------------------------------------+-----------+---------------------------------------------+
+| ``max_length``                      | (number)  | Split fiber lengths > max_length.           |
+|                                     |           | Interest to support high level              |
+|                                     |           | topologies that do not specify in line      |
+|                                     |           | amplification sites. For example the        |
+|                                     |           | CORONET_Global_Topology.xlsx defines        |
+|                                     |           | links > 1000km between 2 sites: it          |
+|                                     |           | couldn't be simulated if these links        |
+|                                     |           | were not split in shorter span lengths.     |
++-------------------------------------+-----------+---------------------------------------------+
+| ``length_unit``                     | "m"/"km"  | Unit for ``max_length``.                    |
++-------------------------------------+-----------+---------------------------------------------+
+| ``max_loss``                        | (number)  | Not used in the current code                |
+|                                     |           | implementation.                             |
++-------------------------------------+-----------+---------------------------------------------+
+| ``padding``                         | (number)  | In dB. Min span loss before putting an      |
+|                                     |           | attenuator before fiber. Attenuator         |
+|                                     |           | value                                       |
+|                                     |           | Fiber.att_in = max(0, padding - span_loss). |
+|                                     |           | Padding can be set manually to reach a      |
+|                                     |           | higher padding value for a given fiber      |
+|                                     |           | by filling in the Fiber/params/att_in       |
+|                                     |           | field in the topology json input [1]        |
+|                                     |           | but if span_loss = length * loss_coef       |
+|                                     |           | + att_in + con_in + con_out < padding,      |
+|                                     |           | the specified att_in value will be          |
+|                                     |           | completed to have span_loss = padding.      |
+|                                     |           | Therefore it is not possible to set         |
+|                                     |           | span_loss < padding.                        |
++-------------------------------------+-----------+---------------------------------------------+
+| ``EOL``                             | (number)  | All fiber span loss ageing. The value       |
+|                                     |           | is added to the con_out (fiber output       |
+|                                     |           | connector). So the design and the path      |
+|                                     |           | feasibility are performed with              |
+|                                     |           | span_loss + EOL. EOL cannot be set          |
+|                                     |           | manually for a given fiber span             |
+|                                     |           | (workaround is to specify higher            |
+|                                     |           | ``con_out`` loss for this fiber).           |
++-------------------------------------+-----------+---------------------------------------------+
+| ``con_in``,                         | (number)  | Default values if Fiber/params/con_in/out   |
+| ``con_out``                         |           | is None in the topology input               |
+|                                     |           | description. This default value is          |
+|                                     |           | ignored if a Fiber/params/con_in/out        |
+|                                     |           | value is input in the topology for a        |
+|                                     |           | given Fiber.                                |
++-------------------------------------+-----------+---------------------------------------------+
+
+.. code-block:: json
+
+    {
+        "uid": "fiber (A1->A2)",
+        "type": "Fiber",
+        "type_variety": "SSMF",
+        "params":
+        {
+              "length": 120.0,
+              "loss_coef": 0.2,
+              "length_units": "km",
+              "att_in": 0,
+              "con_in": 0,
+              "con_out": 0
+        }
+    }
+
+SpectralInformation
+~~~~~~~~~~~~~~~~~~~
+
+The user can only modify the value of existing parameters.
+It defines a spectrum of N identical carriers.
+While the code libraries allow for different carriers and power levels, the current user parametrization only allows one carrier type and one power/channel definition.
+
++----------------------+-----------+-------------------------------------------+
+| field                |   type    | description                               |
++======================+===========+===========================================+
+| ``f_min``,           | (number)  | In Hz. Define spectrum boundaries. Note   |
+| ``f_max``            |           | that due to backward compatibility, the   |
+|                      |           | first channel central frequency is placed |
+|                      |           | at :math:`f_{min} + spacing` and the last |
+|                      |           | one at :math:`f_{max}`.                   |
++----------------------+-----------+-------------------------------------------+
+| ``baud_rate``        | (number)  | In Hz. Simulated baud rate.               |
++----------------------+-----------+-------------------------------------------+
+| ``spacing``          | (number)  | In Hz. Carrier spacing.                   |
++----------------------+-----------+-------------------------------------------+
+| ``roll_off``         | (number)  | Pure number between 0 and 1. TX signal    |
+|                      |           | roll-off shape. Used by Raman-aware       |
+|                      |           | simulation code.                          |
++----------------------+-----------+-------------------------------------------+
+| ``tx_osnr``          | (number)  | In dB. OSNR out from transponder.         |
++----------------------+-----------+-------------------------------------------+
+| ``power_dbm``        | (number)  | Reference channel power. In gain mode     |
+|                      |           | (see spans/power_mode = false), all gain  |
+|                      |           | settings are offset w/r/t this reference  |
+|                      |           | power. In power mode, it is the           |
+|                      |           | reference power for                       |
+|                      |           | Spans/delta_power_range_db. For example,  |
+|                      |           | if delta_power_range_db = `[0,0,0]`, the  |
+|                      |           | same power=power_dbm is launched in every |
+|                      |           | spans. The network design is performed    |
+|                      |           | with the power_dbm value: even if a       |
+|                      |           | power sweep is defined (see after) the    |
+|                      |           | design is not repeated.                   |
++----------------------+-----------+-------------------------------------------+
+| ``power_range_db``   | (number)  | Power sweep excursion around power_dbm.   |
+|                      |           | It is not the min and max channel power   |
+|                      |           | values! The reference power becomes:      |
+|                      |           | power_range_db + power_dbm.               |
++----------------------+-----------+-------------------------------------------+
+| ``sys_margins``      | (number)  | In dB. Added margin on min required       |
+|                      |           | transceiver OSNR.                         |
++----------------------+-----------+-------------------------------------------+

docs/model.rst

@@ -1,5 +1,7 @@
-The QoT estimation in the PSE framework of TIP-OOPT
-=======================================================
+.. _physical-model:
+
+Physical Model used in GNPy
+===========================
 
 QoT-E including ASE noise and NLI accumulation 
 ----------------------------------------------

docs/requirements.txt

@@ -0,0 +1,7 @@
+alabaster>=0.7.12,<1
+docutils>=0.15.2,<1
+myst-parser>=0.14.0,<1
+Pygments>=2.7.4,<3
+rstcheck
+Sphinx>=3.5.0,<4
+sphinxcontrib-bibtex>=0.4.2,<1

docs/source/gnpy.core.rst

@@ -1,70 +0,0 @@
-gnpy\.core package
-==================
-
-Submodules
-----------
-
-gnpy\.core\.elements module
----------------------------
-
-.. automodule:: gnpy.core.elements
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.execute module
---------------------------
-
-.. automodule:: gnpy.core.execute
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.info module
------------------------
-
-.. automodule:: gnpy.core.info
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.network module
---------------------------
-
-.. automodule:: gnpy.core.network
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.node module
------------------------
-
-.. automodule:: gnpy.core.node
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.units module
-------------------------
-
-.. automodule:: gnpy.core.units
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-gnpy\.core\.utils module
-------------------------
-
-.. automodule:: gnpy.core.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: gnpy.core
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/gnpy.rst

@@ -1,17 +0,0 @@
-gnpy package
-============
-
-Subpackages
------------
-
-.. toctree::
-
-    gnpy.core
-
-Module contents
----------------
-
-.. automodule:: gnpy
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/modules.rst

@@ -1,7 +0,0 @@
-gnpy
-====
-
-.. toctree::
-   :maxdepth: 4
-
-   gnpy

examples/create_eqpt_sheet.py

@@ -1,103 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-create_eqpt_sheet.py
-====================
-
-XLS parser that can be called to create a "City" column in the "Eqpt" sheet.
-
-If not present in the "Nodes" sheet, the "Type" column will be implicitly
-determined based on the topology.
-"""
-
-from sys import exit
-try:
-    from xlrd import open_workbook
-except ModuleNotFoundError:
-    exit('Required: `pip install xlrd`')
-from argparse import ArgumentParser
-from collections import namedtuple, defaultdict
-
-
-Shortlink = namedtuple('Link', 'src dest')
-
-Shortnode = namedtuple('Node', 'nodename eqt')
-
-parser = ArgumentParser()
-parser.add_argument('workbook', nargs='?', default='meshTopologyExampleV2.xls',
-    help = 'create the mandatory columns in Eqpt sheet  ')
-all_rows = lambda sh, start=0: (sh.row(x) for x in range(start, sh.nrows))
-
-def read_excel(input_filename):
-    with open_workbook(input_filename) as wb:
-        # reading Links sheet
-        links_sheet = wb.sheet_by_name('Links')
-        links = []
-        nodeoccuranceinlinks = []
-        links_by_src = defaultdict(list)
-        links_by_dest = defaultdict(list)
-        for row in all_rows(links_sheet, start=5):
-            links.append(Shortlink(row[0].value,row[1].value))
-            links_by_src[row[0].value].append(Shortnode(row[1].value,''))
-            links_by_dest[row[1].value].append(Shortnode(row[0].value,''))
-            #print(f'source {links[len(links)-1].src} dest {links[len(links)-1].dest}')
-            nodeoccuranceinlinks.append(row[0].value)
-            nodeoccuranceinlinks.append(row[1].value)
-
-        # reading Nodes sheet
-        nodes_sheet = wb.sheet_by_name('Nodes')
-        nodes = []
-        node_degree = []
-        for row in all_rows(nodes_sheet, start=5) :
-
-            temp_eqt = row[6].value
-            # verify node degree to confirm eqt type
-            node_degree.append(nodeoccuranceinlinks.count(row[0].value))
-            if temp_eqt.lower() == 'ila' and nodeoccuranceinlinks.count(row[0].value) !=2 :
-                print(f'Inconsistancy: node {nodes[len(nodes)-1]} has degree \
-                    {node_degree[len(nodes)-1]} and can not be an ILA ... replaced by ROADM')
-                temp_eqt = 'ROADM'
-            if temp_eqt == '' and nodeoccuranceinlinks.count(row[0].value) == 2 :
-                temp_eqt = 'ILA'
-            if temp_eqt == '' and nodeoccuranceinlinks.count(row[0].value) != 2 :
-                temp_eqt = 'ROADM'
-            # print(f'node {nodes[len(nodes)-1]} eqt {temp_eqt}')
-            nodes.append(Shortnode(row[0].value,temp_eqt))
-            # print(len(nodes)-1)
-            print(f'reading: node {nodes[len(nodes)-1].nodename} eqpt {temp_eqt}')
-        return links,nodes, links_by_src , links_by_dest
-
-def create_eqt_template(links,nodes, links_by_src , links_by_dest, input_filename):
-    output_filename = f'{input_filename[:-4]}_eqpt_sheet.txt'
-    with open(output_filename, 'w', encoding='utf-8') as my_file:
-        # print header similar to excel
-        my_file.write('OPTIONAL\n\n\n\
-           \t\tNode a egress amp (from a to z)\t\t\t\t\tNode a ingress amp (from z to a) \
-           \nNode A \tNode Z \tamp type \tatt_in \tamp gain \ttilt \tatt_out\
-           amp type   \tatt_in \tamp gain   \ttilt   \tatt_out\n')
-
-        tab = []
-        temp = []
-        i = 0
-        for lk in links:
-            if [e for n,e in nodes if n==lk.src][0] != 'FUSED' :
-                temp = [lk.src , lk.dest]
-                tab.append(temp)
-                my_file.write(f'{temp[0]}\t{temp[1]}\n')
-        for n in nodes :
-            if n.eqt.lower() == 'roadm' :
-                for src in  links_by_dest[n.nodename] :
-                    temp = [n.nodename , src.nodename]
-                    tab.append(temp)
-                    # print(temp)
-                    my_file.write(f'{temp[0]}\t{temp[1]}\n')
-            i = i + 1
-        print(f'File {output_filename} successfully created with Node A - Node Z ' +
-        ' entries for Eqpt sheet in excel file.')
-
-if __name__ == '__main__':
-    args = parser.parse_args()
-    input_filename = args.workbook
-    links,nodes,links_by_src, links_by_dest = read_excel(input_filename)
-    create_eqt_template(links,nodes, links_by_src , links_by_dest , input_filename)

examples/edfa_model/OA.json

@@ -1,5 +0,0 @@
-{
-    "nf_ripple": "NFR0_96.txt", 
-    "gain_ripple": "DFG0_96.txt",
-    "dgt": "DGT_96.txt"    
-}

examples/edfa_model/Pchan2D.txt

@@ -1,8 +0,0 @@
-  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01
-  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02
-  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01  -2.0000000000000000e+01
-  -2.0500000000000000e+01  -2.0489473680000000e+01  -2.0478947370000000e+01  -2.0468421050000000e+01  -2.0457894740000000e+01  -2.0447368420000000e+01  -2.0436842110000001e+01  -2.0426315790000000e+01  -2.0415789470000000e+01  -2.0405263160000001e+01  -2.0394736840000000e+01  -2.0384210530000001e+01  -2.0373684210000000e+01  -2.0363157890000000e+01  -2.0352631580000001e+01  -2.0342105260000000e+01  -2.0331578950000001e+01  -2.0321052630000001e+01  -2.0310526320000001e+01  -2.0300000000000001e+01  -2.0289473680000000e+01  -2.0278947370000001e+01  -2.0268421050000001e+01  -2.0257894740000001e+01  -2.0247368420000001e+01  -2.0236842110000001e+01  -2.0226315790000001e+01  -2.0215789470000001e+01  -2.0205263160000001e+01  -2.0194736840000001e+01  -2.0184210530000001e+01  -2.0173684210000001e+01  -2.0163157890000001e+01  -2.0152631580000001e+01  -2.0142105260000001e+01  -2.0131578950000002e+01  -2.0121052630000001e+01  -2.0110526320000002e+01  -2.0100000000000001e+01  -2.0089473680000001e+01  -2.0078947370000002e+01  -2.0068421050000001e+01  -2.0057894739999998e+01  -2.0047368420000002e+01  -2.0036842109999998e+01  -2.0026315790000002e+01  -2.0015789470000001e+01  -2.0005263159999998e+01  -1.9994736840000002e+01  -1.9984210529999999e+01  -1.9973684209999998e+01  -1.9963157890000002e+01  -1.9952631579999998e+01  -1.9942105260000002e+01  -1.9931578949999999e+01  -1.9921052629999998e+01  -1.9910526319999999e+01  -1.9899999999999999e+01  -1.9889473679999998e+01  -1.9878947369999999e+01  -1.9868421049999998e+01  -1.9857894739999999e+01  -1.9847368419999999e+01  -1.9836842109999999e+01  -1.9826315789999999e+01  -1.9815789469999999e+01  -1.9805263159999999e+01  -1.9794736839999999e+01  -1.9784210529999999e+01  -1.9773684209999999e+01  -1.9763157889999999e+01  -1.9752631579999999e+01  -1.9742105259999999e+01  -1.9731578949999999e+01  -1.9721052629999999e+01  -1.9710526320000000e+01  -1.9699999999999999e+01  -1.9689473679999999e+01  -1.9678947369999999e+01  -1.9668421049999999e+01  -1.9657894740000000e+01  -1.9647368419999999e+01  -1.9636842110000000e+01  -1.9626315790000000e+01  -1.9615789469999999e+01  -1.9605263160000000e+01  -1.9594736839999999e+01  -1.9584210530000000e+01  -1.9573684210000000e+01  -1.9563157889999999e+01  -1.9552631580000000e+01  -1.9542105260000000e+01  -1.9531578950000000e+01  -1.9521052630000000e+01  -1.9510526320000000e+01  -1.9500000000000000e+01
-  -2.0500000000000000e+01  -2.0489473680000000e+01  -2.0478947370000000e+01  -2.0468421050000000e+01  -2.0457894740000000e+01  -2.0447368420000000e+01  -2.0436842110000001e+01  -2.0426315790000000e+01  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.9573684210000000e+01  -1.9563157889999999e+01  -1.9552631580000000e+01  -1.9542105260000000e+01  -1.9531578950000000e+01  -1.9521052630000000e+01  -1.9510526320000000e+01  -1.9500000000000000e+01
-  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.4460000000000001e+01
-  -1.4460000000000001e+01  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01  -1.4460000000000001e+01
-  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.4460000000000001e+01  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02  -1.0000000000000000e+02

examples/edfa_model/Pchan2DLegend.txt

@@ -1,8 +0,0 @@
-   7.0000000000000000e+01	   1.1700000000000000e+02	   1.0800000000000000e+02	   1.0800000000000000e+02	   3.2000000000000000e+01	   7.0000000000000000e+01	   1.0800000000000000e+02	   9.7000000000000000e+01	   1.1600000000000000e+02	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	
-   7.9000000000000000e+01	   1.1000000000000000e+02	   1.0100000000000000e+02	   3.2000000000000000e+01	   7.1000000000000000e+01	   1.1400000000000000e+02	   1.1100000000000000e+02	   1.1700000000000000e+02	   1.1200000000000000e+02	   3.2000000000000000e+01	   6.6000000000000000e+01	   1.0800000000000000e+02	   1.1700000000000000e+02	   1.0100000000000000e+02	   3.2000000000000000e+01	
-   7.9000000000000000e+01	   1.1000000000000000e+02	   1.0100000000000000e+02	   3.2000000000000000e+01	   7.1000000000000000e+01	   1.1400000000000000e+02	   1.1100000000000000e+02	   1.1700000000000000e+02	   1.1200000000000000e+02	   3.2000000000000000e+01	   8.2000000000000000e+01	   1.0100000000000000e+02	   1.0000000000000000e+02	   3.2000000000000000e+01	   3.2000000000000000e+01	
-   7.0000000000000000e+01	   1.1700000000000000e+02	   1.0800000000000000e+02	   1.0800000000000000e+02	   3.2000000000000000e+01	   1.1900000000000000e+02	   3.2000000000000000e+01	   8.3000000000000000e+01	   8.2000000000000000e+01	   8.3000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	
-   6.6000000000000000e+01	   1.1100000000000000e+02	   1.1600000000000000e+02	   1.0400000000000000e+02	   3.2000000000000000e+01	   6.9000000000000000e+01	   1.1000000000000000e+02	   1.0000000000000000e+02	   1.1500000000000000e+02	   3.2000000000000000e+01	   1.1900000000000000e+02	   3.2000000000000000e+01	   8.3000000000000000e+01	   8.2000000000000000e+01	   8.3000000000000000e+01	
-   1.0400000000000000e+02	   1.0100000000000000e+02	   9.7000000000000000e+01	   1.1800000000000000e+02	   1.2100000000000000e+02	   3.2000000000000000e+01	   9.8000000000000000e+01	   1.0800000000000000e+02	   1.1700000000000000e+02	   1.0100000000000000e+02	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	
-   1.0400000000000000e+02	   1.0100000000000000e+02	   9.7000000000000000e+01	   1.1800000000000000e+02	   1.2100000000000000e+02	   3.2000000000000000e+01	   1.1400000000000000e+02	   1.0100000000000000e+02	   1.0000000000000000e+02	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	
-   1.1900000000000000e+02	   1.1100000000000000e+02	   1.1400000000000000e+02	   1.1500000000000000e+02	   1.1600000000000000e+02	   3.2000000000000000e+01	   9.9000000000000000e+01	   9.7000000000000000e+01	   1.1500000000000000e+02	   1.0100000000000000e+02	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	   3.2000000000000000e+01	

examples/edfa_model/amplifier.py

@@ -1,301 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-Created on Mon Nov 27 12:32:04 2017
-
-@author: briantaylor
-"""
-import numpy as np
-from numpy import polyfit, polyval, mean
-from utilities import lin2db, db2lin, itufs, freq2wavelength
-import matplotlib.pyplot as plt
-from scipy.constants import h
-
-
-def noise_profile(nf, gain, ffs, df):
-    """ noise_profile(nf, gain, ffs, df) computes amplifier ase
-
-    :param nf: Noise figure in dB
-    :param gain: Actual gain calculated for the EDFA in dB units
-    :param ffs: A numpy array of frequencies
-    :param df: the reference bw in THz
-    :type nf: numpy.ndarray
-    :type gain: numpy.ndarray
-    :type ffs: numpy.ndarray
-    :type df: float
-    :return: the asepower in dBm
-    :rtype: numpy.ndarray
-
-    ASE POWER USING PER CHANNEL GAIN PROFILE
-    INPUTS:
-    NF_dB - Noise figure in dB, vector of length number of channels or
-            spectral slices
-    G_dB  - Actual gain calculated for the EDFA, vector of length number of
-            channels or spectral slices
-    ffs     - Center frequency grid of the channels or spectral slices in THz,
-            vector of length number of channels or spectral slices
-    dF    - width of each channel or spectral slice in THz,
-            vector of length number of channels or spectral slices
-    OUTPUT:
-        ase_dBm - ase in dBm per channel or spectral slice
-    NOTE: the output is the total ASE in the channel or spectral slice. For
-    50GHz channels the ASE BW is effectively 0.4nm. To get to noise power in
-    0.1nm, subtract 6dB.
-
-    ONSR is usually quoted as channel power divided by
-    the ASE power in 0.1nm RBW, regardless of the width of the actual
-    channel.  This is a historical convention from the days when optical
-    signals were much smaller (155Mbps, 2.5Gbps, ... 10Gbps) than the
-    resolution of the OSAs that were used to measure spectral power which
-    were set to 0.1nm resolution for convenience.  Moving forward into
-    flexible grid and high baud rate signals, it may be convenient to begin
-    quoting power spectral density in the same BW for both signal and ASE,
-    e.g. 12.5GHz."""
-
-    h_mWThz = 1e-3 * h * (1e14)**2
-    nf_lin = db2lin(nf)
-    g_lin = db2lin(gain)
-    ase = h_mWThz * df * ffs * (nf_lin * g_lin - 1)
-    asedb = lin2db(ase)
-
-    return asedb
-
-
-def gain_profile(dfg, dgt, Pin, gp, gtp):
-    """
-    :param dfg: design flat gain
-    :param dgt: design gain tilt
-    :param Pin: channing input power profile
-    :param gp: Average gain setpoint in dB units
-    :param gtp: gain tilt setting
-    :type dfg: numpy.ndarray
-    :type dgt: numpy.ndarray
-    :type Pin: numpy.ndarray
-    :type gp: float
-    :type gtp: float
-    :return: gain profile in dBm
-    :rtype: numpy.ndarray
-
-    AMPLIFICATION USING INPUT PROFILE
-    INPUTS:
-        DFG - vector of length number of channels or spectral slices
-        DGT - vector of length number of channels or spectral slices
-        Pin - input powers vector of length number of channels or
-        spectral slices
-        Gp  - provisioned gain length 1
-        GTp - provisioned tilt length 1
-
-    OUTPUT:
-        amp gain per channel or spectral slice
-    NOTE: there is no checking done for violations of the total output power
-        capability of the amp.
-        Ported from Matlab version written by David Boerges at Ciena.
-    Based on:
-        R. di Muro, "The Er3+ fiber gain coefficient derived from a dynamic
-        gain
-        tilt technique", Journal of Lightwave Technology, Vol. 18, Iss. 3,
-        Pp. 343-347, 2000.
-    """
-    err_tolerance = 1.0e-11
-    simple_opt = True
-
-    # TODO make all values linear unit and convert to dB units as needed within
-    # this function.
-    nchan = list(range(len(Pin)))
-
-    # TODO find a way to use these or lose them.  Primarily we should have a
-    # way to determine if exceeding the gain or output power of the amp
-    tot_in_power_db = lin2db(np.sum(db2lin(Pin)))
-    avg_gain_db = lin2db(mean(db2lin(dfg)))
-
-    # Linear fit to get the
-    p = polyfit(nchan, dgt, 1)
-    dgt_slope = p[0]
-
-    # Calculate the target slope-  Currently assumes equal spaced channels
-    # TODO make it so that supports arbitrary channel spacing.
-    targ_slope = gtp / (len(nchan) - 1)
-
-    # 1st estimate of DGT scaling
-    dgts1 = targ_slope / dgt_slope
-
-    # when simple_opt is true code makes 2 attempts to compute gain and
-    # the internal voa value.  This is currently here to provide direct
-    # comparison with original Matlab code.  Will be removed.
-    # TODO replace with loop
-
-    if simple_opt:
-
-        # 1st estimate of Er gain & voa loss
-        g1st = dfg + dgt * dgts1
-        voa = lin2db(mean(db2lin(g1st))) - gp
-
-        # 2nd estimate of Amp ch gain using the channel input profile
-        g2nd = g1st - voa
-        pout_db = lin2db(np.sum(db2lin(Pin + g2nd)))
-        dgts2 = gp - (pout_db - tot_in_power_db)
-
-        # Center estimate of amp ch gain
-        xcent = dgts2
-        gcent = g1st - voa + dgt * xcent
-        pout_db = lin2db(np.sum(db2lin(Pin + gcent)))
-        gavg_cent = pout_db - tot_in_power_db
-
-        # Lower estimate of Amp ch gain
-        deltax = np.max(g1st) - np.min(g1st)
-        xlow = dgts2 - deltax
-        glow = g1st - voa + xlow * dgt
-        pout_db = lin2db(np.sum(db2lin(Pin + glow)))
-        gavg_low = pout_db - tot_in_power_db
-
-        # Upper gain estimate
-        xhigh = dgts2 + deltax
-        ghigh = g1st - voa + xhigh * dgt
-        pout_db = lin2db(np.sum(db2lin(Pin + ghigh)))
-        gavg_high = pout_db - tot_in_power_db
-
-        # compute slope
-        slope1 = (gavg_low - gavg_cent) / (xlow - xcent)
-        slope2 = (gavg_cent - gavg_high) / (xcent - xhigh)
-
-        if np.abs(gp - gavg_cent) <= err_tolerance:
-            dgts3 = xcent
-        elif gp < gavg_cent:
-            dgts3 = xcent - (gavg_cent - gp) / slope1
-        else:
-            dgts3 = xcent + (-gavg_cent + gp) / slope2
-
-        gprofile = g1st - voa + dgt * dgts3
-    else:
-        gprofile = None
-
-    return gprofile
-
-
-if __name__ == '__main__':
-
-    plt.close('all')
-    fc = itufs(0.05)
-    lc = freq2wavelength(fc) / 1000
-    nchan = list(range(len(lc)))
-    df = np.array([0.05] * (nchan[-1] + 1))
-    # TODO remove path dependence
-    path = ''
-
-    """
-    DFG_96:  Design flat gain at each wavelength in the 96 channel 50GHz ITU
-    grid in dB.  This can be experimentally determined by measuring the gain
-    at each wavelength using a full, flat channel (or ASE) load at the input.
-    The amplifier should be set to its maximum flat gain (tilt = 0dB).  This
-    measurement captures the ripple of the amplifier.  If the amplifier was
-    designed to be mimimum ripple at some other tilt value, then the ripple
-    reflected in this measurement will not be that minimum.  However, when
-    the DGT gets applied through the provisioning of tilt, the model should
-    accurately reproduce the expected ripple at that tilt value.  One could
-    also do the measurement at some expected tilt value and back-calculate
-    this vector using the DGT method.  Alternatively, one could re-write the
-    algorithm to accept a nominal tilt and a tiled version of this vector.
-    """
-
-    dfg_96 = np.loadtxt(path + 'DFG_96.txt')
-
-    """maximum gain for flat operation - the amp in the data file was designed
-    for 25dB gain and has an internal VOA for setting the external gain
-    """
-
-    avg_dfg = dfg_96.mean()
-
-    """
-    DGT_96:  This is the so-called Dynamic Gain Tilt of the EDFA in dB/dB. It
-    is the change in gain at each wavelength corresponding to a 1dB change at
-    the longest wavelength supported.  The value can be obtained
-    experimentally or through analysis of the cross sections or Giles
-    parameters of the Er fibre.  This is experimentally measured by changing
-    the gain of the amplifier above the maximum flat gain while not changing
-    the internal VOA (i.e. the mid-stage VOA is set to minimum and does not
-    change during the measurement). Note that the measurement can change the
-    gain by an arbitrary amount and divide by the gain change (in dB) which
-    is measured at the reference wavelength (the red end of the band).
-    """
-
-    dgt_96 = np.loadtxt(path + 'DGT_96.txt')
-
-    """
-    pNFfit3:  Cubic polynomial fit coefficients to noise figure in dB
-    averaged across wavelength as a function of gain change from design flat:
-
-        NFavg = pNFfit3(1)*dG^3 + pNFfit3(2)*dG^2 pNFfit3(3)*dG + pNFfit3(4)
-    where
-        dG = GainTarget - average(DFG_96)
-    note that dG will normally be a negative value.
-    """
-
-    nf_fitco = np.loadtxt(path + 'pNFfit3.txt')
-
-    """NFR_96:  Noise figure ripple in dB away from the average noise figure
-    across the band.  This captures the wavelength dependence of the NF.  To
-    calculate the NF across channels, one uses the cubic fit coefficients
-    with the external gain target to get the average nosie figure, NFavg and
-    then adds this to NFR_96:
-    NF_96 = NFR_96 + NFavg
-    """
-
-    nf_ripple = np.loadtxt(path + 'NFR_96.txt')
-
-    # This is an example to set the provisionable gain and gain-tilt values
-    # Tilt is in units of dB/THz
-    gain_target = 20.0
-    tilt_target = -0.7
-
-    # calculate the NF for the EDFA at this gain setting
-    dg = gain_target - avg_dfg
-    nf_avg = polyval(nf_fitco, dg)
-    nf_96 = nf_ripple + nf_avg
-
-    # get the input power profiles to show
-    pch2d = np.loadtxt(path + 'Pchan2D.txt')
-
-    # Load legend and assemble legend text
-    pch2d_legend_data = np.loadtxt(path + 'Pchan2DLegend.txt')
-    pch2d_legend = []
-    for ea in pch2d_legend_data:
-        s = ''.join([chr(xx) for xx in ea.astype(dtype=int)]).strip()
-        pch2d_legend.append(s)
-
-    # assemble plot
-    axis_font = {'fontname': 'Arial', 'size': '16', 'fontweight': 'bold'}
-    title_font = {'fontname': 'Arial', 'size': '17', 'fontweight': 'bold'}
-    tic_font = {'fontname': 'Arial', 'size': '12'}
-
-    plt.rcParams["font.family"] = "Arial"
-    plt.figure()
-    plt.plot(nchan, pch2d.T, '.-', lw=2)
-    plt.xlabel('Channel Number', **axis_font)
-    plt.ylabel('Channel Power [dBm]', **axis_font)
-    plt.title('Input Power Profiles for Different Channel Loading',
-              **title_font)
-    plt.legend(pch2d_legend, loc=5)
-    plt.grid()
-    plt.ylim((-100, -10))
-    plt.xlim((0, 110))
-    plt.xticks(np.arange(0, 100, 10), **tic_font)
-    plt.yticks(np.arange(-110, -10, 10), **tic_font)
-
-    plt.figure()
-    ea = pch2d[1, :]
-    for ea in pch2d:
-        chgain = gain_profile(dfg_96, dgt_96, ea, gain_target, tilt_target)
-        pase = noise_profile(nf_96, chgain, fc, df)
-        pout = lin2db(db2lin(ea + chgain) + db2lin(pase))
-        plt.plot(nchan, pout, '.-', lw=2)
-    plt.title('Output Power with ASE for Different Channel Loading',
-              **title_font)
-    plt.xlabel('Channel Number', **axis_font)
-    plt.ylabel('Channel Power [dBm]', **axis_font)
-    plt.grid()
-    plt.ylim((-50, 10))
-    plt.xlim((0, 100))
-    plt.xticks(np.arange(0, 100, 10), **tic_font)
-    plt.yticks(np.arange(-50, 10, 10), **tic_font)
-    plt.legend(pch2d_legend, loc=5)
-    plt.show()

examples/edfa_model/edfa_config.json

@@ -1,313 +0,0 @@
-{
-    "params": {
-        "gain_flatmax": 25,
-        "gain_min": 15,
-        "p_max": 21,
-        "nf_fit_coeff": [
-            0.000168241,
-            0.0469961,
-            0.0359549,
-            5.82851
-        ],
-        "nf_ripple": [
-            -0.3110761646066259,
-            -0.3110761646066259,
-            -0.31110274831665313,
-            -0.31419329378173544,
-            -0.3172854168606314,
-            -0.32037911876162584,
-            -0.3233255190215882,
-            -0.31624321721895354,
-            -0.30915729645781326,
-            -0.30206775396360075,
-            -0.2949045115165272,
-            -0.26632156113294336,
-            -0.23772399031437283,
-            -0.20911178784023846,
-            -0.18048410390821285,
-            -0.14379944379052215,
-            -0.10709599992470213,
-            -0.07037375788020579,
-            -0.03372858157230583,
-            -0.015660302006048,
-            0.0024172385953583004,
-            0.020504047353947653,
-            0.03860013139908377,
-            0.05670549786742816,
-            0.07482015390297145,
-            0.0838762040768461,
-            0.09284481475528361,
-            0.1018180306253394,
-            0.11079585523492333,
-            0.1020395478432815,
-            0.09310160456603413,
-            0.08415906712621996,
-            0.07521193198077789,
-            0.0676340601339394,
-            0.06005437964543287,
-            0.052470799141237305,
-            0.044883315610536455,
-            0.037679759069084225,
-            0.03047647598902483,
-            0.02326948274513522,
-            0.01605877647020772,
-            0.021248462316134083,
-            0.02657315875107553,
-            0.03190060058247842,
-            0.03723078993416436,
-            0.04256372893215024,
-            0.047899419704645264,
-            0.03915515813685565,
-            0.030289222542492025,
-            0.021418708618354456,
-            0.012573926129294415,
-            0.006240488799898697,
-            -9.622162373026585e-05,
-            -0.006436207679519103,
-            -0.012779471908040341,
-            -0.02038153550619876,
-            -0.027999803010447587,
-            -0.035622012697103154,
-            -0.043236398934156144,
-            -0.04493583574805963,
-            -0.04663615264317309,
-            -0.048337350303318156,
-            -0.050039429413028365,
-            -0.051742390657545205,
-            -0.05342028484370278,
-            -0.05254242298580185,
-            -0.05166410580536087,
-            -0.05078533294804249,
-            -0.04990610405914272,
-            -0.05409792133358102,
-            -0.05832916277634124,
-            -0.06256260169582961,
-            -0.06660356886269536,
-            -0.04779792991567815,
-            -0.028982516728038848,
-            -0.010157321677553965,
-            0.00861320615127981,
-            0.01913736978785662,
-            0.029667009055877668,
-            0.04020212822983975,
-            0.050742731588695494,
-            0.061288823415841555,
-            0.07184040799914815,
-            0.1043252636301016,
-            0.13687829834471027,
-            0.1694483010211072,
-            0.202035284929368,
-            0.23624619427167134,
-            0.27048596623174515,
-            0.30474360397422756,
-            0.3390191214858807,
-            0.36358851509924695,
-            0.38814205928193013,
-            0.41270842850729195,
-            0.4372876328262819,
-            0.4372876328262819
-        ],
-        "dgt": [
-            2.714526681131686,
-            2.705443819238505,
-            2.6947834587664494,
-            2.6841217449620203,
-            2.6681935771243177,
-            2.6521732021128046,
-            2.630396440815385,
-            2.602860350286428,
-            2.5696460593920065,
-            2.5364027376452056,
-            2.499446286796604,
-            2.4587748041127506,
-            2.414398437185221,
-            2.3699990328716107,
-            2.322373696229342,
-            2.271520771371253,
-            2.2174389328192197,
-            2.16337565384239,
-            2.1183028432496016,
-            2.082225099873648,
-            2.055100772005235,
-            2.0279625371819305,
-            2.0008103857988204,
-            1.9736443063300082,
-            1.9482128147680253,
-            1.9245345552113182,
-            1.9026104247588487,
-            1.8806927939516411,
-            1.862235672444246,
-            1.847275503201129,
-            1.835814081380705,
-            1.824381436842932,
-            1.8139629377087627,
-            1.8045606557581335,
-            1.7961751115773796,
-            1.7877868031023945,
-            1.7793941781790852,
-            1.7709972329654864,
-            1.7625959636196327,
-            1.7541903672600494,
-            1.7459181197626403,
-            1.737780757913635,
-            1.7297783508684146,
-            1.7217732861435076,
-            1.7137640932265894,
-            1.7057507692361864,
-            1.6918150918099673,
-            1.6719047669939942,
-            1.6460167077689267,
-            1.6201194134191075,
-            1.5986915141218316,
-            1.5817353179379183,
-            1.569199764184379,
-            1.5566577309558969,
-            1.545374152761467,
-            1.5353620432989845,
-            1.5266220576235803,
-            1.5178910621476225,
-            1.5097346239790443,
-            1.502153039909686,
-            1.495145456062699,
-            1.488134243479226,
-            1.48111939735681,
-            1.474100442252211,
-            1.4670307626366115,
-            1.4599103316162523,
-            1.45273959485914,
-            1.445565137158368,
-            1.4340878115214444,
-            1.418273806730323,
-            1.3981208704326855,
-            1.3779439775587023,
-            1.3598972673004606,
-            1.3439818461440451,
-            1.3301807335621048,
-            1.316383926863083,
-            1.3040618749785347,
-            1.2932153453410835,
-            1.2838336236692311,
-            1.2744470198196236,
-            1.2650555289898042,
-            1.2556591482982988,
-            1.2428104897182262,
-            1.2264996957264114,
-            1.2067249615595257,
-            1.1869318618366975,
-            1.1672278304018044,
-            1.1476135933863398,
-            1.1280891949729075,
-            1.108555289615659,
-            1.0895983485572227,
-            1.0712204022764056,
-            1.0534217504465226,
-            1.0356155337864215,
-            1.017807767853702,
-            1.0
-        ],
-        "nf_model": {
-            "enabled": true,
-            "nf1": 5.727887800964238,
-            "nf2": 7.727887800964238,
-            "delta_p": 5.238350271545567
-        },
-        "gain_ripple": [
-            0.1359703369791596,
-            0.11822862697916037,
-            0.09542181697916163,
-            0.06245819697916133,
-            0.02602813697916062,
-            -0.0036199830208403228,
-            -0.018326963020840026,
-            -0.0246928330208398,
-            -0.016792253020838643,
-            -0.0028138630208403015,
-            0.017572956979162058,
-            0.038328296979159404,
-            0.054956336979159914,
-            0.0670723869791594,
-            0.07091459697916136,
-            0.07094413697916124,
-            0.07114372697916238,
-            0.07533675697916209,
-            0.08731066697916035,
-            0.10313984697916112,
-            0.12276252697916235,
-            0.14239527697916188,
-            0.15945681697916214,
-            0.1739275269791598,
-            0.1767381569791624,
-            0.17037189697916233,
-            0.15216302697916007,
-            0.13114358697916018,
-            0.10802383697916085,
-            0.08548825697916129,
-            0.06916723697916183,
-            0.05848224697916038,
-            0.05447361697916264,
-            0.05154489697916276,
-            0.04946107697915991,
-            0.04717897697916129,
-            0.04551704697916037,
-            0.04467697697916151,
-            0.04072968697916224,
-            0.03285456697916089,
-            0.023488786979161347,
-            0.01659282697915998,
-            0.013321846979160057,
-            0.011234826979162449,
-            0.01030063697916006,
-            0.00936596697916059,
-            0.00874012697916271,
-            0.00842583697916055,
-            0.006965146979162284,
-            0.0040435869791615175,
-            0.0007104669791608842,
-            -0.0015763130208377163,
-            -0.006936193020838033,
-            -0.016475303020840215,
-            -0.028748483020837767,
-            -0.039618433020837784,
-            -0.051112303020840244,
-            -0.06468462302083822,
-            -0.07868024302083754,
-            -0.09101254302083817,
-            -0.10103437302083762,
-            -0.11041488302083735,
-            -0.11916081302083725,
-            -0.12789859302083784,
-            -0.1353792530208402,
-            -0.14160178302083892,
-            -0.1455411330208385,
-            -0.1484450830208388,
-            -0.14823350302084037,
-            -0.14591937302083835,
-            -0.1409032730208395,
-            -0.13525493302083902,
-            -0.1279646530208396,
-            -0.11963431302083904,
-            -0.11089282302084058,
-            -0.1027863830208382,
-            -0.09717347302083823,
-            -0.09343261302083761,
-            -0.0913487130208388,
-            -0.08906007302083907,
-            -0.0865687230208394,
-            -0.08407607302083875,
-            -0.07844600302084004,
-            -0.06968090302083851,
-            -0.05947139302083926,
-            -0.05095282302083959,
-            -0.042428283020839785,
-            -0.03218106302083967,
-            -0.01819858302084043,
-            -0.0021726530208390216,
-            0.01393231697916164,
-            0.028098946979159933,
-            0.040326236979161934,
-            0.05257029697916238,
-            0.06479749697916048,
-            0.07704745697916238
-        ]
-    }
-}

examples/eqpt_config.json

@@ -1,197 +0,0 @@
-{     "Edfa":[{
-            "type_variety": "high_detail_model_example",
-            "gain_flatmax": 25,
-            "gain_min": 15,
-            "p_max": 21,
-            "advanced_config_from_json": "std_medium_gain_advanced_config.json",
-            "out_voa_auto": false,
-            "allowed_for_design": false
-            },
-            {
-            "type_variety": "operator_model_example",
-            "type_def": "variable_gain",
-            "gain_flatmax": 26,
-            "gain_min": 15,
-            "p_max": 23,
-            "nf_min": 6,
-            "nf_max": 10,
-            "out_voa_auto": false,
-            "allowed_for_design": false           
-            },
-            {
-            "type_variety": "low_noise",
-            "type_def": "openroadm",
-            "gain_flatmax": 27,
-            "gain_min": 12,
-            "p_max": 22,
-            "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62],
-            "allowed_for_design": false
-            },          
-            {
-            "type_variety": "standard",
-            "type_def": "openroadm",
-            "gain_flatmax": 27,
-            "gain_min": 12,
-            "p_max": 22,
-            "nf_coef": [-5.952e-4,-6.250e-2,-1.071,28.99],
-            "allowed_for_design": false
-            },
-            {
-            "type_variety": "std_medium_gain",
-            "type_def": "variable_gain",
-            "gain_flatmax": 26,
-            "gain_min": 15,
-            "p_max": 23,
-            "nf_min": 6,
-            "nf_max": 10,
-            "out_voa_auto": false,
-            "allowed_for_design": true
-            },
-            {
-            "type_variety": "std_low_gain",
-            "type_def": "variable_gain",
-            "gain_flatmax": 16,
-            "gain_min": 8,
-            "p_max": 23,
-            "nf_min": 6.5,
-            "nf_max": 11,
-            "out_voa_auto": false,
-            "allowed_for_design": true
-            },
-            {
-            "type_variety": "std_fixed_gain",
-            "type_def": "fixed_gain",
-            "gain_flatmax": 21,
-            "gain_min": 20,
-            "p_max": 21,
-            "nf0": 5.5,
-            "allowed_for_design": false
-            }       
-      ],
-      "Fiber":[{
-            "type_variety": "SSMF",
-            "dispersion": 1.67e-05,
-            "gamma": 0.00127
-            },
-            {
-            "type_variety": "NZDF",
-            "dispersion": 0.5e-05,
-            "gamma": 0.00146
-            },
-            {
-            "type_variety": "LOF",
-            "dispersion": 2.2e-05,
-            "gamma": 0.000843
-            }
-      ],
-      "Spans":[{
-            "power_mode":true,
-            "delta_power_range_db": [0,0,0.5],
-            "max_length": 150,
-            "length_units": "km",
-            "max_loss": 28,
-            "padding": 10,
-            "EOL": 0,
-            "con_in": 0,
-            "con_out": 0
-            }
-      ],
-      "Roadms":[{
-            "gain_mode_default_loss": 20,
-            "power_mode_pout_target": -20,
-            "add_drop_osnr": 38
-            }],
-      "SI":[{
-            "f_min": 191.3e12,
-            "baud_rate": 32e9,
-            "f_max":195.1e12,
-            "spacing": 50e9,
-            "power_dbm": 0,
-            "power_range_db": [0,0,0.5],
-            "roll_off": 0.15,
-            "tx_osnr": 40,
-            "sys_margins": 0
-            }],
-      "Transceiver":[
-            {
-            "type_variety": "vendorA_trx-type1",
-            "frequency":{
-                        "min": 191.35e12,
-                        "max": 196.1e12
-                        },
-            "mode":[
-                       {
-
-                       "format": "mode 1",
-                       "baud_rate": 32e9,
-                       "OSNR": 11,
-                       "bit_rate": 100e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 37.5e9,
-                       "cost":1
-                       },
-                       {
-                       "format": "mode 2",
-                       "baud_rate": 66e9,
-                       "OSNR": 15,
-                       "bit_rate": 200e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 75e9,
-                       "cost":1
-                       }
-                   ]
-            },
-            {
-            "type_variety": "Voyager",
-            "frequency":{
-                        "min": 191.35e12,
-                        "max": 196.1e12
-                        },
-            "mode":[
-                       {
-                       "format": "mode 1",
-                       "baud_rate": 32e9,
-                       "OSNR": 12,
-                       "bit_rate": 100e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 37.5e9,
-                       "cost":1
-                       },
-                       {
-                       "format": "mode 3",
-                       "baud_rate": 44e9,
-                       "OSNR": 18,
-                       "bit_rate": 300e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 62.5e9,
-                       "cost":1
-                       },
-                       {
-                       "format": "mode 2",
-                       "baud_rate": 66e9,
-                       "OSNR": 21,
-                       "bit_rate": 400e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 75e9,
-                       "cost":1
-                       },
-                       {
-                       "format": "mode 4",
-                       "baud_rate": 66e9,
-                       "OSNR": 16,
-                       "bit_rate": 200e9,
-                       "roll_off": 0.15,
-                       "tx_osnr": 40,
-                       "min_spacing": 75e9,
-                       "cost":1
-                       }
-                   ]
-            }
-      ]
-
-}

examples/path_requests_run.py

@@ -1,399 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-path_requests_run.py
-====================
-
-Reads a JSON request file in accordance with the Yang model
-for requesting path computation and returns path results in terms
-of path and feasibilty.
-
-See: draft-ietf-teas-yang-path-computation-01.txt
-"""
-
-from sys import exit
-from argparse import ArgumentParser
-from pathlib import Path
-from collections import namedtuple
-from logging import getLogger, basicConfig, CRITICAL, DEBUG, INFO
-from json import dumps, loads
-from networkx import (draw_networkx_nodes, draw_networkx_edges,
-                      draw_networkx_labels)
-from numpy import mean
-from gnpy.core.service_sheet import convert_service_sheet, Request_element, Element
-from gnpy.core.utils import load_json
-from gnpy.core.network import load_network, build_network, set_roadm_loss, save_network
-from gnpy.core.equipment import load_equipment, trx_mode_params, automatic_nch, automatic_spacing
-from gnpy.core.elements import Transceiver, Roadm, Edfa, Fused, Fiber
-from gnpy.core.utils import db2lin, lin2db
-from gnpy.core.request import (Path_request, Result_element, compute_constrained_path,
-                              propagate, jsontocsv, Disjunction, compute_path_dsjctn, requests_aggregation,
-                              propagate_and_optimize_mode)
-from copy import copy, deepcopy
-from textwrap import dedent
-from math import ceil
-import time
-
-#EQPT_LIBRARY_FILENAME = Path(__file__).parent / 'eqpt_config.json'
-
-logger = getLogger(__name__)
-
-parser = ArgumentParser(description = 'A function that computes performances for a list of services provided in a json file or an excel sheet.')
-parser.add_argument('network_filename', nargs='?', type = Path, default= Path(__file__).parent / 'meshTopologyExampleV2.xls')
-parser.add_argument('service_filename', nargs='?', type = Path, default= Path(__file__).parent / 'meshTopologyExampleV2.xls')
-parser.add_argument('eqpt_filename', nargs='?', type = Path, default=Path(__file__).parent / 'eqpt_config.json')
-parser.add_argument('-v', '--verbose', action='count', default=0, help='increases verbosity for each occurence')
-parser.add_argument('-o', '--output', type = Path)
-
-
-def requests_from_json(json_data,equipment):
-    requests_list = []
-
-    for req in json_data['path-request']:
-        # init all params from request
-        params = {}
-        params['request_id'] = req['request-id']
-        params['source'] = req['src-tp-id']
-        params['destination'] = req['dst-tp-id']
-        params['trx_type'] = req['path-constraints']['te-bandwidth']['trx_type']
-        params['trx_mode'] = req['path-constraints']['te-bandwidth']['trx_mode']
-        params['format'] = params['trx_mode']
-        nd_list = req['optimizations']['explicit-route-include-objects']
-        params['nodes_list'] = [n['unnumbered-hop']['node-id'] for n in nd_list]
-        params['loose_list'] = [n['unnumbered-hop']['hop-type'] for n in nd_list]
-        params['spacing'] = req['path-constraints']['te-bandwidth']['spacing']
-
-        # recover trx physical param (baudrate, ...) from type and mode
-        # in trx_mode_params optical power is read from equipment['SI']['default'] and
-        # nb_channel is computed based on min max frequency and spacing
-        trx_params = trx_mode_params(equipment,params['trx_type'],params['trx_mode'],True)
-        params.update(trx_params)
-        # print(trx_params['min_spacing'])
-        # optical power might be set differently in the request. if it is indicated then the 
-        # params['power'] is updated
-        if req['path-constraints']['te-bandwidth']['output-power']:
-            params['power'] = req['path-constraints']['te-bandwidth']['output-power']
-
-        # same process for nb-channel
-        f_min = params['f_min']
-        f_max_from_si = params['f_max']
-        if req['path-constraints']['te-bandwidth']['max-nb-of-channel'] is not None :
-            nch = req['path-constraints']['te-bandwidth']['max-nb-of-channel'] 
-            params['nb_channel'] = nch         
-            spacing = params['spacing']
-            params['f_max'] = f_min + nch*spacing
-        else :
-            params['nb_channel'] = automatic_nch(f_min,f_max_from_si,params['spacing'])
-
-        consistency_check(params, f_max_from_si)
-
-        try :
-            params['path_bandwidth'] = req['path-constraints']['te-bandwidth']['path_bandwidth']
-        except KeyError:
-            pass
-        requests_list.append(Path_request(**params))
-    return requests_list
-
-def consistency_check(params, f_max_from_si):
-    f_min = params['f_min']
-    f_max = params['f_max']
-    max_recommanded_nb_channels = automatic_nch(f_min,f_max,
-                params['spacing'])
-    if params['baud_rate'] is not None:
-        #implicitely means that a mode is defined with min_spacing
-        if params['min_spacing']>params['spacing'] : 
-            msg = f'Request {params["request_id"]} has spacing below transponder {params["trx_type"]}'+\
-                f' {params["trx_mode"]} min spacing value {params["min_spacing"]*1e-9}GHz.\n'+\
-                'Computation stopped'
-            print(msg)
-            logger.critical(msg)
-            exit()
-        if f_max>f_max_from_si:
-            msg = dedent(f'''
-            Requested channel number {params["nb_channel"]}, baud rate {params["baud_rate"]} GHz and requested spacing {params["spacing"]*1e-9}GHz 
-            is not consistent with frequency range {f_min*1e-12} THz, {f_max*1e-12} THz, min recommanded spacing {params["min_spacing"]*1e-9}GHz.
-            max recommanded nb of channels is {max_recommanded_nb_channels}
-            Computation stopped.''')
-            logger.critical(msg)
-            exit()    
-
-
-def disjunctions_from_json(json_data):
-    disjunctions_list = []
-
-    for snc in json_data['synchronization']:
-        params = {}
-        params['disjunction_id'] = snc['synchronization-id']
-        params['relaxable'] = snc['svec']['relaxable']
-        params['link_diverse'] = snc['svec']['link-diverse']
-        params['node_diverse'] = snc['svec']['node-diverse']
-        params['disjunctions_req'] = snc['svec']['request-id-number']
-        disjunctions_list.append(Disjunction(**params))
-    return disjunctions_list
-
-
-def load_requests(filename,eqpt_filename):
-    if filename.suffix.lower() == '.xls':
-        logger.info('Automatically converting requests from XLS to JSON')
-        json_data = convert_service_sheet(filename,eqpt_filename)
-    else:
-        with open(filename, encoding='utf-8') as f:
-            json_data = loads(f.read())
-    return json_data
-
-def compute_path(network, equipment, pathreqlist):
-
-    # This function is obsolete and not relevant with respect to network building: suggest either to correct
-    # or to suppress it
-    
-    path_res_list = []
-
-    for pathreq in pathreqlist:
-        #need to rebuid the network for each path because the total power
-        #can be different and the choice of amplifiers in autodesign is power dependant
-        #but the design is the same if the total power is the same
-        #TODO parametrize the total spectrum power so the same design can be shared
-        p_db = lin2db(pathreq.power*1e3)
-        p_total_db = p_db + lin2db(pathreq.nb_channel)
-        build_network(network, equipment, p_db, p_total_db)
-        pathreq.nodes_list.append(pathreq.destination)
-        #we assume that the destination is a strict constraint
-        pathreq.loose_list.append('strict')
-        print(f'Computing path from {pathreq.source} to {pathreq.destination}')
-        print(f'with path constraint: {[pathreq.source]+pathreq.nodes_list}') #adding first node to be clearer on the output
-        total_path = compute_constrained_path(network, pathreq)
-        print(f'Computed path (roadms):{[e.uid for e in total_path  if isinstance(e, Roadm)]}\n')
-
-        if total_path :
-            total_path = propagate(total_path,pathreq,equipment, show=False)
-        else:
-            total_path = []
-        # we record the last tranceiver object in order to have th whole
-        # information about spectrum. Important Note: since transceivers
-        # attached to roadms are actually logical elements to simulate
-        # performance, several demands having the same destination may use
-        # the same transponder for the performance simaulation. This is why
-        # we use deepcopy: to ensure each propagation is recorded and not
-        # overwritten
-
-        path_res_list.append(deepcopy(total_path))
-    return path_res_list
-
-def compute_path_with_disjunction(network, equipment, pathreqlist, pathlist):
-    
-    # use a list but a dictionnary might be helpful to find path bathsed on request_id
-    # TODO change all these req, dsjct, res lists into dict !
-    path_res_list = []
-
-    for i,pathreq in enumerate(pathreqlist):
-
-        # use the power specified in requests but might be different from the one specified for design
-        # the power is an optional parameter for requests definition
-        # if optional, use the one defines in eqt_config.json
-        p_db = lin2db(pathreq.power*1e3)
-        p_total_db = p_db + lin2db(pathreq.nb_channel)
-        print(f'request {pathreq.request_id}')
-        print(f'Computing path from {pathreq.source} to {pathreq.destination}')
-        print(f'with path constraint: {[pathreq.source]+pathreq.nodes_list}') #adding first node to be clearer on the output
-
-        total_path = pathlist[i]
-        print(f'Computed path (roadms):{[e.uid for e in total_path  if isinstance(e, Roadm)]}\n')
-        # for debug
-        # print(f'{pathreq.baud_rate}   {pathreq.power}   {pathreq.spacing}   {pathreq.nb_channel}')
-        if total_path :
-            if pathreq.baud_rate is not None:
-                total_path = propagate(total_path,pathreq,equipment, show=False)
-                temp_snr01nm = round(mean(total_path[-1].snr+lin2db(pathreq.baud_rate/(12.5e9))),2)
-                if temp_snr01nm < pathreq.OSNR :
-                    msg = f'\tWarning! Request {pathreq.request_id} computed path from {pathreq.source} to {pathreq.destination} does not pass with {pathreq.tsp_mode}\n' +\
-                    f'\tcomputedSNR in 0.1nm = {temp_snr01nm} - required osnr {pathreq.OSNR}\n'
-                    print(msg)
-                    logger.warning(msg)
-                    total_path = []
-            else:
-                total_path,mode = propagate_and_optimize_mode(total_path,pathreq,equipment)
-                # if no baudrate satisfies spacing, no mode is returned and an empty path is returned
-                # a warning is shown in the propagate_and_optimize_mode
-                if mode is not None :
-                    # propagate_and_optimize_mode function returns the mode with the highest bitrate
-                    # that passes. if no mode passes, then it returns an empty path
-                    pathreq.baud_rate = mode['baud_rate']
-                    pathreq.tsp_mode = mode['format']
-                    pathreq.format = mode['format']
-                    pathreq.OSNR = mode['OSNR']
-                    pathreq.tx_osnr = mode['tx_osnr']
-                    pathreq.bit_rate = mode['bit_rate']
-                else :
-                    total_path = []
-        # we record the last tranceiver object in order to have th whole 
-        # information about spectrum. Important Note: since transceivers 
-        # attached to roadms are actually logical elements to simulate
-        # performance, several demands having the same destination may use 
-        # the same transponder for the performance simaulation. This is why 
-        # we use deepcopy: to ensure each propagation is recorded and not 
-        # overwritten 
-        
-        path_res_list.append(deepcopy(total_path))
-    return path_res_list
-
-def correct_route_list(network, pathreqlist):
-    # prepares the format of route list of nodes to be consistant
-    # remove wrong names, remove endpoints
-    # also correct source and destination
-    anytype = [n.uid for n in network.nodes() if not isinstance(n, Transceiver) and not isinstance(n, Fiber)]
-    # TODO there is a problem of identification of fibers in case of parallel fibers bitween two adjacent roadms
-    # so fiber constraint is not supported
-    transponders = [n.uid for n in network.nodes() if isinstance(n, Transceiver)]
-    for pathreq in pathreqlist:
-        for i,n_id in enumerate(pathreq.nodes_list):
-            # replace possibly wrong name with a formated roadm name
-            # print(n_id)
-            if n_id not in anytype :
-                nodes_suggestion = [uid for uid in anytype \
-                    if n_id.lower() in uid.lower()]
-                if pathreq.loose_list[i] == 'loose':
-                    if len(nodes_suggestion)>0 :
-                        new_n = nodes_suggestion[0]
-                        print(f'invalid route node specified:\
-                        \n\'{n_id}\', replaced with \'{new_n}\'')
-                        pathreq.nodes_list[i] = new_n
-                    else:
-                        print(f'\x1b[1;33;40m'+f'invalid route node specified \'{n_id}\', could not use it as constraint, skipped!'+'\x1b[0m')
-                        pathreq.nodes_list.remove(n_id)
-                        pathreq.loose_list.pop(i)
-                else:
-                    msg = f'\x1b[1;33;40m'+f'could not find node : {n_id} in network topology. Strict constraint can not be applied.'+'\x1b[0m'
-                    logger.critical(msg)
-                    raise ValueError(msg)
-        if pathreq.source not in transponders:
-            msg = f'\x1b[1;31;40m'+f'Request: {pathreq.request_id}: could not find transponder source : {pathreq.source}.'+'\x1b[0m'
-            logger.critical(msg)
-            print(f'{msg}\nComputation stopped.')
-            exit()
-            
-        if pathreq.destination not in transponders:
-            msg = f'\x1b[1;31;40m'+f'Request: {pathreq.request_id}: could not find transponder destination : {pathreq.destination}.'+'\x1b[0m'
-            logger.critical(msg)
-            print(f'{msg}\nComputation stopped.')
-            exit()
-
-        # TODO remove endpoints from this list in case they were added by the user in the xls or json files
-    return pathreqlist
-
-def correct_disjn(disjn):
-    local_disjn = disjn.copy()
-    for el in local_disjn:
-        for d in local_disjn:
-            if set(el.disjunctions_req) == set(d.disjunctions_req) and\
-             el.disjunction_id != d.disjunction_id:
-                local_disjn.remove(d)
-    return local_disjn
-
-
-def path_result_json(pathresult):
-    data = {
-        'path': [n.json for n in pathresult]
-    }
-    return data
-
-
-if __name__ == '__main__':
-    start = time.time()
-    args = parser.parse_args()
-    basicConfig(level={2: DEBUG, 1: INFO, 0: CRITICAL}.get(args.verbose, DEBUG))
-    logger.info(f'Computing path requests {args.service_filename} into JSON format')
-    print('\x1b[1;34;40m'+f'Computing path requests {args.service_filename} into JSON format'+ '\x1b[0m')
-    # for debug
-    # print( args.eqpt_filename)
-    data = load_requests(args.service_filename,args.eqpt_filename)
-    equipment = load_equipment(args.eqpt_filename)
-    network = load_network(args.network_filename,equipment)
-
-    # Build the network once using the default power defined in SI in eqpt config
-    # TODO power density : db2linp(ower_dbm": 0)/power_dbm": 0 * nb channels as defined by
-    # spacing, f_min and f_max 
-    p_db = equipment['SI']['default'].power_dbm
-    
-    p_total_db = p_db + lin2db(automatic_nch(equipment['SI']['default'].f_min,\
-        equipment['SI']['default'].f_max, equipment['SI']['default'].spacing))
-    build_network(network, equipment, p_db, p_total_db)
-    save_network(args.network_filename, network)
-
-    rqs = requests_from_json(data, equipment)
-
-    # check that request ids are unique. Non unique ids, may 
-    # mess the computation : better to stop the computation
-    all_ids = [r.request_id for r in rqs]
-    if len(all_ids) != len(set(all_ids)):
-        for a in list(set(all_ids)):
-            all_ids.remove(a)
-        msg = f'Requests id {all_ids} are not unique'
-        logger.critical(msg)
-        exit()
-    rqs = correct_route_list(network, rqs)
-
-    # pths = compute_path(network, equipment, rqs)
-    dsjn = disjunctions_from_json(data)
-
-    print('\x1b[1;34;40m'+f'List of disjunctions'+ '\x1b[0m')
-    print(dsjn)
-    # need to warn or correct in case of wrong disjunction form
-    # disjunction must not be repeated with same or different ids
-    dsjn = correct_disjn(dsjn)
-        
-    # Aggregate demands with same exact constraints
-    print('\x1b[1;34;40m'+f'Aggregating similar requests'+ '\x1b[0m')
-
-    rqs,dsjn = requests_aggregation(rqs,dsjn)
-    # TODO export novel set of aggregated demands in a json file
-
-    print('\x1b[1;34;40m'+'The following services have been requested:'+ '\x1b[0m')
-    print(rqs)
-    
-    print('\x1b[1;34;40m'+f'Computing all paths with constraints'+ '\x1b[0m')
-    pths = compute_path_dsjctn(network, equipment, rqs, dsjn)
-
-    print('\x1b[1;34;40m'+f'Propagating on selected path'+ '\x1b[0m')
-    propagatedpths = compute_path_with_disjunction(network, equipment, rqs, pths)
-
-    end = time.time()
-    print(f'computation time {end-start}')
-    print('\x1b[1;34;40m'+f'Result summary'+ '\x1b[0m')
-    
-    header = ['req id', '  demand','  snr@bandwidth','  snr@0.1nm','  Receiver minOSNR', '  mode', '  Gbit/s' , '  nb of tsp pairs']
-    data = []
-    data.append(header)
-    for i, p in enumerate(propagatedpths):
-        if p:
-            line = [f'{rqs[i].request_id}', f' {rqs[i].source} to {rqs[i].destination} : ', f'{round(mean(p[-1].snr),2)}',\
-                f'{round(mean(p[-1].snr+lin2db(rqs[i].baud_rate/(12.5e9))),2)}',\
-                f'{rqs[i].OSNR}', f'{rqs[i].tsp_mode}' , f'{round(rqs[i].path_bandwidth * 1e-9,2)}' , f'{ceil(rqs[i].path_bandwidth / rqs[i].bit_rate) }']
-        else:
-            line = [f'{rqs[i].request_id}',f' {rqs[i].source} to {rqs[i].destination} : not feasible ']
-        data.append(line)
-
-    col_width = max(len(word) for row in data for word in row[2:])   # padding
-    firstcol_width = max(len(row[0]) for row in data )   # padding
-    secondcol_width = max(len(row[1]) for row in data )   # padding
-    for row in data:
-        firstcol = ''.join(row[0].ljust(firstcol_width)) 
-        secondcol = ''.join(row[1].ljust(secondcol_width))
-        remainingcols = ''.join(word.center(col_width,' ') for word in row[2:])
-        print(f'{firstcol} {secondcol} {remainingcols}')
-
-
-    if args.output :
-        result = []
-        # assumes that list of rqs and list of propgatedpths have same order
-        for i,p in enumerate(propagatedpths):
-            result.append(Result_element(rqs[i],p))
-        temp = path_result_json(result)
-        fnamecsv = f'{str(args.output)[0:len(str(args.output))-len(str(args.output.suffix))]}.csv'
-        fnamejson = f'{str(args.output)[0:len(str(args.output))-len(str(args.output.suffix))]}.json'
-        with open(fnamejson, 'w', encoding='utf-8') as f:
-            f.write(dumps(path_result_json(result), indent=2, ensure_ascii=False))
-            with open(fnamecsv,"w", encoding='utf-8') as fcsv :
-                jsontocsv(temp,equipment,fcsv)
-                print('\x1b[1;34;40m'+f'saving in {args.output} and {fnamecsv}'+ '\x1b[0m')
-

examples/std_medium_gain_advanced_config.json

@@ -1,301 +0,0 @@
-{     "nf_fit_coeff": [
-      0.000168241,
-      0.0469961,
-      0.0359549,
-      5.82851
-      ],
-      "nf_ripple": [
-      -0.3110761646066259,
-      -0.3110761646066259,
-      -0.31110274831665313,
-      -0.31419329378173544,
-      -0.3172854168606314,
-      -0.32037911876162584,
-      -0.3233255190215882,
-      -0.31624321721895354,
-      -0.30915729645781326,
-      -0.30206775396360075,
-      -0.2949045115165272,
-      -0.26632156113294336,
-      -0.23772399031437283,
-      -0.20911178784023846,
-      -0.18048410390821285,
-      -0.14379944379052215,
-      -0.10709599992470213,
-      -0.07037375788020579,
-      -0.03372858157230583,
-      -0.015660302006048,
-      0.0024172385953583004,
-      0.020504047353947653,
-      0.03860013139908377,
-      0.05670549786742816,
-      0.07482015390297145,
-      0.0838762040768461,
-      0.09284481475528361,
-      0.1018180306253394,
-      0.11079585523492333,
-      0.1020395478432815,
-      0.09310160456603413,
-      0.08415906712621996,
-      0.07521193198077789,
-      0.0676340601339394,
-      0.06005437964543287,
-      0.052470799141237305,
-      0.044883315610536455,
-      0.037679759069084225,
-      0.03047647598902483,
-      0.02326948274513522,
-      0.01605877647020772,
-      0.021248462316134083,
-      0.02657315875107553,
-      0.03190060058247842,
-      0.03723078993416436,
-      0.04256372893215024,
-      0.047899419704645264,
-      0.03915515813685565,
-      0.030289222542492025,
-      0.021418708618354456,
-      0.012573926129294415,
-      0.006240488799898697,
-      -9.622162373026585e-05,
-      -0.006436207679519103,
-      -0.012779471908040341,
-      -0.02038153550619876,
-      -0.027999803010447587,
-      -0.035622012697103154,
-      -0.043236398934156144,
-      -0.04493583574805963,
-      -0.04663615264317309,
-      -0.048337350303318156,
-      -0.050039429413028365,
-      -0.051742390657545205,
-      -0.05342028484370278,
-      -0.05254242298580185,
-      -0.05166410580536087,
-      -0.05078533294804249,
-      -0.04990610405914272,
-      -0.05409792133358102,
-      -0.05832916277634124,
-      -0.06256260169582961,
-      -0.06660356886269536,
-      -0.04779792991567815,
-      -0.028982516728038848,
-      -0.010157321677553965,
-      0.00861320615127981,
-      0.01913736978785662,
-      0.029667009055877668,
-      0.04020212822983975,
-      0.050742731588695494,
-      0.061288823415841555,
-      0.07184040799914815,
-      0.1043252636301016,
-      0.13687829834471027,
-      0.1694483010211072,
-      0.202035284929368,
-      0.23624619427167134,
-      0.27048596623174515,
-      0.30474360397422756,
-      0.3390191214858807,
-      0.36358851509924695,
-      0.38814205928193013,
-      0.41270842850729195,
-      0.4372876328262819,
-      0.4372876328262819
-      ],
-      "dgt": [
-      2.714526681131686,
-      2.705443819238505,
-      2.6947834587664494,
-      2.6841217449620203,
-      2.6681935771243177,
-      2.6521732021128046,
-      2.630396440815385,
-      2.602860350286428,
-      2.5696460593920065,
-      2.5364027376452056,
-      2.499446286796604,
-      2.4587748041127506,
-      2.414398437185221,
-      2.3699990328716107,
-      2.322373696229342,
-      2.271520771371253,
-      2.2174389328192197,
-      2.16337565384239,
-      2.1183028432496016,
-      2.082225099873648,
-      2.055100772005235,
-      2.0279625371819305,
-      2.0008103857988204,
-      1.9736443063300082,
-      1.9482128147680253,
-      1.9245345552113182,
-      1.9026104247588487,
-      1.8806927939516411,
-      1.862235672444246,
-      1.847275503201129,
-      1.835814081380705,
-      1.824381436842932,
-      1.8139629377087627,
-      1.8045606557581335,
-      1.7961751115773796,
-      1.7877868031023945,
-      1.7793941781790852,
-      1.7709972329654864,
-      1.7625959636196327,
-      1.7541903672600494,
-      1.7459181197626403,
-      1.737780757913635,
-      1.7297783508684146,
-      1.7217732861435076,
-      1.7137640932265894,
-      1.7057507692361864,
-      1.6918150918099673,
-      1.6719047669939942,
-      1.6460167077689267,
-      1.6201194134191075,
-      1.5986915141218316,
-      1.5817353179379183,
-      1.569199764184379,
-      1.5566577309558969,
-      1.545374152761467,
-      1.5353620432989845,
-      1.5266220576235803,
-      1.5178910621476225,
-      1.5097346239790443,
-      1.502153039909686,
-      1.495145456062699,
-      1.488134243479226,
-      1.48111939735681,
-      1.474100442252211,
-      1.4670307626366115,
-      1.4599103316162523,
-      1.45273959485914,
-      1.445565137158368,
-      1.4340878115214444,
-      1.418273806730323,
-      1.3981208704326855,
-      1.3779439775587023,
-      1.3598972673004606,
-      1.3439818461440451,
-      1.3301807335621048,
-      1.316383926863083,
-      1.3040618749785347,
-      1.2932153453410835,
-      1.2838336236692311,
-      1.2744470198196236,
-      1.2650555289898042,
-      1.2556591482982988,
-      1.2428104897182262,
-      1.2264996957264114,
-      1.2067249615595257,
-      1.1869318618366975,
-      1.1672278304018044,
-      1.1476135933863398,
-      1.1280891949729075,
-      1.108555289615659,
-      1.0895983485572227,
-      1.0712204022764056,
-      1.0534217504465226,
-      1.0356155337864215,
-      1.017807767853702,
-      1.0
-      ],
-      "gain_ripple": [
-      0.1359703369791596,
-      0.11822862697916037,
-      0.09542181697916163,
-      0.06245819697916133,
-      0.02602813697916062,
-      -0.0036199830208403228,
-      -0.018326963020840026,
-      -0.0246928330208398,
-      -0.016792253020838643,
-      -0.0028138630208403015,
-      0.017572956979162058,
-      0.038328296979159404,
-      0.054956336979159914,
-      0.0670723869791594,
-      0.07091459697916136,
-      0.07094413697916124,
-      0.07114372697916238,
-      0.07533675697916209,
-      0.08731066697916035,
-      0.10313984697916112,
-      0.12276252697916235,
-      0.14239527697916188,
-      0.15945681697916214,
-      0.1739275269791598,
-      0.1767381569791624,
-      0.17037189697916233,
-      0.15216302697916007,
-      0.13114358697916018,
-      0.10802383697916085,
-      0.08548825697916129,
-      0.06916723697916183,
-      0.05848224697916038,
-      0.05447361697916264,
-      0.05154489697916276,
-      0.04946107697915991,
-      0.04717897697916129,
-      0.04551704697916037,
-      0.04467697697916151,
-      0.04072968697916224,
-      0.03285456697916089,
-      0.023488786979161347,
-      0.01659282697915998,
-      0.013321846979160057,
-      0.011234826979162449,
-      0.01030063697916006,
-      0.00936596697916059,
-      0.00874012697916271,
-      0.00842583697916055,
-      0.006965146979162284,
-      0.0040435869791615175,
-      0.0007104669791608842,
-      -0.0015763130208377163,
-      -0.006936193020838033,
-      -0.016475303020840215,
-      -0.028748483020837767,
-      -0.039618433020837784,
-      -0.051112303020840244,
-      -0.06468462302083822,
-      -0.07868024302083754,
-      -0.09101254302083817,
-      -0.10103437302083762,
-      -0.11041488302083735,
-      -0.11916081302083725,
-      -0.12789859302083784,
-      -0.1353792530208402,
-      -0.14160178302083892,
-      -0.1455411330208385,
-      -0.1484450830208388,
-      -0.14823350302084037,
-      -0.14591937302083835,
-      -0.1409032730208395,
-      -0.13525493302083902,
-      -0.1279646530208396,
-      -0.11963431302083904,
-      -0.11089282302084058,
-      -0.1027863830208382,
-      -0.09717347302083823,
-      -0.09343261302083761,
-      -0.0913487130208388,
-      -0.08906007302083907,
-      -0.0865687230208394,
-      -0.08407607302083875,
-      -0.07844600302084004,
-      -0.06968090302083851,
-      -0.05947139302083926,
-      -0.05095282302083959,
-      -0.042428283020839785,
-      -0.03218106302083967,
-      -0.01819858302084043,
-      -0.0021726530208390216,
-      0.01393231697916164,
-      0.028098946979159933,
-      0.040326236979161934,
-      0.05257029697916238,
-      0.06479749697916048,
-      0.07704745697916238
-      ]
-}

examples/transmission_main_example.py

@@ -1,264 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-'''
-transmission_main_example.py
-============================
-
-Main example for transmission simulation.
-
-Reads from network JSON (by default, `edfa_example_network.json`)
-'''
-
-from gnpy.core.equipment import load_equipment, trx_mode_params
-from gnpy.core.utils import db2lin, lin2db, write_csv
-from argparse import ArgumentParser
-from sys import exit
-from pathlib import Path
-from json import loads
-from collections import Counter
-from logging import getLogger, basicConfig, INFO, ERROR, DEBUG
-from numpy import linspace, mean
-from matplotlib.pyplot import show, axis, figure, title, text
-from networkx import (draw_networkx_nodes, draw_networkx_edges,
-                      draw_networkx_labels, dijkstra_path)
-from gnpy.core.network import load_network, build_network, save_network
-from gnpy.core.elements import Transceiver, Fiber, Edfa, Roadm
-from gnpy.core.info import create_input_spectral_information, SpectralInformation, Channel, Power, Pref
-from gnpy.core.request import Path_request, RequestParams, compute_constrained_path, propagate2
-
-logger = getLogger(__name__)
-
-def plot_baseline(network):
-    edges = set(network.edges())
-    pos = {n: (n.lng, n.lat) for n in network.nodes()}
-    labels = {n: n.location.city for n in network.nodes() if isinstance(n, Transceiver)}
-    city_labels = set(labels.values())
-    for n in network.nodes():
-        if n.location.city and n.location.city not in city_labels:
-            labels[n] = n.location.city
-            city_labels.add(n.location.city)
-    label_pos = pos
-
-    fig = figure()
-    kwargs = {'figure': fig, 'pos': pos}
-    plot = draw_networkx_nodes(network, nodelist=network.nodes(), node_color='#ababab', **kwargs)
-    draw_networkx_edges(network, edgelist=edges, edge_color='#ababab', **kwargs)
-    draw_networkx_labels(network, labels=labels, font_size=14, **{**kwargs, 'pos': label_pos})
-    axis('off')
-    show()
-
-def plot_results(network, path, source, destination, infos):
-    path_edges = set(zip(path[:-1], path[1:]))
-    edges = set(network.edges()) - path_edges
-    pos = {n: (n.lng, n.lat) for n in network.nodes()}
-    nodes = {}
-    for k, (x, y) in pos.items():
-        nodes.setdefault((round(x, 1), round(y, 1)), []).append(k)
-    labels = {n: n.location.city for n in network.nodes() if isinstance(n, Transceiver)}
-    city_labels = set(labels.values())
-    for n in network.nodes():
-        if n.location.city and n.location.city not in city_labels:
-            labels[n] = n.location.city
-            city_labels.add(n.location.city)
-    label_pos = pos
-
-    fig = figure()
-    kwargs = {'figure': fig, 'pos': pos}
-    all_nodes = [n for n in network.nodes() if n not in path]
-    plot = draw_networkx_nodes(network, nodelist=all_nodes, node_color='#ababab', node_size=50, **kwargs)
-    draw_networkx_nodes(network, nodelist=path, node_color='#ff0000', node_size=55, **kwargs)
-    draw_networkx_edges(network, edgelist=edges, edge_color='#ababab', **kwargs)
-    draw_networkx_edges(network, edgelist=path_edges, edge_color='#ff0000', **kwargs)
-    draw_networkx_labels(network, labels=labels, font_size=14, **{**kwargs, 'pos': label_pos})
-    title(f'Propagating from {source.loc.city} to {destination.loc.city}')
-    axis('off')
-
-    heading = 'Spectral Information\n\n'
-    textbox = text(0.85, 0.20, heading, fontsize=14, fontname='Ubuntu Mono',
-                   verticalalignment='top', transform=fig.axes[0].transAxes,
-                   bbox={'boxstyle': 'round', 'facecolor': 'wheat', 'alpha': 0.5})
-
-    msgs = {(x, y): heading + '\n\n'.join(str(n) for n in ns if n in path)
-            for (x, y), ns in nodes.items()}
-
-    def hover(event):
-        if event.xdata is None or event.ydata is None:
-            return
-        if fig.contains(event):
-            x, y = round(event.xdata, 1), round(event.ydata, 1)
-            if (x, y) in msgs:
-                textbox.set_text(msgs[x, y])
-            else:
-                textbox.set_text(heading)
-            fig.canvas.draw_idle()
-
-    fig.canvas.mpl_connect('motion_notify_event', hover)
-    show()
-
-
-def main(network, equipment, source, destination, req = None):
-    result_dicts = {}
-    network_data = [{
-                    'network_name'  : str(args.filename),
-                    'source'        : source.uid,
-                    'destination'   : destination.uid
-                    }]
-    result_dicts.update({'network': network_data})
-    design_data = [{
-                    'power_mode'        : equipment['Spans']['default'].power_mode,
-                    'span_power_range'  : equipment['Spans']['default'].delta_power_range_db,
-                    'design_pch'        : equipment['SI']['default'].power_dbm,
-                    'baud_rate'         : equipment['SI']['default'].baud_rate
-                    }]
-    result_dicts.update({'design': design_data})
-    simulation_data = []
-    result_dicts.update({'simulation results': simulation_data})
-
-    power_mode = equipment['Spans']['default'].power_mode
-    print('\n'.join([f'Power mode is set to {power_mode}',
-                     f'=> it can be modified in eqpt_config.json - Spans']))
-
-    pref_ch_db = lin2db(req.power*1e3) #reference channel power / span (SL=20dB)
-    pref_total_db = pref_ch_db + lin2db(req.nb_channel) #reference total power / span (SL=20dB)
-    build_network(network, equipment, pref_ch_db, pref_total_db)
-    path = compute_constrained_path(network, req)
-
-    spans = [s.length for s in path if isinstance(s, Fiber)]
-    print(f'\nThere are {len(spans)} fiber spans over {sum(spans):.0f}m between {source.uid} and {destination.uid}')
-    print(f'\nNow propagating between {source.uid} and {destination.uid}:')
-
-    try:
-        p_start, p_stop, p_step = equipment['SI']['default'].power_range_db
-        p_num = abs(int(round((p_stop - p_start)/p_step))) + 1 if p_step != 0 else 1
-        power_range = list(linspace(p_start, p_stop, p_num))
-    except TypeError:
-        print('invalid power range definition in eqpt_config, should be power_range_db: [lower, upper, step]')
-        power_range = [0]
-
-    for dp_db in power_range:
-        req.power = db2lin(pref_ch_db + dp_db)*1e-3
-        print(f'\nPropagating with input power = {lin2db(req.power*1e3):.2f}dBm :')
-        infos = propagate2(path, req, equipment, show=len(power_range)==1)
-        print(f'\nTransmission result for input power = {lin2db(req.power*1e3):.2f}dBm :')
-        print(destination)
-
-        #print(f'\n !!!!!!!!!!!!!!!!!     TEST POINT         !!!!!!!!!!!!!!!!!!!!!')
-        #print(f'carriers ase output of {path[1]} =\n {list(path[1].carriers("out", "nli"))}')
-        # => use "in" or "out" parameter
-        # => use "nli" or "ase" or "signal" or "total" parameter
-
-        simulation_data.append({
-                    'Pch_dBm'               : pref_ch_db + dp_db,
-                    'OSNR_ASE_0.1nm'        : round(mean(destination.osnr_ase_01nm),2),
-                    'OSNR_ASE_signal_bw'    : round(mean(destination.osnr_ase),2),
-                    'SNR_nli_signal_bw'     : round(mean(destination.osnr_nli),2),
-                    'SNR_total_signal_bw'   : round(mean(destination.snr),2)
-                            })
-    write_csv(result_dicts, 'simulation_result.csv')
-    return path, infos
-
-
-parser = ArgumentParser()
-parser.add_argument('-e', '--equipment', type=Path,
-                    default=Path(__file__).parent / 'eqpt_config.json')
-parser.add_argument('-pl', '--plot', action='store_true')
-parser.add_argument('-v', '--verbose', action='count', default=0, help='increases verbosity for each occurence')
-parser.add_argument('-l', '--list-nodes', action='store_true', help='list all transceiver nodes')
-parser.add_argument('-po', '--power', default=0, help='channel ref power in dBm')
-parser.add_argument('-names', '--names-matching', action='store_true', help='display network names that are closed matches')
-parser.add_argument('filename', nargs='?', type=Path,
-                    default=Path(__file__).parent / 'edfa_example_network.json')
-parser.add_argument('source', nargs='?', help='source node')
-parser.add_argument('destination',   nargs='?', help='destination node')
-
-
-if __name__ == '__main__':
-    args = parser.parse_args()
-    basicConfig(level={0: ERROR, 1: INFO, 2: DEBUG}.get(args.verbose, DEBUG))
-
-    equipment = load_equipment(args.equipment)
-    network = load_network(args.filename, equipment, args.names_matching)
-
-    if args.plot:
-        plot_baseline(network)
-
-    transceivers = {n.uid: n for n in network.nodes() if isinstance(n, Transceiver)}
-
-    if not transceivers:
-        exit('Network has no transceivers!')
-    if len(transceivers) < 2:
-        exit('Network has only one transceiver!')
-
-    if args.list_nodes:
-        for uid in transceivers:
-            print(uid)
-        exit()
-
-    #First try to find exact match if source/destination provided
-    if args.source:
-        source = transceivers.pop(args.source, None)
-        valid_source = True if source else False
-    else:
-        source = None
-        logger.info('No source node specified: picking random transceiver')
-
-    if args.destination:
-        destination = transceivers.pop(args.destination, None)
-        valid_destination = True if destination else False
-    else:
-        destination = None
-        logger.info('No destination node specified: picking random transceiver')
-
-    #If no exact match try to find partial match
-    if args.source and not source:
-        #TODO code a more advanced regex to find nodes match
-        source = next((transceivers.pop(uid) for uid in transceivers \
-                  if args.source.lower() in uid.lower()), None)
-
-    if args.destination and not destination:
-        #TODO code a more advanced regex to find nodes match
-        destination = next((transceivers.pop(uid) for uid in transceivers \
-                  if args.destination.lower() in uid.lower()), None)
-
-    #If no partial match or no source/destination provided pick random
-    if not source:
-        source = list(transceivers.values())[0]
-        del transceivers[source.uid]
-
-    if not destination:
-        destination = list(transceivers.values())[0]
-
-    logger.info(f'source = {args.source!r}')
-    logger.info(f'destination = {args.destination!r}')
-
-    params = {}
-    params['request_id'] = 0
-    params['trx_type'] = ''
-    params['trx_mode'] = ''
-    params['source'] = source.uid
-    params['destination'] = destination.uid
-    params['nodes_list'] = [destination.uid]
-    params['loose_list'] = ['strict']
-    params['format'] = ''
-    params['path_bandwidth'] = 0
-    trx_params = trx_mode_params(equipment)
-    if args.power:
-        trx_params['power'] = db2lin(float(args.power))*1e-3
-    params.update(trx_params)
-    req = Path_request(**params)
-    path, infos = main(network, equipment, source, destination, req)
-    save_network(args.filename, network)
-
-    if not args.source:
-        print(f'\n(No source node specified: picked {source.uid})')
-    elif not valid_source:
-        print(f'\n(Invalid source node {args.source!r} replaced with {source.uid})')
-
-    if not args.destination:
-        print(f'\n(No destination node specified: picked {destination.uid})')
-    elif not valid_destination:
-        print(f'\n(Invalid destination node {args.destination!r} replaced with {destination.uid})')
-
-    if args.plot:
-        plot_results(network, path, source, destination, infos)

gnpy/__init__.py

@@ -0,0 +1,8 @@
+'''
+GNPy is an open-source, community-developed library for building route planning and optimization tools in real-world mesh optical networks. It is based on the Gaussian Noise Model.
+
+Signal propagation is implemented in :py:mod:`.core`.
+Path finding and spectrum assignment is in :py:mod:`.topology`.
+Various tools and auxiliary code, including the JSON I/O handling, is in
+:py:mod:`.tools`.
+'''

gnpy/core/__init__.py

@@ -1,30 +1,9 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-########################################################################
-#                _____ ___ ____    ____  ____  _____                   #
-#               |_   _|_ _|  _ \  |  _ \/ ___|| ____|                  #
-#                 | |  | || |_) | | |_) \___ \|  _|                    #
-#                 | |  | ||  __/  |  __/ ___) | |___                   #
-#                 |_| |___|_|     |_|   |____/|_____|                  #
-#                                                                      #
-#                == Physical Simulation Environment ==                 #
-#                                                                      #
-########################################################################
-
-
 '''
-gnpy route planning and optimization library
-============================================
+Simulation of signal propagation in the DWDM network
 
-gnpy is a route planning and optimization library, written in Python, for
-operators of large-scale mesh optical networks.
-
-:copyright: © 2018, Telecom Infra Project
-:license: BSD 3-Clause, see LICENSE for more details.
+Optical signals, as defined via :class:`.info.SpectralInformation`, enter
+:py:mod:`.elements` which compute how these signals are affected as they travel
+through the :py:mod:`.network`.
+The simulation is controlled via :py:mod:`.parameters` and implemented mainly
+via :py:mod:`.science_utils`.
 '''
-
-from . import elements
-from .execute import *
-from .network import *
-from .utils import *

gnpy/core/ansi_escapes.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.core.ansi_escapes
+======================
+
+A random subset of ANSI terminal escape codes for colored messages
+'''
+
+red = '\x1b[1;31;40m'
+blue = '\x1b[1;34;40m'
+cyan = '\x1b[1;36;40m'
+yellow = '\x1b[1;33;40m'
+reset = '\x1b[0m'

gnpy/core/convert.py

@@ -1,581 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-gnpy.core.convert
-=================
-
-This module contains utilities for converting between XLS and JSON.
-
-The input XLS file must contain sheets named "Nodes" and "Links".
-It may optionally contain a sheet named "Eqpt".
-
-In the "Nodes" sheet, only the "City" column is mandatory. The column "Type"
-can be determined automatically given the topology (e.g., if degree 2, ILA;
-otherwise, ROADM.) Incorrectly specified types (e.g., ILA for node of
-degree ≠ 2) will be automatically corrected.
-
-In the "Links" sheet, only the first three columns ("Node A", "Node Z" and
-"east Distance (km)") are mandatory.  Missing "west" information is copied from
-the "east" information so that it is possible to input undirected data.
-"""
-
-from sys import exit
-try:
-    from xlrd import open_workbook
-except ModuleNotFoundError:
-    exit('Required: `pip install xlrd`')
-from argparse import ArgumentParser
-from collections import namedtuple, Counter, defaultdict
-from itertools import chain
-from json import dumps
-from pathlib import Path
-from difflib import get_close_matches
-import time
-
-all_rows = lambda sh, start=0: (sh.row(x) for x in range(start, sh.nrows))
-
-class Node(object):
-    def __init__(self, **kwargs):
-        super(Node, self).__init__()
-        self.update_attr(kwargs)
-
-    def update_attr(self, kwargs):
-        clean_kwargs = {k:v for k,v in kwargs.items() if v !=''}
-        for k,v in self.default_values.items():
-            v = clean_kwargs.get(k,v)
-            setattr(self, k, v)
-
-    default_values = \
-    {
-        'city':         '',
-        'state':        '',
-        'country':      '',
-        'region':       '',
-        'latitude':     0,
-        'longitude':    0,
-        'node_type':    'ILA'
-    }
-
-class Link(object):
-    """attribtes from west parse_ept_headers dict
-    +node_a, node_z, west_fiber_con_in, east_fiber_con_in
-    """
-    def __init__(self, **kwargs):
-        super(Link, self).__init__()
-        self.update_attr(kwargs)
-        self.distance_units = 'km'
-
-    def update_attr(self, kwargs):
-        clean_kwargs = {k:v for k,v in kwargs.items() if v !=''}
-        for k,v in self.default_values.items():
-            v = clean_kwargs.get(k,v)
-            setattr(self, k, v)
-            k = 'west' + k.split('east')[-1]
-            v = clean_kwargs.get(k,v)
-            setattr(self, k, v)
-
-    def __eq__(self, link):
-        return (self.from_city == link.from_city and self.to_city == link.to_city) \
-                or (self.from_city == link.to_city and self.to_city == link.from_city)
-
-    default_values = \
-    {
-            'from_city':            '',
-            'to_city':              '',
-            'east_distance':        80,
-            'east_fiber':           'SSMF',
-            'east_lineic':          0.2,
-            'east_con_in':          None,
-            'east_con_out':         None,
-            'east_pmd':             0.1,
-            'east_cable':           ''
-    }
-
-
-class Eqpt(object):
-    def __init__(self, **kwargs):
-        super(Eqpt, self).__init__()
-        self.update_attr(kwargs)
-
-    def update_attr(self, kwargs):
-        clean_kwargs = {k:v for k,v in kwargs.items() if v !=''}
-        for k,v in self.default_values.items():
-            v_east = clean_kwargs.get(k,v)
-            setattr(self, k, v_east)
-            k = 'west' + k.split('east')[-1]
-            v_west = clean_kwargs.get(k,v)
-            setattr(self, k, v_west)
-
-    default_values = \
-    {
-            'from_city':        '',
-            'to_city':          '',
-            'east_amp_type':         '',
-            'east_att_in':           0,
-            'east_amp_gain':         0,
-            'east_tilt':             0,
-            'east_att_out':          0
-    }
-
-
-def read_header(my_sheet, line, slice_):
-    """ return the list of headers !:= ''
-    header_i = [(header, header_column_index), ...]
-    in a {line, slice1_x, slice_y} range
-    """
-    Param_header = namedtuple('Param_header', 'header colindex')
-    try:
-        header = [x.value.strip() for x in my_sheet.row_slice(line, slice_[0], slice_[1])]
-        header_i = [Param_header(header,i+slice_[0]) for i, header in enumerate(header) if header != '']
-    except Exception:
-        header_i = []
-    if header_i != [] and header_i[-1].colindex != slice_[1]:
-        header_i.append(Param_header('',slice_[1]))
-    return header_i
-
-def read_slice(my_sheet, line, slice_, header):
-    """return the slice range of a given header
-    in a defined range {line, slice_x, slice_y}"""
-    header_i = read_header(my_sheet, line, slice_)
-    slice_range = (-1,-1)
-    if header_i != []:
-        try:
-            slice_range = next((h.colindex,header_i[i+1].colindex) \
-                for i,h in enumerate(header_i) if header in h.header)
-        except Exception:
-            pass
-    return slice_range
-
-
-def parse_headers(my_sheet, input_headers_dict, headers, start_line, slice_in):
-    """return a dict of header_slice
-    key = column index
-    value = header name"""
-
-
-    for h0 in input_headers_dict:
-        slice_out = read_slice(my_sheet, start_line, slice_in, h0)
-        iteration = 1
-        while slice_out == (-1,-1) and iteration < 10:
-            #try next lines
-            #print(h0, iteration)
-            slice_out = read_slice(my_sheet, start_line+iteration, slice_in, h0)
-            iteration += 1
-        if slice_out == (-1, -1):
-            if h0 == 'east':
-                print(f'\x1b[1;31;40m'+f'CRITICAL: missing _east_ header above other headers (hierarchical) _ ABORT'+ '\x1b[0m')
-                exit()
-            else:
-                print(f'missing header {h0}')
-        elif not isinstance(input_headers_dict[h0], dict):
-            headers[slice_out[0]] = input_headers_dict[h0]
-        else:
-            headers = parse_headers(my_sheet, input_headers_dict[h0], headers, start_line+1, slice_out)
-    if headers == {}:
-        print(f'\x1b[1;31;40m'+f'CRITICAL ERROR: could not find any header to read _ ABORT'+ '\x1b[0m')
-        exit()
-    return headers
-
-def parse_row(row, headers):
-    #print([label for label in ept.values()])
-    #print([i for i in ept.keys()])
-    #print(row[i for i in ept.keys()])
-    return {f: r.value for f, r in \
-            zip([label for label in headers.values()], [row[i] for i in headers])}
-            #if r.ctype != XL_CELL_EMPTY}
-
-def parse_sheet(my_sheet, input_headers_dict, header_line, start_line, column):
-    headers = parse_headers(my_sheet, input_headers_dict, {}, header_line, (0,column))
-    for row in all_rows(my_sheet, start=start_line):
-        yield parse_row(row[0: column], headers)
-
-def sanity_check(nodes, links, nodes_by_city, links_by_city, eqpts_by_city):
-
-    duplicate_links = []
-    for l1 in links:
-        for l2 in links:
-            if l1 is not l2 and l1 == l2 and l2 not in duplicate_links:
-                print(f'\nWARNING\n \
-                    link {l1.from_city}-{l1.to_city} is duplicate \
-                    \nthe 1st duplicate link will be removed but you should check Links sheet input')
-                duplicate_links.append(l1)
-    #if duplicate_links != []:
-        #time.sleep(3)
-    for l in duplicate_links:
-        links.remove(l)
-
-    try :
-        test_nodes = [n for n in nodes_by_city if not n in links_by_city]
-        test_links = [n for n in links_by_city if not n in nodes_by_city]
-        test_eqpts = [n for n in eqpts_by_city if not n in nodes_by_city]
-        assert (test_nodes == [] or test_nodes == [''])\
-                and (test_links == [] or test_links ==[''])\
-                and (test_eqpts == [] or test_eqpts ==[''])
-    except AssertionError:
-        print(f'CRITICAL error: \nNames in Nodes and Links sheets do no match, check:\
-            \n{test_nodes} in Nodes sheet\
-            \n{test_links} in Links sheet\
-            \n{test_eqpts} in Eqpt sheet')
-        exit(1)
-
-    for city,link in links_by_city.items():
-        if nodes_by_city[city].node_type.lower()=='ila' and len(link) != 2:
-            #wrong input: ILA sites can only be Degree 2
-            # => correct to make it a ROADM and remove entry in links_by_city
-            #TODO : put in log rather than print
-            print(f'invalid node type ({nodes_by_city[city].node_type})\
- specified in {city}, replaced by ROADM')
-            nodes_by_city[city].node_type = 'ROADM'
-            for n in nodes:
-                if n.city==city:
-                    n.node_type='ROADM'
-    return nodes, links
-
-def convert_file(input_filename, names_matching=False, filter_region=[]):
-    nodes, links, eqpts = parse_excel(input_filename)
-
-    if filter_region:
-        nodes = [n for n in nodes if n.region.lower() in filter_region]
-        cities = {n.city for n in nodes}
-        links = [lnk for lnk in links if lnk.from_city in cities and
-                                         lnk.to_city in cities]
-        cities = {lnk.from_city for lnk in links} | {lnk.to_city for lnk in links}
-        nodes = [n for n in nodes if n.city in cities]
-
-
-    global nodes_by_city
-    nodes_by_city = {n.city: n for n in nodes}
-
-    #create matching dictionary for node name mismatch analysis
-
-    cities = {''.join(c.strip() for c in n.city.split('C+L')).lower(): n.city for n in nodes}
-    cities_to_match = [k for k in cities]
-    city_match_dic = defaultdict(list)
-    for city in cities:
-        if city in cities_to_match:
-            cities_to_match.remove(city)
-        matches = get_close_matches(city, cities_to_match, 4, 0.85)
-        for m in matches:
-            city_match_dic[cities[city]].append(cities[m])
-    #check lower case/upper case
-    for city in nodes_by_city:
-        for match_city in nodes_by_city:
-            if match_city.lower() == city.lower() and match_city != city:
-                city_match_dic[city].append(match_city)
-
-    if names_matching:
-        print('\ncity match dictionary:',city_match_dic)
-    with  open('name_match_dictionary.json', 'w', encoding='utf-8') as city_match_dic_file:
-        city_match_dic_file.write(dumps(city_match_dic, indent=2, ensure_ascii=False))
-
-    global links_by_city
-    links_by_city = defaultdict(list)
-    for link in links:
-        links_by_city[link.from_city].append(link)
-        links_by_city[link.to_city].append(link)
-
-    global eqpts_by_city
-    eqpts_by_city = defaultdict(list)
-    for eqpt in eqpts:
-        eqpts_by_city[eqpt.from_city].append(eqpt)
-
-    nodes, links = sanity_check(nodes, links, nodes_by_city, links_by_city, eqpts_by_city)
-
-    data = {
-        'elements':
-            [{'uid': f'trx {x.city}',
-              'metadata': {'location': {'city':      x.city,
-                                        'region':    x.region,
-                                        'latitude':  x.latitude,
-                                        'longitude': x.longitude}},
-              'type': 'Transceiver'}
-             for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'] +
-            [{'uid': f'roadm {x.city}',
-              'metadata': {'location': {'city':      x.city,
-                                        'region':    x.region,
-                                        'latitude':  x.latitude,
-                                        'longitude': x.longitude}},
-              'type': 'Roadm'}
-             for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'] +
-            [{'uid': f'west fused spans in {x.city}',
-              'metadata': {'location': {'city':      x.city,
-                                        'region':    x.region,
-                                        'latitude':  x.latitude,
-                                        'longitude': x.longitude}},
-              'type': 'Fused'}
-             for x in nodes_by_city.values() if x.node_type.lower() == 'fused'] +
-            [{'uid': f'east fused spans in {x.city}',
-              'metadata': {'location': {'city':      x.city,
-                                        'region':    x.region,
-                                        'latitude':  x.latitude,
-                                        'longitude': x.longitude}},
-              'type': 'Fused'}
-             for x in nodes_by_city.values() if x.node_type.lower() == 'fused'] +
-            [{'uid': f'fiber ({x.from_city} \u2192 {x.to_city})-{x.east_cable}',
-              'metadata': {'location': midpoint(nodes_by_city[x.from_city],
-                                                nodes_by_city[x.to_city])},
-              'type': 'Fiber',
-              'type_variety': x.east_fiber,
-              'params': {'length':   round(x.east_distance, 3),
-                         'length_units':    x.distance_units,
-                         'loss_coef': x.east_lineic,
-                         'con_in':x.east_con_in,
-                         'con_out':x.east_con_out}
-            }
-              for x in links] +
-            [{'uid': f'fiber ({x.to_city} \u2192 {x.from_city})-{x.west_cable}',
-              'metadata': {'location': midpoint(nodes_by_city[x.from_city],
-                                                nodes_by_city[x.to_city])},
-              'type': 'Fiber',
-              'type_variety': x.west_fiber,
-              'params': {'length':   round(x.west_distance, 3),
-                         'length_units':    x.distance_units,
-                         'loss_coef': x.west_lineic,
-                         'con_in':x.west_con_in,
-                         'con_out':x.west_con_out}
-            } # missing ILA construction
-              for x in links] +
-            [{'uid': f'east edfa in {e.from_city} to {e.to_city}',
-              'metadata': {'location': {'city':      nodes_by_city[e.from_city].city,
-                                        'region':    nodes_by_city[e.from_city].region,
-                                        'latitude':  nodes_by_city[e.from_city].latitude,
-                                        'longitude': nodes_by_city[e.from_city].longitude}},
-              'type': 'Edfa',
-              'type_variety': e.east_amp_type,
-              'operational': {'gain_target': e.east_amp_gain,
-                              'tilt_target': e.east_tilt,
-                              'out_voa'    : e.east_att_out}
-            }
-             for e in eqpts if e.east_amp_type.lower() != ''] +
-            [{'uid': f'west edfa in {e.from_city} to {e.to_city}',
-              'metadata': {'location': {'city':      nodes_by_city[e.from_city].city,
-                                        'region':    nodes_by_city[e.from_city].region,
-                                        'latitude':  nodes_by_city[e.from_city].latitude,
-                                        'longitude': nodes_by_city[e.from_city].longitude}},
-              'type': 'Edfa',
-              'type_variety': e.west_amp_type,
-              'operational': {'gain_target': e.west_amp_gain,
-                              'tilt_target': e.west_tilt,
-                              'out_voa'    : e.west_att_out}
-              }
-             for e in eqpts if e.west_amp_type.lower() != ''],
-        'connections':
-            list(chain.from_iterable([eqpt_connection_by_city(n.city)
-            for n in nodes]))
-            +
-            list(chain.from_iterable(zip(
-            [{'from_node': f'trx {x.city}',
-              'to_node':   f'roadm {x.city}'}
-             for x in nodes_by_city.values() if x.node_type.lower()=='roadm'],
-            [{'from_node': f'roadm {x.city}',
-              'to_node':   f'trx {x.city}'}
-             for x in nodes_by_city.values() if x.node_type.lower()=='roadm'])))
-    }
-
-    suffix_filename = str(input_filename.suffixes[0])
-    full_input_filename = str(input_filename)
-    split_filename = [full_input_filename[0:len(full_input_filename)-len(suffix_filename)] , suffix_filename[1:]]
-    output_json_file_name = split_filename[0]+'.json'
-    with  open(output_json_file_name, 'w', encoding='utf-8') as edfa_json_file:
-        edfa_json_file.write(dumps(data, indent=2, ensure_ascii=False))
-    return output_json_file_name
-
-def parse_excel(input_filename):
-    link_headers = \
-    {  'Node A': 'from_city',
-       'Node Z': 'to_city',
-       'east':{
-            'Distance (km)':        'east_distance',
-            'Fiber type':           'east_fiber',
-            'lineic att':           'east_lineic',
-            'Con_in':               'east_con_in',
-            'Con_out':              'east_con_out',
-            'PMD':                  'east_pmd',
-            'Cable id':             'east_cable'
-        },
-        'west':{
-            'Distance (km)':        'west_distance',
-            'Fiber type':           'west_fiber',
-            'lineic att':           'west_lineic',
-            'Con_in':               'west_con_in',
-            'Con_out':              'west_con_out',
-            'PMD':                  'west_pmd',
-            'Cable id':             'west_cable'
-        }
-    }
-    node_headers = \
-    {   'City':         'city',
-        'State':        'state',
-        'Country':      'country',
-        'Region':       'region',
-        'Latitude':     'latitude',
-        'Longitude':    'longitude',
-        'Type':         'node_type'
-    }
-    eqpt_headers = \
-    {  'Node A': 'from_city',
-       'Node Z': 'to_city',
-       'east':{
-            'amp type':         'east_amp_type',
-            'att_in':           'east_att_in',
-            'amp gain':         'east_amp_gain',
-            'tilt':             'east_tilt',
-            'att_out':          'east_att_out'
-       },
-       'west':{
-            'amp type':         'west_amp_type',
-            'att_in':           'west_att_in',
-            'amp gain':         'west_amp_gain',
-            'tilt':             'west_tilt',
-            'att_out':          'west_att_out'
-       }
-    }
-
-    with open_workbook(input_filename) as wb:
-        nodes_sheet = wb.sheet_by_name('Nodes')
-        links_sheet = wb.sheet_by_name('Links')
-        try:
-            eqpt_sheet = wb.sheet_by_name('Eqpt')
-        except Exception:
-            #eqpt_sheet is optional
-            eqpt_sheet = None
-
-        nodes = []
-        for node in parse_sheet(nodes_sheet, node_headers, NODES_LINE, NODES_LINE+1, NODES_COLUMN):
-            nodes.append(Node(**node))
-        expected_node_types = {'ROADM', 'ILA', 'FUSED'}
-        for n in nodes:
-            if n.node_type not in expected_node_types:
-                n.node_type = 'ILA'
-
-        links = []
-        for link in parse_sheet(links_sheet, link_headers, LINKS_LINE, LINKS_LINE+2, LINKS_COLUMN):
-            links.append(Link(**link))
-        #print('\n', [l.__dict__ for l in links])
-
-        eqpts = []
-        if eqpt_sheet != None:
-            for eqpt in parse_sheet(eqpt_sheet, eqpt_headers, EQPTS_LINE, EQPTS_LINE+2, EQPTS_COLUMN):
-                eqpts.append(Eqpt(**eqpt))
-
-    # sanity check
-    all_cities = Counter(n.city for n in nodes)
-    if len(all_cities) != len(nodes):
-        ValueError(f'Duplicate city: {all_cities}')
-    if any(ln.from_city not in all_cities or
-           ln.to_city   not in all_cities for ln in links):
-        ValueError(f'Bad link.')
-
-    return nodes, links, eqpts
-
-
-def eqpt_connection_by_city(city_name):
-    other_cities = fiber_dest_from_source(city_name)
-    subdata = []
-    if nodes_by_city[city_name].node_type.lower() in {'ila', 'fused'}:
-        # Then len(other_cities) == 2
-        direction = ['west', 'east']
-        for i in range(2):
-            from_ = fiber_link(other_cities[i], city_name)
-            in_ = eqpt_in_city_to_city(city_name, other_cities[0],direction[i])
-            to_ = fiber_link(city_name, other_cities[1-i])
-            subdata += connect_eqpt(from_, in_, to_)
-    elif nodes_by_city[city_name].node_type.lower() == 'roadm':
-        for other_city in other_cities:
-            from_ = f'roadm {city_name}'
-            in_ = eqpt_in_city_to_city(city_name, other_city)
-            to_ = fiber_link(city_name, other_city)
-            subdata += connect_eqpt(from_, in_, to_)
-
-            from_ = fiber_link(other_city, city_name)
-            in_ = eqpt_in_city_to_city(city_name, other_city, "west")
-            to_ = f'roadm {city_name}'
-            subdata += connect_eqpt(from_, in_, to_)
-    return subdata
-
-
-def connect_eqpt(from_, in_, to_):
-    connections = []
-    if in_ !='':
-        connections = [{'from_node': from_, 'to_node': in_},
-                      {'from_node': in_, 'to_node': to_}]
-    else:
-        connections = [{'from_node': from_, 'to_node': to_}]
-    return connections
-
-
-def eqpt_in_city_to_city(in_city, to_city, direction='east'):
-    rev_direction = 'west' if direction == 'east' else 'east'
-    amp_direction = f'{direction}_amp_type'
-    amp_rev_direction = f'{rev_direction}_amp_type'
-    return_eqpt = ''
-    if in_city in eqpts_by_city:
-        for e in eqpts_by_city[in_city]:
-            if nodes_by_city[in_city].node_type.lower() == 'roadm':
-                if e.to_city == to_city and getattr(e, amp_direction) != '':
-                    return_eqpt = f'{direction} edfa in {e.from_city} to {e.to_city}'
-            elif nodes_by_city[in_city].node_type.lower() == 'ila':
-                if e.to_city != to_city:
-                    direction = rev_direction
-                    amp_direction = amp_rev_direction
-                if getattr(e, amp_direction) != '':
-                    return_eqpt = f'{direction} edfa in {e.from_city} to {e.to_city}'
-    if nodes_by_city[in_city].node_type.lower() == 'fused':
-        return_eqpt = f'{direction} fused spans in {in_city}'
-    return return_eqpt
-
-
-def fiber_dest_from_source(city_name):
-    destinations = []
-    links_from_city = links_by_city[city_name]
-    for l in links_from_city:
-        if l.from_city == city_name:
-            destinations.append(l.to_city)
-        else:
-            destinations.append(l.from_city)
-    return destinations
-
-
-def fiber_link(from_city, to_city):
-    source_dest = (from_city, to_city)
-    link = links_by_city[from_city]
-    l = next(l for l in link if l.from_city in source_dest and l.to_city in source_dest)
-    if l.from_city == from_city:
-        fiber = f'fiber ({l.from_city} \u2192 {l.to_city})-{l.east_cable}'
-    else:
-        fiber = f'fiber ({l.to_city} \u2192 {l.from_city})-{l.west_cable}'
-    return fiber
-
-
-def midpoint(city_a, city_b):
-    lats  = city_a.latitude, city_b.latitude
-    longs = city_a.longitude, city_b.longitude
-    try:
-        result = {
-        'latitude':  sum(lats)  / 2,
-        'longitude': sum(longs) / 2
-                }
-    except :
-        result = {
-        'latitude':  0,
-        'longitude': 0
-                }
-    return result
-
-#output_json_file_name = 'coronet_conus_example.json'
-#TODO get column size automatically from tupple size
-
-NODES_COLUMN = 7
-NODES_LINE = 4
-LINKS_COLUMN = 16
-LINKS_LINE = 3
-EQPTS_LINE = 3
-EQPTS_COLUMN = 12
-parser = ArgumentParser()
-parser.add_argument('workbook', nargs='?', type=Path , default='meshTopologyExampleV2.xls')
-parser.add_argument('-f', '--filter-region', action='append', default=[])
-
-if __name__ == '__main__':
-    args = parser.parse_args()
-    convert_file(args.workbook, args.filter_region)

gnpy/core/equipment.py

@@ -8,196 +8,49 @@ gnpy.core.equipment
 This module contains functionality for specifying equipment.
 '''
 
-from numpy import clip, polyval
-from sys import exit
-from operator import itemgetter
-from math import isclose
-from pathlib import Path
-from json import load
-from gnpy.core.utils import lin2db, db2lin, load_json
-from collections import namedtuple
-from gnpy.core.elements import Edfa
+from gnpy.core.utils import automatic_nch, db2lin
+from gnpy.core.exceptions import EquipmentConfigError
 
-Model_vg = namedtuple('Model_vg', 'nf1 nf2 delta_p')
-Model_fg = namedtuple('Model_fg', 'nf0')
-Model_openroadm = namedtuple('Model_openroadm', 'nf_coef')
-Fiber = namedtuple('Fiber', 'type_variety dispersion gamma')
-Spans = namedtuple('Spans', 'power_mode delta_power_range_db max_length length_units \
-                             max_loss padding EOL con_in con_out')
-Transceiver = namedtuple('Transceiver', 'type_variety frequency mode')
-Roadms = namedtuple('Roadms', 'gain_mode_default_loss power_mode_pout_target add_drop_osnr')
-SI = namedtuple('SI', 'f_min f_max baud_rate spacing roll_off \
-                       power_dbm power_range_db tx_osnr sys_margins')
-AmpBase = namedtuple(
-    'AmpBase',
-    'type_variety type_def gain_flatmax gain_min p_max'
-    ' nf_model nf_fit_coeff nf_ripple dgt gain_ripple out_voa_auto allowed_for_design')
-class Amp(AmpBase):
-    def __new__(cls,
-            type_variety, type_def, gain_flatmax, gain_min, p_max, nf_model=None,
-            nf_fit_coeff=None, nf_ripple=None, dgt=None, gain_ripple=None,
-             out_voa_auto=False, allowed_for_design=True):
-        return super().__new__(cls,
-            type_variety, type_def, gain_flatmax, gain_min, p_max,
-            nf_model, nf_fit_coeff, nf_ripple, dgt, gain_ripple,
-            out_voa_auto, allowed_for_design)
-
-    @classmethod
-    def from_advanced_json(cls, filename, **kwargs):
-        with open(filename, encoding='utf-8') as f:
-            json_data = load(f)
-        return cls(**{**kwargs, **json_data, 'type_def':None, 'nf_model':None})
-
-    @classmethod
-    def from_default_json(cls, filename, **kwargs):
-        with open(filename, encoding='utf-8') as f:
-            json_data = load(f)
-        type_variety = kwargs['type_variety']
-        type_def = kwargs.get('type_def', 'variable_gain') #default compatibility with older json eqpt files
-        nf_def = None
-
-        if type_def == 'fixed_gain':
-            try:
-                nf0 = kwargs.pop('nf0')
-            except KeyError: #nf0 is expected for a fixed gain amp
-                print(f'missing nf0 value input for amplifier: {type_variety} in eqpt_config.json')
-                exit()
-            try: #remove all remaining nf inputs
-                del kwargs['nf_min']
-                del kwargs['nf_max']
-            except KeyError: pass #nf_min and nf_max are not needed for fixed gain amp
-            nf_def = Model_fg(nf0)
-        elif type_def == 'variable_gain':
-            gain_min, gain_max = kwargs['gain_min'], kwargs['gain_flatmax']
-            try: #nf_min and nf_max are expected for a variable gain amp
-                nf_min = kwargs.pop('nf_min')
-                nf_max = kwargs.pop('nf_max')
-            except KeyError:
-                print(f'missing nf_min/max value input for amplifier: {type_variety} in eqpt_config.json')
-                exit()
-            try: #remove all remaining nf inputs
-                del kwargs['nf0']
-            except KeyError: pass #nf0 is not needed for variable gain amp
-            nf1, nf2, delta_p = nf_model(type_variety, gain_min, gain_max, nf_min, nf_max)
-            nf_def = Model_vg(nf1, nf2, delta_p)
-        elif type_def == 'openroadm':
-            try:
-                nf_coef = kwargs.pop('nf_coef')
-            except KeyError: #nf_coef is expected for openroadm amp
-                print(f'missing nf_coef input for amplifier: {type_variety} in eqpt_config.json')
-                exit()
-            nf_def = Model_openroadm(nf_coef)
-        return cls(**{**kwargs, **json_data, 'nf_model': nf_def})
-
-
-def nf_model(type_variety, gain_min, gain_max, nf_min, nf_max):
-    if nf_min < -10:
-        print(f'Invalid nf_min value {nf_min!r} for amplifier {type_variety}')
-        exit()
-    if nf_max < -10:
-        print(f'Invalid nf_max value {nf_max!r} for amplifier {type_variety}')
-        exit()
-
-    # NF estimation model based on nf_min and nf_max
-    # delta_p:  max power dB difference between first and second stage coils
-    # dB g1a:   first stage gain - internal VOA attenuation
-    # nf1, nf2: first and second stage coils
-    #           calculated by solving nf_{min,max} = nf1 + nf2 / g1a{min,max}
-    delta_p = 5
-    g1a_min = gain_min - (gain_max - gain_min) - delta_p
-    g1a_max = gain_max - delta_p
-    nf2 = lin2db((db2lin(nf_min) - db2lin(nf_max)) /
-                 (1/db2lin(g1a_max) - 1/db2lin(g1a_min)))
-    nf1 = lin2db(db2lin(nf_min) - db2lin(nf2)/db2lin(g1a_max))
-
-    if nf1 < 4:
-        print(f'First coil value too low {nf1} for amplifier {type_variety}')
-        exit()
-
-    # Check 1 dB < delta_p < 6 dB to ensure nf_min and nf_max values make sense.
-    # There shouldn't be high nf differences between the two coils:
-    #    nf2 should be nf1 + 0.3 < nf2 < nf1 + 2
-    # If not, recompute and check delta_p
-    if not nf1 + 0.3 < nf2 < nf1 + 2:
-        nf2 = clip(nf2, nf1 + 0.3, nf1 + 2)
-        g1a_max = lin2db(db2lin(nf2) / (db2lin(nf_min) - db2lin(nf1)))
-        delta_p = gain_max - g1a_max
-        g1a_min = gain_min - (gain_max-gain_min) - delta_p
-        if not 1 < delta_p < 6:
-            print(f'Computed \N{greek capital letter delta}P invalid \
-                \n 1st coil vs 2nd coil calculated DeltaP {delta_p:.2f} for \
-                \n amplifier {type_variety} is not valid: revise inputs \
-                \n calculated 1st coil NF = {nf1:.2f}, 2nd coil NF = {nf2:.2f}')
-            exit()
-    # Check calculated values for nf1 and nf2
-    calc_nf_min = lin2db(db2lin(nf1) + db2lin(nf2)/db2lin(g1a_max))
-    if not isclose(nf_min, calc_nf_min, abs_tol=0.01):
-        print(f'nf_min does not match calc_nf_min, {nf_min} vs {calc_nf_min} for amp {type_variety}')
-        exit()
-    calc_nf_max = lin2db(db2lin(nf1) + db2lin(nf2)/db2lin(g1a_min))
-    if not isclose(nf_max, calc_nf_max, abs_tol=0.01):
-        print(f'nf_max does not match calc_nf_max, {nf_max} vs {calc_nf_max} for amp {type_variety}')
-        exit()
-
-    return nf1, nf2, delta_p
-
-def edfa_nf(gain_target, variety_type, equipment):
-    amp_params = equipment['Edfa'][variety_type]
-    amp = Edfa(
-            uid = f'calc_NF',
-            params = amp_params._asdict(),
-            operational = {
-                'gain_target': gain_target,
-                'tilt_target': 0
-                        }
-            )
-    amp.pin_db = 0
-    amp.nch = 88
-    return amp._calc_nf(True)
 
 def trx_mode_params(equipment, trx_type_variety='', trx_mode='', error_message=False):
     """return the trx and SI parameters from eqpt_config for a given type_variety and mode (ie format)"""
     trx_params = {}
     default_si_data = equipment['SI']['default']
-    
+
     try:
         trxs = equipment['Transceiver']
-        #if called from path_requests_run.py, trx_mode is filled with None when not specified by user
-        #if called from transmission_main.py, trx_mode is ''
+        # if called from path_requests_run.py, trx_mode is filled with None when not specified by user
+        # if called from transmission_main.py, trx_mode is ''
         if trx_mode is not None:
-            mode_params = next(mode for trx in trxs \
-                        if trx == trx_type_variety \
-                        for mode in trxs[trx].mode \
-                        if mode['format'] == trx_mode)
+            mode_params = next(mode for trx in trxs
+                               if trx == trx_type_variety
+                               for mode in trxs[trx].mode
+                               if mode['format'] == trx_mode)
             trx_params = {**mode_params}
             # sanity check: spacing baudrate must be smaller than min spacing
-            if trx_params['baud_rate'] > trx_params['min_spacing'] :
-                msg = f'Inconsistency in equipment library:\n Transpoder "{trx_type_variety}" mode "{trx_params["format"]}" '+\
-                    f'has baud rate: {trx_params["baud_rate"]*1e-9} GHz greater than min_spacing {trx_params["min_spacing"]*1e-9}.'
-                print(msg)
-                exit()
+            if trx_params['baud_rate'] > trx_params['min_spacing']:
+                raise EquipmentConfigError(f'Inconsistency in equipment library:\n Transpoder "{trx_type_variety}" mode "{trx_params["format"]}" ' +
+                                           f'has baud rate {trx_params["baud_rate"]*1e-9} GHz greater than min_spacing {trx_params["min_spacing"]*1e-9}.')
         else:
             mode_params = {"format": "undetermined",
-                       "baud_rate": None,
-                       "OSNR": None,
-                       "bit_rate": None,
-                       "roll_off": None,
-                       "tx_osnr":None,
-                       "min_spacing":None,
-                       "cost":None}
-            trx_params = {**mode_params} 
+                           "baud_rate": None,
+                           "OSNR": None,
+                           "bit_rate": None,
+                           "roll_off": None,
+                           "tx_osnr": None,
+                           "min_spacing": None,
+                           "cost": None}
+            trx_params = {**mode_params}
         trx_params['f_min'] = equipment['Transceiver'][trx_type_variety].frequency['min']
         trx_params['f_max'] = equipment['Transceiver'][trx_type_variety].frequency['max']
 
         # TODO: novel automatic feature maybe unwanted if spacing is specified
-        # trx_params['spacing'] = automatic_spacing(trx_params['baud_rate'])
+        # trx_params['spacing'] = _automatic_spacing(trx_params['baud_rate'])
         # temp = trx_params['spacing']
         # print(f'spacing {temp}')
-    except StopIteration :
+    except StopIteration:
         if error_message:
-            print(f'could not find tsp : {trx_type_variety} with mode: {trx_mode} in eqpt library')
-            print('Computation stopped.')
-            exit()
+            raise EquipmentConfigError(f'Could not find transponder "{trx_type_variety}" with mode "{trx_mode}" in equipment library')
         else:
             # default transponder charcteristics
             # mainly used with transmission_main_example.py
@@ -214,58 +67,7 @@ def trx_mode_params(equipment, trx_type_variety='', trx_mode='', error_message=F
             nch = automatic_nch(trx_params['f_min'], trx_params['f_max'], trx_params['spacing'])
             trx_params['nb_channel'] = nch
             print(f'There are {nch} channels propagating')
-                
-    trx_params['power'] =  db2lin(default_si_data.power_dbm)*1e-3
+
+    trx_params['power'] = db2lin(default_si_data.power_dbm) * 1e-3
 
     return trx_params
-
-def automatic_spacing(baud_rate):
-    """return the min possible channel spacing for a given baud rate"""
-    # TODO : this should parametrized in a cfg file
-    spacing_list = [(33e9,37.5e9), (38e9,50e9), (50e9,62.5e9), (67e9,75e9), (92e9,100e9)] #list of possible tuples
-                                                #[(max_baud_rate, spacing_for_this_baud_rate)]
-    return min((s[1] for s in spacing_list if s[0] > baud_rate), default=baud_rate*1.2)
-
-def automatic_nch(f_min, f_max, spacing):
-    return int((f_max - f_min)//spacing)
-
-def automatic_fmax(f_min, spacing, nch):
-    return f_min + spacing * nch
-
-def load_equipment(filename):
-    json_data = load_json(filename)
-    return equipment_from_json(json_data, filename)
-
-def update_trx_osnr(equipment):
-    """add sys_margins to all Transceivers OSNR values"""
-    for trx in equipment['Transceiver'].values():
-        for m in trx.mode:
-            m['OSNR'] = m['OSNR'] + equipment['SI']['default'].sys_margins
-    return equipment
-
-def equipment_from_json(json_data, filename):
-    """build global dictionnary eqpt_library that stores all eqpt characteristics:
-    edfa type type_variety, fiber type_variety
-    from the eqpt_config.json (filename parameter)
-    also read advanced_config_from_json file parameters for edfa if they are available:
-    typically nf_ripple, dfg gain ripple, dgt and nf polynomial nf_fit_coeff
-    if advanced_config_from_json file parameter is not present: use nf_model:
-    requires nf_min and nf_max values boundaries of the edfa gain range
-    """
-    equipment = {}
-    for key, entries in json_data.items():
-        equipment[key] = {}
-        typ = globals()[key]
-        for entry in entries:
-            subkey = entry.get('type_variety', 'default')           
-            if key == 'Edfa':
-                if 'advanced_config_from_json' in entry:
-                    config = Path(filename).parent / entry.pop('advanced_config_from_json')
-                    equipment[key][subkey] = Amp.from_advanced_json(config, **entry)
-                else:
-                    config = Path(filename).parent / 'default_edfa_config.json'
-                    equipment[key][subkey] = Amp.from_default_json(config, **entry)
-            else:                
-                equipment[key][subkey] = typ(**entry)
-    equipment = update_trx_osnr(equipment)
-    return equipment

gnpy/core/exceptions.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.core.exceptions
+====================
+
+Exceptions thrown by other gnpy modules
+"""
+
+
+class ConfigurationError(Exception):
+    """User-provided configuration contains an error"""
+
+
+class EquipmentConfigError(ConfigurationError):
+    """Incomplete or wrong configuration within the equipment library"""
+
+
+class NetworkTopologyError(ConfigurationError):
+    """Topology of user-provided network is wrong"""
+
+
+class ServiceError(Exception):
+    """Service of user-provided request is wrong"""
+
+
+class DisjunctionError(ServiceError):
+    """Disjunction of user-provided request can not be satisfied"""
+
+
+class SpectrumError(Exception):
+    """Spectrum errors of the program"""
+
+
+class ParametersError(ConfigurationError):
+    """Incomplete or wrong configurations within parameters json"""

gnpy/core/execute.py

@@ -1,10 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-'''
-gnpy.core.execute
-=================
-
-This module contains functions for executing the propogation of
-spectral information on a `gnpy` network.
-'''

gnpy/core/info.py

@@ -1,91 +1,56 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-'''
+"""
 gnpy.core.info
 ==============
 
-This module contains classes for modelling SpectralInformation.
-'''
-
+This module contains classes for modelling :class:`SpectralInformation`.
+"""
 
 from collections import namedtuple
-from numpy import array
-from gnpy.core.utils import lin2db, db2lin
-from json import loads
-from gnpy.core.utils import load_json
-from gnpy.core.equipment import automatic_nch, automatic_spacing
-
-class ConvenienceAccess:
-
-    def __init_subclass__(cls):
-        for abbrev, field in getattr(cls, '_ABBREVS', {}).items():
-            setattr(cls, abbrev, property(lambda self, f=field: getattr(self, f)))
-
-    def update(self, **kwargs):
-        for abbrev, field in getattr(self, '_ABBREVS', {}).items():
-            if abbrev in kwargs:
-                kwargs[field] = kwargs.pop(abbrev)
-        return self._replace(**kwargs)
+from gnpy.core.utils import automatic_nch, lin2db
 
 
-class Power(namedtuple('Power', 'signal nonlinear_interference amplified_spontaneous_emission'), ConvenienceAccess):
-
-    _ABBREVS = {'nli': 'nonlinear_interference',
-                'ase': 'amplified_spontaneous_emission',}
+class Power(namedtuple('Power', 'signal nli ase')):
+    """carriers power in W"""
 
 
-class Channel(namedtuple('Channel', 'channel_number frequency baud_rate roll_off power'), ConvenienceAccess):
+class Channel(namedtuple('Channel', 'channel_number frequency baud_rate roll_off power chromatic_dispersion pmd')):
+    """ Class containing the parameters of a WDM signal.
 
-    _ABBREVS = {'channel':  'channel_number',
-                'num_chan': 'channel_number',
-                'ffs':      'frequency',
-                'freq':     'frequency',}
+        :param channel_number: channel number in the WDM grid
+        :param frequency: central frequency of the signal (Hz)
+        :param baud_rate: the symbol rate of the signal (Baud)
+        :param roll_off: the roll off of the signal. It is a pure number between 0 and 1
+        :param power (gnpy.core.info.Power): power of signal, ASE noise and NLI (W)
+        :param chromatic_dispersion: chromatic dispersion (s/m)
+        :param pmd: polarization mode dispersion (s)
+    """
 
-class Pref(namedtuple('Pref', 'p_span0, p_spani'), ConvenienceAccess):
 
-    _ABBREVS = {'p0' :  'p_span0',
-                'pi' :  'p_spani'}
+class Pref(namedtuple('Pref', 'p_span0, p_spani, neq_ch ')):
+    """noiseless reference power in dBm:
+    p_span0: inital target carrier power
+    p_spani: carrier power after element i
+    neq_ch: equivalent channel count in dB"""
 
-class SpectralInformation(namedtuple('SpectralInformation', 'pref carriers'), ConvenienceAccess):
 
-    def __new__(cls, pref=Pref(0, 0), *carriers):
+class SpectralInformation(namedtuple('SpectralInformation', 'pref carriers')):
+
+    def __new__(cls, pref, carriers):
         return super().__new__(cls, pref, carriers)
 
-def merge_input_spectral_information(*si):
-    """mix channel combs of different baud rates and power"""
-    #TODO
-    pass
 
 def create_input_spectral_information(f_min, f_max, roll_off, baud_rate, power, spacing):
     # pref in dB : convert power lin into power in dB
     pref = lin2db(power * 1e3)
-    si = SpectralInformation(pref=Pref(pref, pref))
     nb_channel = automatic_nch(f_min, f_max, spacing)
-    si = si.update(carriers=[
-            Channel(f, (f_min+spacing*f),
-            baud_rate, roll_off, Power(power, 0, 0)) for f in range(1,nb_channel+1)
-            ])
-    return si
-
-if __name__ == '__main__':
-    pref = lin2db(power * 1e3)
     si = SpectralInformation(
-        Pref(pref, pref),
-        Channel(1, 193.95e12, 32e9, 0.15,  # 193.95 THz, 32 Gbaud
-            Power(1e-3, 1e-6, 1e-6)),             # 1 mW, 1uW, 1uW
-        Channel(1, 195.95e12, 32e9, 0.15,  # 195.95 THz, 32 Gbaud
-            Power(1.2e-3, 1e-6, 1e-6)),           # 1.2 mW, 1uW, 1uW
+        pref=Pref(pref, pref, lin2db(nb_channel)),
+        carriers=[
+            Channel(f, (f_min + spacing * f),
+                    baud_rate, roll_off, Power(power, 0, 0), 0, 0) for f in range(1, nb_channel + 1)
+        ]
     )
-
-    si = SpectralInformation()
-    spacing = 0.05 # THz
-
-    si = si.update(carriers=tuple(Channel(f+1, 191.3+spacing*(f+1), 32e9, 0.15, Power(1e-3, f, 1)) for f in range(96)))
-
-    print(f'si = {si}')
-    print(f'si = {si.carriers[0].power.nli}')
-    print(f'si = {si.carriers[20].power.nli}')
-    si2 = si.update(carriers=tuple(c.update(power = c.power.update(nli = c.power.nli * 1e5))
-                              for c in si.carriers))
-    print(f'si2 = {si2}')
+    return si

gnpy/core/network.py

@@ -5,227 +5,199 @@
 gnpy.core.network
 =================
 
-This module contains functions for constructing networks of network elements.
+Working with networks which consist of network elements
 '''
 
-from gnpy.core.convert import convert_file
-from networkx import DiGraph
-from numpy import arange
-from scipy.interpolate import interp1d
-from logging import getLogger
-from os import path
-from operator import itemgetter
-from gnpy.core import elements
-from gnpy.core.elements import Fiber, Edfa, Transceiver, Roadm, Fused
-from gnpy.core.equipment import edfa_nf
-from gnpy.core.units import UNITS
-from gnpy.core.utils import load_json, save_json, round2float, db2lin, lin2db
-from sys import exit
+from operator import attrgetter
+from gnpy.core import ansi_escapes, elements
+from gnpy.core.exceptions import ConfigurationError, NetworkTopologyError
+from gnpy.core.utils import round2float, convert_length
 from collections import namedtuple
 
-logger = getLogger(__name__)
 
-def load_network(filename, equipment, name_matching = False):
-    json_filename = ''
-    if filename.suffix.lower() == '.xls':
-        logger.info('Automatically generating topology JSON file')
-        json_filename = convert_file(filename, name_matching)
-    elif filename.suffix.lower() == '.json':
-        json_filename = filename
-    else:
-        raise ValueError(f'unsuported topology filename extension {filename.suffix.lower()}')
-    json_data = load_json(json_filename)
-    return network_from_json(json_data, equipment)
-
-def save_network(filename, network):
-    filename_output = path.splitext(filename)[0] + '_auto_design.json'
-    json_data = network_to_json(network)
-    save_json(json_data, filename_output)
-
-def network_from_json(json_data, equipment):
-    # NOTE|dutc: we could use the following, but it would tie our data format
-    #            too closely to the graph library
-    # from networkx import node_link_graph
-    g = DiGraph()
-    for el_config in json_data['elements']:
-        typ = el_config.pop('type')
-        variety = el_config.pop('type_variety', 'default')
-        if typ in equipment and variety in equipment[typ]:
-            extra_params = equipment[typ][variety]
-            el_config.setdefault('params', {}).update(extra_params._asdict())
-        elif typ in ['Edfa', 'Fiber']: #catch it now because the code will crash later!
-            print( f'The {typ} of variety type {variety} was not recognized:'
-                    '\nplease check it is properly defined in the eqpt_config json file')
-            exit()
-        cls = getattr(elements, typ)
-        el = cls(**el_config)
-        g.add_node(el)
-
-    nodes = {k.uid: k for k in g.nodes()}
-
-    for cx in json_data['connections']:
-        from_node, to_node = cx['from_node'], cx['to_node']
-        try:
-            g.add_edge(nodes[from_node], nodes[to_node])
-        except KeyError:
-            msg = f'In {__name__} network_from_json function:\n\tcan not find {from_node} or {to_node} defined in {cx}'
-            print(msg)
-            exit(1)
-
-    return g
-
-def network_to_json(network):
-    data = {
-        'elements': [n.to_json for n in network]
+def edfa_nf(gain_target, variety_type, equipment):
+    amp_params = equipment['Edfa'][variety_type]
+    amp = elements.Edfa(
+        uid='calc_NF',
+        params=amp_params.__dict__,
+        operational={
+            'gain_target': gain_target,
+            'tilt_target': 0
         }
-    connections = {
-        'connections': [{"from_node": n.uid,
-                         "to_node": next_n.uid}
-                        for n in network
-                        for next_n in network.successors(n) if next_n is not None]
-        }
-    data.update(connections)
-    return data
+    )
+    amp.pin_db = 0
+    amp.nch = 88
+    return amp._calc_nf(True)
 
-def select_edfa(gain_target, power_target, equipment):
+
+def select_edfa(raman_allowed, gain_target, power_target, equipment, uid, restrictions=None):
     """amplifer selection algorithm
     @Orange Jean-Luc Augé
     """
-    Edfa_list = namedtuple('Edfa_list', 'variety power gain nf')
-    TARGET_EXTENDED_GAIN = 2.1
-    #MAX_EXTENDED_GAIN = 5
-    edfa_dict = equipment['Edfa']
+    Edfa_list = namedtuple('Edfa_list', 'variety power gain_min nf')
+    TARGET_EXTENDED_GAIN = equipment['Span']['default'].target_extended_gain
+
+    # for roadm restriction only: create a dict including not allowed for design amps
+    # because main use case is to have specific radm amp which are not allowed for ILA
+    # with the auto design
+    edfa_dict = {name: amp for (name, amp) in equipment['Edfa'].items()
+                 if restrictions is None or name in restrictions}
+
     pin = power_target - gain_target
 
-    edfa_list = [Edfa_list(
-                variety=edfa_variety,
-                power=min(
-                    pin
-                    +edfa.gain_flatmax
-                    +TARGET_EXTENDED_GAIN,
-                    edfa.p_max
-                    )
-                    -power_target,
-                gain=edfa.gain_flatmax-gain_target,
-                nf=edfa_nf(gain_target, edfa_variety, equipment)) \
-                for edfa_variety, edfa in edfa_dict.items()
-                if edfa.allowed_for_design]
+    # create 2 list of available amplifiers with relevant attributes for their selection
 
-    acceptable_gain_list = \
-    list(filter(lambda x : x.gain>-TARGET_EXTENDED_GAIN, edfa_list))
-    if len(acceptable_gain_list) < 1:
-        #no amplifier satisfies the required gain, so pick the highest gain:
-        gain_max = max(edfa_list, key=itemgetter(2)).gain
-        #pick up all amplifiers that share this max gain:
-        acceptable_gain_list = \
-        list(filter(lambda x : x.gain-gain_max>-0.1, edfa_list))
-    acceptable_power_list = \
-    list(filter(lambda x : x.power>=0, acceptable_gain_list))
+    # edfa list with:
+    # extended gain min allowance of 3dB: could be parametrized, but a bit complex
+    # extended gain max allowance TARGET_EXTENDED_GAIN is coming from eqpt_config.json
+    # power attribut include power AND gain limitations
+    edfa_list = [Edfa_list(
+        variety=edfa_variety,
+        power=min(
+            pin
+            + edfa.gain_flatmax
+            + TARGET_EXTENDED_GAIN,
+            edfa.p_max
+        )
+        - power_target,
+        gain_min=gain_target + 3
+        - edfa.gain_min,
+        nf=edfa_nf(gain_target, edfa_variety, equipment))
+        for edfa_variety, edfa in edfa_dict.items()
+        if ((edfa.allowed_for_design or restrictions is not None) and not edfa.raman)]
+
+    # consider a Raman list because of different gain_min requirement:
+    # do not allow extended gain min for Raman
+    raman_list = [Edfa_list(
+        variety=edfa_variety,
+        power=min(
+            pin
+            + edfa.gain_flatmax
+            + TARGET_EXTENDED_GAIN,
+            edfa.p_max
+        )
+        - power_target,
+        gain_min=gain_target
+        - edfa.gain_min,
+        nf=edfa_nf(gain_target, edfa_variety, equipment))
+        for edfa_variety, edfa in edfa_dict.items()
+        if (edfa.allowed_for_design and edfa.raman)] \
+        if raman_allowed else []
+
+    # merge raman and edfa lists
+    amp_list = edfa_list + raman_list
+
+    # filter on min gain limitation:
+    acceptable_gain_min_list = [x for x in amp_list if x.gain_min > 0]
+
+    if len(acceptable_gain_min_list) < 1:
+        # do not take this empty list into account for the rest of the code
+        # but issue a warning to the user and do not consider Raman
+        # Raman below min gain should not be allowed because i is meant to be a design requirement
+        # and raman padding at the amplifier input is impossible!
+
+        if len(edfa_list) < 1:
+            raise ConfigurationError(f'auto_design could not find any amplifier \
+                    to satisfy min gain requirement in node {uid} \
+                    please increase span fiber padding')
+        else:
+            # TODO: convert to logging
+            print(
+                f'{ansi_escapes.red}WARNING:{ansi_escapes.reset} target gain in node {uid} is below all available amplifiers min gain: \
+                  amplifier input padding will be assumed, consider increase span fiber padding instead'
+            )
+            acceptable_gain_min_list = edfa_list
+
+    # filter on gain+power limitation:
+    # this list checks both the gain and the power requirement
+    # because of the way .power is calculated in the list
+    acceptable_power_list = [x for x in acceptable_gain_min_list if x.power > 0]
     if len(acceptable_power_list) < 1:
-        #no amplifier satisfies the required power, so pick the highest power:
-        power_max = \
-        max(acceptable_gain_list, key=itemgetter(1)).power
-        #pick up all amplifiers that share this max gain:
-        acceptable_power_list = \
-        list(filter(lambda x : x.power-power_max>-0.1, acceptable_gain_list))
+        # no amplifier satisfies the required power, so pick the highest power(s):
+        power_max = max(acceptable_gain_min_list, key=attrgetter('power')).power
+        # check and pick if other amplifiers may have a similar gain/power
+        # allow a 0.3dB power range
+        # this allows to chose an amplifier with a better NF subsequentely
+        acceptable_power_list = [x for x in acceptable_gain_min_list
+                                 if x.power - power_max > -0.3]
+
     # gain and power requirements are resolved,
     #       =>chose the amp with the best NF among the acceptable ones:
-    return min(acceptable_power_list, key=itemgetter(3)).variety #filter on NF
+    selected_edfa = min(acceptable_power_list, key=attrgetter('nf'))  # filter on NF
+    # check what are the gain and power limitations of this amp
+    power_reduction = round(min(selected_edfa.power, 0), 2)
+    if power_reduction < -0.5:
+        print(
+            f'{ansi_escapes.red}WARNING:{ansi_escapes.reset} target gain and power in node {uid}\n \
+    is beyond all available amplifiers capabilities and/or extended_gain_range:\n\
+    a power reduction of {power_reduction} is applied\n'
+        )
+
+    return selected_edfa.variety, power_reduction
 
 
-def set_roadm_loss(network, equipment, pref_ch_db):
-    roadms = [roadm for roadm in network if isinstance(roadm, Roadm)]
-    power_mode = equipment['Spans']['default'].power_mode
-    default_roadm_loss = equipment['Roadms']['default'].gain_mode_default_loss
-    pout_target = equipment['Roadms']['default'].power_mode_pout_target
-    roadm_loss = pref_ch_db - pout_target
+def target_power(network, node, equipment):  # get_fiber_dp
+    if isinstance(node, elements.Roadm):
+        return 0
 
-    for roadm in roadms:
-        if power_mode:
-            roadm.loss = roadm_loss
-            roadm.target_pch_out_db = pout_target
-        elif roadm.loss == None:
-            roadm.loss = default_roadm_loss
-
-def target_power(dp_from_gain, network, node, equipment): #get_fiber_dp
     SPAN_LOSS_REF = 20
     POWER_SLOPE = 0.3
-    power_mode = equipment['Spans']['default'].power_mode
-    dp_range = list(equipment['Spans']['default'].delta_power_range_db)
+    dp_range = list(equipment['Span']['default'].delta_power_range_db)
     node_loss = span_loss(network, node)
 
-    dp_gain_mode = 0
     try:
-        dp_power_mode = round2float((node_loss - SPAN_LOSS_REF) * POWER_SLOPE, dp_range[2])
-        dp_power_mode = max(dp_range[0], dp_power_mode)
-        dp_power_mode = min(dp_range[1], dp_power_mode)
-    except KeyError:
-        print(f'invalid delta_power_range_db definition in eqpt_config[Spans]'
-              f'delta_power_range_db: [lower_bound, upper_bound, step]')
-        exit()
-
-    if dp_from_gain:
-        dp_power_mode = dp_from_gain
-        dp_gain_mode = dp_from_gain
-    if isinstance(node, Roadm):
-        dp_power_mode = 0
-
-    dp = dp_power_mode if power_mode else dp_gain_mode
-    #print(f'{repr(node)} delta power in:\n{dp}dB')
+        dp = round2float((node_loss - SPAN_LOSS_REF) * POWER_SLOPE, dp_range[2])
+        dp = max(dp_range[0], dp)
+        dp = min(dp_range[1], dp)
+    except IndexError:
+        raise ConfigurationError(f'invalid delta_power_range_db definition in eqpt_config[Span]'
+                                 f'delta_power_range_db: [lower_bound, upper_bound, step]')
 
     return dp
 
 
+_fiber_fused_types = (elements.Fused, elements.Fiber)
+
+
 def prev_node_generator(network, node):
     """fused spans interest:
-    iterate over all predecessors while they are Fused or Fiber type"""
+    iterate over all predecessors while they are either Fused or Fibers succeeded by Fused"""
     try:
-        prev_node = next(n for n in network.predecessors(node))
+        prev_node = next(network.predecessors(node))
     except StopIteration:
-        msg = f'In {__name__} prev_node_generator function:\n\t{node.uid} is not properly connected, please check network topology'
-        print(msg)
-        logger.critical(msg)
-        exit(1)
-    # yield and re-iterate
-    if isinstance(prev_node, Fused) or isinstance(node, Fused):
+        if isinstance(node, elements.Transceiver):
+            return
+        raise NetworkTopologyError(f'Node {node.uid} is not properly connected, please check network topology')
+    if ((isinstance(prev_node, elements.Fused) and isinstance(node, _fiber_fused_types)) or
+            (isinstance(prev_node, _fiber_fused_types) and isinstance(node, elements.Fused))):
         yield prev_node
         yield from prev_node_generator(network, prev_node)
-    else:
-        StopIteration
+
 
 def next_node_generator(network, node):
     """fused spans interest:
-    iterate over all successors while they are Fused or Fiber type"""
+    iterate over all predecessors while they are either Fused or Fibers preceded by Fused"""
     try:
-        next_node = next(n for n in network.successors(node))
+        next_node = next(network.successors(node))
     except StopIteration:
-        print(f'In {__name__} next_node_generator function:\n\t{node.uid}  is not properly connected, please check network topology')
-        exit(1)        
-    # yield and re-iterate
-    if isinstance(next_node, Fused) or isinstance(node, Fused):
+        if isinstance(node, elements.Transceiver):
+            return
+        raise NetworkTopologyError(f'Node {node.uid} is not properly connected, please check network topology')
+
+    if ((isinstance(next_node, elements.Fused) and isinstance(node, _fiber_fused_types)) or
+            (isinstance(next_node, _fiber_fused_types) and isinstance(node, elements.Fused))):
         yield next_node
         yield from next_node_generator(network, next_node)
-    else:
-        StopIteration
+
 
 def span_loss(network, node):
-    """Fused span interest:
-    return the total span loss of all the fibers spliced by a Fused node"""
+    """Total loss of a span (Fiber and Fused nodes) which contains the given node"""
     loss = node.loss if node.passive else 0
-    try:
-        prev_node = next(n for n in network.predecessors(node))
-        if isinstance(prev_node, Fused):
-            loss += sum(n.loss for n in prev_node_generator(network, node))
-    except StopIteration:
-        pass
-    try:
-        next_node = next(n for n in network.successors(node))
-        if isinstance(next_node, Fused):
-            loss += sum(n.loss for n in next_node_generator(network, node))
-    except StopIteration:
-        pass
+    loss += sum(n.loss for n in prev_node_generator(network, node))
+    loss += sum(n.loss for n in next_node_generator(network, node))
     return loss
 
+
 def find_first_node(network, node):
     """Fused node interest:
     returns the 1st node at the origin of a succession of fused nodes
@@ -235,6 +207,7 @@ def find_first_node(network, node):
         pass
     return this_node
 
+
 def find_last_node(network, node):
     """Fused node interest:
     returns the last node in a succession of fused nodes
@@ -244,115 +217,223 @@ def find_last_node(network, node):
         pass
     return this_node
 
-def set_amplifier_voa(amp, pref_total_db, power_mode):
-    VOA_MARGIN = 0
-    if amp.operational.out_voa is None:
-        if power_mode:
-            gain_target = amp.operational.gain_target
-            pout = pref_total_db + amp.dp_db
-            voa = min(amp.params.p_max-pout,
-                      amp.params.gain_flatmax-amp.operational.gain_target)
-            voa = round2float(max(voa, 0), 0.5) - VOA_MARGIN if amp.params.out_voa_auto else 0
-            amp.dp_db = amp.dp_db + voa
-            amp.operational.gain_target = amp.operational.gain_target + voa
-        else:
-            voa = 0 # no output voa optimization in gain mode
-        amp.operational.out_voa = voa
 
-def set_egress_amplifier(network, roadm, equipment, pref_total_db):
-    power_mode = equipment['Spans']['default'].power_mode
-    next_oms = (n for n in network.successors(roadm) if not isinstance(n, Transceiver))
+def set_amplifier_voa(amp, power_target, power_mode):
+    VOA_MARGIN = 1  # do not maximize the VOA optimization
+    if amp.out_voa is None:
+        if power_mode and amp.params.out_voa_auto:
+            voa = min(amp.params.p_max - power_target,
+                      amp.params.gain_flatmax - amp.effective_gain)
+            voa = max(round2float(voa, 0.5) - VOA_MARGIN, 0)
+            amp.delta_p = amp.delta_p + voa
+            amp.effective_gain = amp.effective_gain + voa
+        else:
+            voa = 0  # no output voa optimization in gain mode
+        amp.out_voa = voa
+
+
+def set_egress_amplifier(network, this_node, equipment, pref_ch_db, pref_total_db):
+    """ this node can be a transceiver or a ROADM (same function called in both cases)
+    """
+    power_mode = equipment['Span']['default'].power_mode
+    next_oms = (n for n in network.successors(this_node) if not isinstance(n, elements.Transceiver))
+    this_node_degree = {k: v for k, v in this_node.per_degree_pch_out_db.items()} if hasattr(this_node, 'per_degree_pch_out_db') else {}
     for oms in next_oms:
-        #go through all the OMS departing from the Roadm
-        node = roadm
-        prev_node = roadm
-        next_node = oms
-        # if isinstance(next_node, Fused): #support ROADM wo egress amp for metro applications
+        # go through all the OMS departing from the ROADM
+        prev_node = this_node
+        node = oms
+        # if isinstance(next_node, elements.Fused): #support ROADM wo egress amp for metro applications
         #     node = find_last_node(next_node)
         #     next_node = next(n for n in network.successors(node))
         #     next_node = find_last_node(next_node)
-        prev_dp = 0
-        dp = 0
-        while True:
-        #go through all nodes in the OMS (loop until next Roadm instance)
-            if isinstance(node, Edfa):
+        if node.uid not in this_node_degree:
+            # if no target power is defined on this degree or no per degree target power is given use the global one
+            # if target_pch_out_db  is not an attribute, then the element must be a transceiver
+            this_node_degree[node.uid] = getattr(this_node.params, 'target_pch_out_db', 0)
+        # use the target power on this degree
+        prev_dp = this_node_degree[node.uid] - pref_ch_db
+        dp = prev_dp
+        prev_voa = 0
+        voa = 0
+        visited_nodes = []
+        while not (isinstance(node, elements.Roadm) or isinstance(node, elements.Transceiver)):
+            # go through all nodes in the OMS (loop until next Roadm instance)
+            try:
+                next_node = next(network.successors(node))
+            except StopIteration:
+                raise NetworkTopologyError(f'{type(node).__name__} {node.uid} is not properly connected, please check network topology')
+            visited_nodes.append(node)
+            if next_node in visited_nodes:
+                raise NetworkTopologyError(f'Loop detected for {type(node).__name__} {node.uid}, please check network topology')
+            if isinstance(node, elements.Edfa):
                 node_loss = span_loss(network, prev_node)
-                dp_from_gain = prev_dp + node.operational.gain_target - node_loss \
-                    if node.operational.gain_target > 0 else None
-                dp = target_power(dp_from_gain, network, next_node, equipment)
-                gain_target = node_loss + dp - prev_dp
+                voa = node.out_voa if node.out_voa else 0
+                if node.delta_p is None:
+                    dp = target_power(network, next_node, equipment)
+                else:
+                    dp = node.delta_p
+                if node.effective_gain is None or power_mode:
+                    gain_target = node_loss + dp - prev_dp + prev_voa
+                else:  # gain mode with effective_gain
+                    gain_target = node.effective_gain
+                    dp = prev_dp - node_loss - prev_voa + gain_target
 
-                if power_mode:
-                    node.dp_db = dp
-                node.operational.gain_target = gain_target
+                power_target = pref_total_db + dp
+
+                if isinstance(prev_node, elements.Fiber):
+                    max_fiber_lineic_loss_for_raman = \
+                        equipment['Span']['default'].max_fiber_lineic_loss_for_raman
+                    raman_allowed = prev_node.params.loss_coef < max_fiber_lineic_loss_for_raman
+                else:
+                    raman_allowed = False
 
                 if node.params.type_variety == '':
-                    power_target = pref_total_db + dp
-                    edfa_variety = select_edfa(gain_target, power_target, equipment)
+                    if node.variety_list and isinstance(node.variety_list, list):
+                        restrictions = node.variety_list
+                    elif isinstance(prev_node, elements.Roadm) and prev_node.restrictions['booster_variety_list']:
+                        # implementation of restrictions on roadm boosters
+                        restrictions = prev_node.restrictions['booster_variety_list']
+                    elif isinstance(next_node, elements.Roadm) and next_node.restrictions['preamp_variety_list']:
+                        # implementation of restrictions on roadm preamp
+                        restrictions = next_node.restrictions['preamp_variety_list']
+                    else:
+                        restrictions = None
+                    edfa_variety, power_reduction = select_edfa(raman_allowed, gain_target, power_target, equipment, node.uid, restrictions)
                     extra_params = equipment['Edfa'][edfa_variety]
-                    node.params.update_params(extra_params._asdict())
-                set_amplifier_voa(node, pref_total_db, power_mode)
-            if isinstance(next_node, Roadm) or isinstance(next_node, Transceiver):
-                break
+                    node.params.update_params(extra_params.__dict__)
+                    dp += power_reduction
+                    gain_target += power_reduction
+                elif node.params.raman and not raman_allowed:
+                    print(f'{ansi_escapes.red}WARNING{ansi_escapes.reset}: raman is used in node {node.uid}\n but fiber lineic loss is above threshold\n')
+                else:
+                    # if variety is imposed by user, and if the gain_target (computed or imposed) is also above
+                    # variety max gain + extended range, then warn that gain > max_gain + extended range
+                    if gain_target - equipment['Edfa'][node.params.type_variety].gain_flatmax - \
+                            equipment['Span']['default'].target_extended_gain > 1e-2:
+                        # 1e-2 to allow a small margin according to round2float min step
+                        print(f'{ansi_escapes.red}WARNING{ansi_escapes.reset}: '
+                              f'WARNING: effective gain in Node {node.uid} is above user '
+                              f'specified amplifier {node.params.type_variety}\n'
+                              f'max flat gain: {equipment["Edfa"][node.params.type_variety].gain_flatmax}dB ; '
+                              f'required gain: {gain_target}dB. Please check amplifier type.')
+
+                node.delta_p = dp if power_mode else None
+                node.effective_gain = gain_target
+                set_amplifier_voa(node, power_target, power_mode)
+
             prev_dp = dp
+            prev_voa = voa
             prev_node = node
             node = next_node
             # print(f'{node.uid}')
-            next_node = next(n for n in network.successors(node))
+
+    if isinstance(this_node, elements.Roadm):
+        this_node.per_degree_pch_out_db = {k: v for k, v in this_node_degree.items()}
 
 
-def add_egress_amplifier(network, node):
-    next_nodes = [n for n in network.successors(node)
-        if not (isinstance(n, Transceiver) or isinstance(n, Fused) or isinstance(n, Edfa))]
-        #no amplification for fused spans or TRX
-    for i, next_node in enumerate(next_nodes):
-        network.remove_edge(node, next_node)
-        amp = Edfa(
-                    uid = f'Edfa{i}_{node.uid}',
-                    params = {},
-                    metadata = {
-                        'location': {
-                            'latitude':  (node.lat * 2 + next_node.lat * 2) / 4,
-                            'longitude': (node.lng * 2 + next_node.lng * 2) / 4,
-                            'city':      node.loc.city,
-                            'region':    node.loc.region,
-                        }
-                    },
-                    operational = {
-                        'gain_target': 0,
-                        'tilt_target': 0,
-                    })
+def add_roadm_booster(network, roadm):
+    next_nodes = [n for n in network.successors(roadm)
+                  if not (isinstance(n, elements.Transceiver) or isinstance(n, elements.Fused) or isinstance(n, elements.Edfa))]
+    # no amplification for fused spans or TRX
+    for next_node in next_nodes:
+        network.remove_edge(roadm, next_node)
+        amp = elements.Edfa(
+            uid=f'Edfa_booster_{roadm.uid}_to_{next_node.uid}',
+            params={},
+            metadata={
+                'location': {
+                    'latitude': roadm.lat,
+                    'longitude': roadm.lng,
+                    'city': roadm.loc.city,
+                    'region': roadm.loc.region,
+                }
+            },
+            operational={
+                'gain_target': None,
+                'tilt_target': 0,
+            })
         network.add_node(amp)
-        network.add_edge(node, amp)
-        network.add_edge(amp, next_node)
+        network.add_edge(roadm, amp, weight=0.01)
+        network.add_edge(amp, next_node, weight=0.01)
+
+
+def add_roadm_preamp(network, roadm):
+    prev_nodes = [n for n in network.predecessors(roadm)
+                  if not (isinstance(n, elements.Transceiver) or isinstance(n, elements.Fused) or isinstance(n, elements.Edfa))]
+    # no amplification for fused spans or TRX
+    for prev_node in prev_nodes:
+        network.remove_edge(prev_node, roadm)
+        amp = elements.Edfa(
+            uid=f'Edfa_preamp_{roadm.uid}_from_{prev_node.uid}',
+            params={},
+            metadata={
+                'location': {
+                    'latitude': roadm.lat,
+                    'longitude': roadm.lng,
+                    'city': roadm.loc.city,
+                    'region': roadm.loc.region,
+                }
+            },
+            operational={
+                'gain_target': None,
+                'tilt_target': 0,
+            })
+        network.add_node(amp)
+        if isinstance(prev_node, elements.Fiber):
+            edgeweight = prev_node.params.length
+        else:
+            edgeweight = 0.01
+        network.add_edge(prev_node, amp, weight=edgeweight)
+        network.add_edge(amp, roadm, weight=0.01)
+
+
+def add_inline_amplifier(network, fiber):
+    next_node = next(network.successors(fiber))
+    if isinstance(next_node, elements.Fiber) or isinstance(next_node, elements.RamanFiber):
+        # no amplification for fused spans or TRX
+        network.remove_edge(fiber, next_node)
+        amp = elements.Edfa(
+            uid=f'Edfa_{fiber.uid}',
+            params={},
+            metadata={
+                'location': {
+                    'latitude': (fiber.lat + next_node.lat) / 2,
+                    'longitude': (fiber.lng + next_node.lng) / 2,
+                    'city': fiber.loc.city,
+                    'region': fiber.loc.region,
+                }
+            },
+            operational={
+                'gain_target': None,
+                'tilt_target': 0,
+            })
+        network.add_node(amp)
+        network.add_edge(fiber, amp, weight=fiber.params.length)
+        network.add_edge(amp, next_node, weight=0.01)
 
 
 def calculate_new_length(fiber_length, bounds, target_length):
     if fiber_length < bounds.stop:
         return fiber_length, 1
 
-    n_spans = int(fiber_length // target_length)
+    n_spans2 = int(fiber_length // target_length)
+    n_spans1 = n_spans2 + 1
 
-    length1 = fiber_length / (n_spans+1)
-    delta1 = target_length-length1
-    result1 = (length1, n_spans+1)
+    length1 = fiber_length / n_spans1
+    length2 = fiber_length / n_spans2
 
-    length2 = fiber_length / n_spans
-    delta2 = length2-target_length
-    result2 = (length2, n_spans)
-
-    if (bounds.start<=length1<=bounds.stop) and not(bounds.start<=length2<=bounds.stop):
-        result = result1
-    elif (bounds.start<=length2<=bounds.stop) and not(bounds.start<=length1<=bounds.stop):
-        result = result2
+    if (bounds.start <= length1 <= bounds.stop) and not(bounds.start <= length2 <= bounds.stop):
+        return (length1, n_spans1)
+    elif (bounds.start <= length2 <= bounds.stop) and not(bounds.start <= length1 <= bounds.stop):
+        return (length2, n_spans2)
+    elif target_length - length1 < length2 - target_length:
+        return (length1, n_spans1)
     else:
-        result = result1 if delta1 < delta2 else result2
-
-    return result
+        return (length2, n_spans2)
 
 
 def split_fiber(network, fiber, bounds, target_length, equipment):
-    new_length, n_spans = calculate_new_length(fiber.length, bounds, target_length)
+    new_length, n_spans = calculate_new_length(fiber.params.length, bounds, target_length)
     if n_spans == 1:
         return
 
@@ -360,98 +441,106 @@ def split_fiber(network, fiber, bounds, target_length, equipment):
         next_node = next(network.successors(fiber))
         prev_node = next(network.predecessors(fiber))
     except StopIteration:
-
-        print(f'In {__name__} split_fiber function:\n\t{fiber.uid}   is not properly connected, please check network topology')
-        exit()
+        raise NetworkTopologyError(f'Fiber {fiber.uid} is not properly connected, please check network topology')
 
     network.remove_node(fiber)
 
-    fiber_params = fiber.params._asdict()
-    fiber_params['length'] = new_length / UNITS[fiber.params.length_units]
-    fiber_params['con_in'] = fiber.con_in
-    fiber_params['con_out'] = fiber.con_out
+    fiber.params.length = new_length
 
-    f = interp1d([prev_node.lng, next_node.lng], [prev_node.lat, next_node.lat])
-    xpos = [prev_node.lng + (next_node.lng - prev_node.lng) * (n+1)/(n_spans+1) for n in range(n_spans)]
-    ypos = f(xpos)
+    xpos = [prev_node.lng + (next_node.lng - prev_node.lng) * (n + 0.5) / n_spans for n in range(n_spans)]
+    ypos = [prev_node.lat + (next_node.lat - prev_node.lat) * (n + 0.5) / n_spans for n in range(n_spans)]
     for span, lng, lat in zip(range(n_spans), xpos, ypos):
-        new_span = Fiber(uid = f'{fiber.uid}_({span+1}/{n_spans})',
-                          metadata = {
-                            'location': {
-                                'latitude':  lat,
-                                'longitude': lng,
-                                'city':      fiber.loc.city,
-                                'region':    fiber.loc.region,
-                            }
-                          },
-                          params = fiber_params)
-        network.add_edge(prev_node, new_span)
-        prev_node = new_span
-    network.add_edge(prev_node, next_node)
-
-def add_connector_loss(fibers, con_in, con_out, EOL):
-    for fiber in fibers:
-        if fiber.con_in is None: fiber.con_in = con_in
-        if fiber.con_out is None:
-            fiber.con_out = con_out #con_out includes EOL
+        new_span = elements.Fiber(uid=f'{fiber.uid}_({span+1}/{n_spans})',
+                         type_variety=fiber.type_variety,
+                         metadata={
+                              'location': {
+                                  'latitude': lat,
+                                  'longitude': lng,
+                                  'city': fiber.loc.city,
+                                  'region': fiber.loc.region,
+                              }
+                         },
+                         params=fiber.params.asdict())
+        if isinstance(prev_node, elements.Fiber):
+            edgeweight = prev_node.params.length
         else:
-            fiber.con_out = fiber.con_out+EOL
+            edgeweight = 0.01
+        network.add_edge(prev_node, new_span, weight=edgeweight)
+        prev_node = new_span
+    if isinstance(prev_node, elements.Fiber):
+        edgeweight = prev_node.params.length
+    else:
+        edgeweight = 0.01
+    network.add_edge(prev_node, next_node, weight=edgeweight)
 
-def add_fiber_padding(network, fibers, padding):
-    """last_fibers = (fiber for n in network.nodes()
-                         if not (isinstance(n, Fiber) or isinstance(n, Fused))
-                         for fiber in network.predecessors(n)
-                         if isinstance(fiber, Fiber))"""
+
+def add_connector_loss(network, fibers, default_con_in, default_con_out, EOL):
     for fiber in fibers:
-        this_span_loss = span_loss(network, fiber)
         try:
             next_node = next(network.successors(fiber))
         except StopIteration:
-            msg = f'In {__name__} add_fiber_padding function:\n\t{fiber.uid}   is not properly connected, please check network topology'
-            print(msg)
-            logger.critical(msg)
-            exit(1)            
-        if this_span_loss < padding and not (isinstance(next_node, Fused)):
-            #add a padding att_in at the input of the 1st fiber:
-            #address the case when several fibers are spliced together
+            raise NetworkTopologyError(f'Fiber {fiber.uid} is not properly connected, please check network topology')
+        if fiber.params.con_in is None:
+            fiber.params.con_in = default_con_in
+        if fiber.params.con_out is None:
+            fiber.params.con_out = default_con_out
+        if not isinstance(next_node, elements.Fused):
+            fiber.params.con_out += EOL
+
+
+def add_fiber_padding(network, fibers, padding):
+    """last_fibers = (fiber for n in network.nodes()
+                         if not (isinstance(n, elements.Fiber) or isinstance(n, elements.Fused))
+                         for fiber in network.predecessors(n)
+                         if isinstance(fiber, elements.Fiber))"""
+    for fiber in fibers:
+        try:
+            next_node = next(network.successors(fiber))
+        except StopIteration:
+            raise NetworkTopologyError(f'Fiber {fiber.uid} is not properly connected, please check network topology')
+        if isinstance(next_node, elements.Fused):
+            continue
+        this_span_loss = span_loss(network, fiber)
+        if this_span_loss < padding:
+            # add a padding att_in at the input of the 1st fiber:
+            # address the case when several fibers are spliced together
             first_fiber = find_first_node(network, fiber)
-            if first_fiber.att_in is None:
-                first_fiber.att_in = padding - this_span_loss
-            else :
-                first_fiber.att_in = first_fiber.att_in + padding - this_span_loss
+            # in order to support no booster , fused might be placed
+            # just after a roadm: need to check that first_fiber is really a fiber
+            if isinstance(first_fiber, elements.Fiber):
+                first_fiber.params.att_in = first_fiber.params.att_in + padding - this_span_loss
+
 
 def build_network(network, equipment, pref_ch_db, pref_total_db):
-    default_span_data = equipment['Spans']['default']
-    max_length = int(default_span_data.max_length * UNITS[default_span_data.length_units])
-    min_length = max(int(default_span_data.padding/0.2*1e3),50_000)
+    default_span_data = equipment['Span']['default']
+    max_length = int(convert_length(default_span_data.max_length, default_span_data.length_units))
+    min_length = max(int(default_span_data.padding / 0.2 * 1e3), 50_000)
     bounds = range(min_length, max_length)
     target_length = max(min_length, 90_000)
-    con_in = default_span_data.con_in
-    con_out = default_span_data.con_out + default_span_data.EOL
-    padding = default_span_data.padding
 
-    #set raodm loss for gain_mode before to build network
-    set_roadm_loss(network, equipment, pref_ch_db)
-    fibers = [f for f in network.nodes() if isinstance(f, Fiber)]
-    add_connector_loss(fibers, con_in, con_out, default_span_data.EOL)
-    add_fiber_padding(network, fibers, padding)
+    # set roadm loss for gain_mode before to build network
+    fibers = [f for f in network.nodes() if isinstance(f, elements.Fiber)]
+    add_connector_loss(network, fibers, default_span_data.con_in, default_span_data.con_out, default_span_data.EOL)
+    add_fiber_padding(network, fibers, default_span_data.padding)
     # don't group split fiber and add amp in the same loop
     # =>for code clarity (at the expense of speed):
     for fiber in fibers:
         split_fiber(network, fiber, bounds, target_length, equipment)
 
-    amplified_nodes = [n for n in network.nodes()
-                        if isinstance(n, Fiber) or isinstance(n, Roadm)]
-    for node in amplified_nodes:
-        add_egress_amplifier(network, node)
-
-    roadms = [r for r in network.nodes() if isinstance(r, Roadm)]
+    roadms = [r for r in network.nodes() if isinstance(r, elements.Roadm)]
     for roadm in roadms:
-        set_egress_amplifier(network, roadm, equipment, pref_total_db)
+        add_roadm_preamp(network, roadm)
+        add_roadm_booster(network, roadm)
 
-    #support older json input topology wo Roadms:
-    if len(roadms) == 0:
-        trx = [t for t in network.nodes() if isinstance(t, Transceiver)]
-        for t in trx:
-            set_egress_amplifier(network, t, equipment, pref_total_db)
+    fibers = [f for f in network.nodes() if isinstance(f, elements.Fiber)]
+    for fiber in fibers:
+        add_inline_amplifier(network, fiber)
 
+    for roadm in roadms:
+        set_egress_amplifier(network, roadm, equipment, pref_ch_db, pref_total_db)
+
+    trx = [t for t in network.nodes() if isinstance(t, elements.Transceiver)]
+    for t in trx:
+        next_node = next(network.successors(t), None)
+        if next_node and not isinstance(next_node, elements.Roadm):
+            set_egress_amplifier(network, t, equipment, 0, pref_total_db)

gnpy/core/node.py

@@ -1,54 +0,0 @@
-#! /bin/usr/python3
-# -*- coding: utf-8 -*-
-
-'''
-gnpy.core.node
-==============
-
-This module contains the base class for a network element.
-
-Strictly, a network element is any callable which accepts an immutable
-.info.SpectralInformation object and returns a .info.SpectralInformation object
-(a copy.)
-
-Network elements MUST implement two attributes .uid and .name representing a
-unique identifier and a printable name.
-
-This base class provides a mode convenient way to define a network element
-via subclassing.
-'''
-
-from uuid import uuid4
-from collections import namedtuple
-
-class Location(namedtuple('Location', 'latitude longitude city region')):
-    def __new__(cls, latitude=0, longitude=0, city=None, region=None):
-        return super().__new__(cls, latitude, longitude, city, region)
-
-class Node:
-    def __init__(self, uid, name=None, params=None, metadata={'location':{}}, operational=None):
-        if name is None:
-            name = uid
-        self.uid, self.name = uid, name
-        if metadata and not isinstance(metadata.get('location'), Location):
-            metadata['location'] = Location(**metadata.pop('location', {}))
-        self.params, self.metadata, self.operational = params, metadata, operational
-
-    @property
-    def coords(self):
-        return self.lng, self.lat
-
-    @property
-    def location(self):
-        return self.metadata['location']
-    loc = location
-
-    @property
-    def longitude(self):
-        return self.location.longitude
-    lng = longitude
-
-    @property
-    def latitude(self):
-        return self.location.latitude
-    lat = latitude

gnpy/core/parameters.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.core.parameters
+====================
+
+This module contains all parameters to configure standard network elements.
+"""
+
+from scipy.constants import c, pi
+from numpy import squeeze, log10, exp
+
+from gnpy.core.utils import db2lin, convert_length
+from gnpy.core.exceptions import ParametersError
+
+
+class Parameters:
+    def asdict(self):
+        class_dict = self.__class__.__dict__
+        instance_dict = self.__dict__
+        new_dict = {}
+        for key in class_dict:
+            if isinstance(class_dict[key], property):
+                new_dict[key] = instance_dict['_' + key]
+        return new_dict
+
+
+class PumpParams(Parameters):
+    def __init__(self, power, frequency, propagation_direction):
+        self._power = power
+        self._frequency = frequency
+        self._propagation_direction = propagation_direction
+
+    @property
+    def power(self):
+        return self._power
+
+    @property
+    def frequency(self):
+        return self._frequency
+
+    @property
+    def propagation_direction(self):
+        return self._propagation_direction
+
+
+class RamanParams(Parameters):
+    def __init__(self, **kwargs):
+        self._flag_raman = kwargs['flag_raman']
+        self._space_resolution = kwargs['space_resolution'] if 'space_resolution' in kwargs else None
+        self._tolerance = kwargs['tolerance'] if 'tolerance' in kwargs else None
+
+    @property
+    def flag_raman(self):
+        return self._flag_raman
+
+    @property
+    def space_resolution(self):
+        return self._space_resolution
+
+    @property
+    def tolerance(self):
+        return self._tolerance
+
+
+class NLIParams(Parameters):
+    def __init__(self, **kwargs):
+        self._nli_method_name = kwargs['nli_method_name']
+        self._wdm_grid_size = kwargs['wdm_grid_size']
+        self._dispersion_tolerance = kwargs['dispersion_tolerance']
+        self._phase_shift_tolerance = kwargs['phase_shift_tolerance']
+        self._f_cut_resolution = None
+        self._f_pump_resolution = None
+        self._computed_channels = kwargs['computed_channels'] if 'computed_channels' in kwargs else None
+
+    @property
+    def nli_method_name(self):
+        return self._nli_method_name
+
+    @property
+    def wdm_grid_size(self):
+        return self._wdm_grid_size
+
+    @property
+    def dispersion_tolerance(self):
+        return self._dispersion_tolerance
+
+    @property
+    def phase_shift_tolerance(self):
+        return self._phase_shift_tolerance
+
+    @property
+    def f_cut_resolution(self):
+        return self._f_cut_resolution
+
+    @f_cut_resolution.setter
+    def f_cut_resolution(self, f_cut_resolution):
+        self._f_cut_resolution = f_cut_resolution
+
+    @property
+    def f_pump_resolution(self):
+        return self._f_pump_resolution
+
+    @f_pump_resolution.setter
+    def f_pump_resolution(self, f_pump_resolution):
+        self._f_pump_resolution = f_pump_resolution
+
+    @property
+    def computed_channels(self):
+        return self._computed_channels
+
+
+class SimParams(Parameters):
+    def __init__(self, **kwargs):
+        try:
+            if 'nli_parameters' in kwargs:
+                self._nli_params = NLIParams(**kwargs['nli_parameters'])
+            else:
+                self._nli_params = None
+            if 'raman_parameters' in kwargs:
+                self._raman_params = RamanParams(**kwargs['raman_parameters'])
+            else:
+                self._raman_params = None
+        except KeyError as e:
+            raise ParametersError(f'Simulation parameters must include {e}. Configuration: {kwargs}')
+
+    @property
+    def nli_params(self):
+        return self._nli_params
+
+    @property
+    def raman_params(self):
+        return self._raman_params
+
+
+class FiberParams(Parameters):
+    def __init__(self, **kwargs):
+        try:
+            self._length = convert_length(kwargs['length'], kwargs['length_units'])
+            # fixed attenuator for padding
+            self._att_in = kwargs['att_in'] if 'att_in' in kwargs else 0
+            # if not defined in the network json connector loss in/out
+            # the None value will be updated in network.py[build_network]
+            # with default values from eqpt_config.json[Spans]
+            self._con_in = kwargs['con_in'] if 'con_in' in kwargs else None
+            self._con_out = kwargs['con_out'] if 'con_out' in kwargs else None
+            if 'ref_wavelength' in kwargs:
+                self._ref_wavelength = kwargs['ref_wavelength']
+                self._ref_frequency = c / self.ref_wavelength
+            elif 'ref_frequency' in kwargs:
+                self._ref_frequency = kwargs['ref_frequency']
+                self._ref_wavelength = c / self.ref_frequency
+            else:
+                self._ref_wavelength = 1550e-9
+                self._ref_frequency = c / self.ref_wavelength
+            self._dispersion = kwargs['dispersion']  # s/m/m
+            self._dispersion_slope = kwargs['dispersion_slope'] if 'dispersion_slope' in kwargs else \
+                -2 * self._dispersion/self.ref_wavelength  # s/m/m/m
+            self._beta2 = -(self.ref_wavelength ** 2) * self.dispersion / (2 * pi * c)  # 1/(m * Hz^2)
+            # Eq. (3.23) in  Abramczyk, Halina. "Dispersion phenomena in optical fibers." Virtual European University
+            # on Lasers. Available online: http://mitr.p.lodz.pl/evu/lectures/Abramczyk3.pdf
+            # (accessed on 25 March 2018) (2005).
+            self._beta3 = ((self.dispersion_slope - (4*pi*c/self.ref_wavelength**3) * self.beta2) /
+                           (2*pi*c/self.ref_wavelength**2)**2)
+            self._gamma = kwargs['gamma']  # 1/W/m
+            self._pmd_coef = kwargs['pmd_coef']  # s/sqrt(m)
+            if type(kwargs['loss_coef']) == dict:
+                self._loss_coef = squeeze(kwargs['loss_coef']['loss_coef_power']) * 1e-3  # lineic loss dB/m
+                self._f_loss_ref = squeeze(kwargs['loss_coef']['frequency'])  # Hz
+            else:
+                self._loss_coef = kwargs['loss_coef'] * 1e-3  # lineic loss dB/m
+                self._f_loss_ref = 193.5e12  # Hz
+            self._lin_attenuation = db2lin(self.length * self.loss_coef)
+            self._lin_loss_exp = self.loss_coef / (10 * log10(exp(1)))  # linear power exponent loss Neper/m
+            self._effective_length = (1 - exp(- self.lin_loss_exp * self.length)) / self.lin_loss_exp
+            self._asymptotic_length = 1 / self.lin_loss_exp
+            # raman parameters (not compulsory)
+            self._raman_efficiency = kwargs['raman_efficiency'] if 'raman_efficiency' in kwargs else None
+            self._pumps_loss_coef = kwargs['pumps_loss_coef'] if 'pumps_loss_coef' in kwargs else None
+        except KeyError as e:
+            raise ParametersError(f'Fiber configurations json must include {e}. Configuration: {kwargs}')
+
+    @property
+    def length(self):
+        return self._length
+
+    @length.setter
+    def length(self, length):
+        """length must be in m"""
+        self._length = length
+
+    @property
+    def att_in(self):
+        return self._att_in
+
+    @att_in.setter
+    def att_in(self, att_in):
+        self._att_in = att_in
+
+    @property
+    def con_in(self):
+        return self._con_in
+
+    @con_in.setter
+    def con_in(self, con_in):
+        self._con_in = con_in
+
+    @property
+    def con_out(self):
+        return self._con_out
+
+    @con_out.setter
+    def con_out(self, con_out):
+        self._con_out = con_out
+
+    @property
+    def dispersion(self):
+        return self._dispersion
+
+    @property
+    def dispersion_slope(self):
+        return self._dispersion_slope
+
+    @property
+    def gamma(self):
+        return self._gamma
+
+    @property
+    def pmd_coef(self):
+        return self._pmd_coef
+
+    @property
+    def ref_wavelength(self):
+        return self._ref_wavelength
+
+    @property
+    def ref_frequency(self):
+        return self._ref_frequency
+
+    @property
+    def beta2(self):
+        return self._beta2
+
+    @property
+    def beta3(self):
+        return self._beta3
+
+    @property
+    def loss_coef(self):
+        return self._loss_coef
+
+    @property
+    def f_loss_ref(self):
+        return self._f_loss_ref
+
+    @property
+    def lin_loss_exp(self):
+        return self._lin_loss_exp
+
+    @property
+    def lin_attenuation(self):
+        return self._lin_attenuation
+
+    @property
+    def effective_length(self):
+        return self._effective_length
+
+    @property
+    def asymptotic_length(self):
+        return self._asymptotic_length
+
+    @property
+    def raman_efficiency(self):
+        return self._raman_efficiency
+
+    @property
+    def pumps_loss_coef(self):
+        return self._pumps_loss_coef
+
+    def asdict(self):
+        dictionary = super().asdict()
+        dictionary['loss_coef'] = self.loss_coef * 1e3
+        dictionary['length_units'] = 'm'
+        return dictionary

gnpy/core/request.py

@@ -1,923 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-gnpy.core.request
-=================
-
-This module contains path request functionality.
-
-This functionality allows the user to provide a JSON request
-file in accordance with a Yang model for requesting path
-computations and returns path results in terms of path
-and feasibility
-
-See: draft-ietf-teas-yang-path-computation-01.txt
-"""
-
-from sys import exit
-from collections import namedtuple
-from logging import getLogger, basicConfig, CRITICAL, DEBUG, INFO
-from networkx import (dijkstra_path, NetworkXNoPath, all_simple_paths)
-from networkx.utils import pairwise 
-from numpy import mean
-from gnpy.core.service_sheet import convert_service_sheet, Request_element, Element
-from gnpy.core.elements import Transceiver, Roadm, Edfa, Fused
-from gnpy.core.network import set_roadm_loss
-from gnpy.core.utils import db2lin, lin2db
-from gnpy.core.info import create_input_spectral_information, SpectralInformation, Channel, Power
-from copy import copy, deepcopy
-from csv import writer
-from math import ceil
-
-logger = getLogger(__name__)
-
-
-RequestParams = namedtuple('RequestParams','request_id source destination trx_type'+
-' trx_mode nodes_list loose_list spacing power nb_channel f_min f_max format baud_rate OSNR bit_rate roll_off tx_osnr min_spacing cost path_bandwidth')
-DisjunctionParams = namedtuple('DisjunctionParams','disjunction_id relaxable link_diverse node_diverse disjunctions_req')
-
-class Path_request:
-    def __init__(self, *args, **params):
-        params = RequestParams(**params)
-        self.request_id = params.request_id
-        self.source     = params.source
-        self.destination = params.destination
-        self.tsp        = params.trx_type
-        self.tsp_mode   = params.trx_mode
-        self.baud_rate  = params.baud_rate
-        self.nodes_list = params.nodes_list
-        self.loose_list = params.loose_list
-        self.spacing    = params.spacing
-        self.power      = params.power
-        self.nb_channel = params.nb_channel
-        self.f_min       = params.f_min
-        self.f_max       = params.f_max
-        self.format     = params.format
-        self.OSNR       = params.OSNR
-        self.bit_rate   = params.bit_rate
-        self.roll_off   = params.roll_off
-        self.tx_osnr    = params.tx_osnr
-        self.min_spacing = params.min_spacing
-        self.cost       = params.cost
-        self.path_bandwidth  = params.path_bandwidth
-
-    def __str__(self):
-        return '\n\t'.join([  f'{type(self).__name__} {self.request_id}',
-                            f'source:       {self.source}',
-                            f'destination:  {self.destination}'])
-    def __repr__(self):
-        if self.baud_rate is not None:
-            temp = self.baud_rate * 1e-9
-            temp2 = self.bit_rate * 1e-9
-        else:
-            temp = self.baud_rate
-            temp2 = self.bit_rate
-
-        return '\n\t'.join([  f'{type(self).__name__} {self.request_id}',
-                            f'source: \t{self.source}',
-                            f'destination:\t{self.destination}',
-                            f'trx type:\t{self.tsp}',
-                            f'trx mode:\t{self.tsp_mode}',
-                            f'baud_rate:\t{temp} Gbaud',
-                            f'bit_rate:\t{temp2} Gb/s',
-                            f'spacing:\t{self.spacing * 1e-9} GHz',
-                            f'power:  \t{round(lin2db(self.power)+30,2)} dBm',
-                            f'nb channels: \t{self.nb_channel}',
-                            f'path_bandwidth: \t{round(self.path_bandwidth * 1e-9,2)} Gbit/s',
-                            f'nodes-list:\t{self.nodes_list}',
-                            f'loose-list:\t{self.loose_list}'
-                            '\n'])
-class Disjunction:
-    def __init__(self, *args, **params):
-        params = DisjunctionParams(**params)
-        self.disjunction_id = params.disjunction_id
-        self.relaxable = params.relaxable
-        self.link_diverse = params.link_diverse
-        self.node_diverse = params.node_diverse
-        self.disjunctions_req = params.disjunctions_req
-        
-    def __str__(self):
-        return '\n\t'.join([f'relaxable:    {self.relaxable}',
-                            f'link-diverse:       {self.link_diverse}',
-                            f'node-diverse:  {self.node_diverse}',
-                            f'request-id-numbers: {self.disjunctions_req}']
-                            )
-    def __repr__(self):
-        return '\n\t'.join([  f'{type(self).__name__} {self.disjunction_id}',
-                            f'relaxable:    {self.relaxable}',
-                            f'link-diverse:       {self.link_diverse}',
-                            f'node-diverse:  {self.node_diverse}',
-                            f'request-id-numbers: {self.disjunctions_req}'
-                            '\n'])
-
-class Result_element(Element):
-    def __init__(self,path_request,computed_path):
-        self.path_id = path_request.request_id
-        self.path_request = path_request
-        self.computed_path = computed_path
-        hop_type = []
-        if len(computed_path)>0 :
-            for e in computed_path :
-                if isinstance(e, Transceiver) :
-                    hop_type.append(' - '.join([path_request.tsp,path_request.tsp_mode]))
-                else:
-                    hop_type.append('not recorded')
-        else:
-            # TODO differentiate empty path in case not feasible because of tsp or not feasible because
-            # ther is no path connecting the nodes (whatever the tsp)
-            mode = 'not feasible with this transponder'
-            hop_type = ' - '.join([path_request.tsp,mode])
-        self.hop_type = hop_type
-    uid = property(lambda self: repr(self))
-    @property
-    def pathresult(self):
-        if not self.computed_path:
-            return {
-                   'path-id': self.path_id,
-                   'path-properties':{
-                       'path-metric': [
-                           {
-                           'metric-type': 'SNR@bandwidth',
-                           'accumulative-value': 'None'
-                           },
-                           {
-                           'metric-type': 'SNR@0.1nm',
-                           'accumulative-value': 'None'
-                           },
-                           {
-                           'metric-type': 'OSNR@bandwidth',
-                           'accumulative-value': 'None'
-                           },
-                           {
-                           'metric-type': 'OSNR@0.1nm',
-                           'accumulative-value': 'None'
-                           },
-                           {
-                           'metric-type': 'reference_power',
-                           'accumulative-value': self.path_request.power
-                           },
-                           {
-                           'metric-type': 'path_bandwidth',
-                           'accumulative-value': self.path_request.path_bandwidth
-                           }
-                        ],
-                        'path-srlgs': {
-                            'usage': 'not used yet',
-                            'values': 'not used yet'
-                        },
-                        'path-route-objects': [
-                            {
-                            'path-route-object': {
-                                'index': 0,
-                                'unnumbered-hop': {
-                                    'node-id': self.path_request.source,
-                                    'link-tp-id': self.path_request.source,
-                                    'hop-type':  self.hop_type,
-                                    'direction': 'not used'
-                                },
-                                'label-hop': {
-                                    'te-label': {
-                                        'generic': 'not used yet',
-                                        'direction': 'not used yet'
-                                        }
-                                    }
-                                }
-                            },
-                            {
-                            'path-route-object': {
-                                'index': 1,
-                                'unnumbered-hop': {
-                                    'node-id': self.path_request.destination,
-                                    'link-tp-id': self.path_request.destination,
-                                    'hop-type':  self.hop_type,
-                                    'direction': 'not used'
-                                },
-                                'label-hop': {
-                                    'te-label': {
-                                        'generic': 'not used yet',
-                                        'direction': 'not used yet'
-                                        }
-                                    }
-                                }
-                            }
-                            ]
-                    }
-                }
-        else:
-            return {
-                   'path-id': self.path_id,
-                   'path-properties':{
-                       'path-metric': [
-                           {
-                           'metric-type': 'SNR@bandwidth',
-                           'accumulative-value': round(mean(self.computed_path[-1].snr),2)
-                           },
-                           {
-                           'metric-type': 'SNR@0.1nm',
-                           'accumulative-value': round(mean(self.computed_path[-1].snr+lin2db(self.path_request.baud_rate/12.5e9)),2)
-                           },
-                           {
-                           'metric-type': 'OSNR@bandwidth',
-                           'accumulative-value': round(mean(self.computed_path[-1].osnr_ase),2)
-                           },
-                           {
-                           'metric-type': 'OSNR@0.1nm',
-                           'accumulative-value': round(mean(self.computed_path[-1].osnr_ase_01nm),2)
-                           },
-                           {
-                           'metric-type': 'reference_power',
-                           'accumulative-value': self.path_request.power
-                           },
-                           {
-                           'metric-type': 'path_bandwidth',
-                           'accumulative-value': self.path_request.path_bandwidth
-                           }
-                        ],
-                        'path-srlgs': {
-                            'usage': 'not used yet',
-                            'values': 'not used yet'
-                        },
-                        'path-route-objects': [
-                            {
-                            'path-route-object': {
-                                'index': self.computed_path.index(n),
-                                'unnumbered-hop': {
-                                    'node-id': n.uid,
-                                    'link-tp-id': n.uid,
-                                    'hop-type': self.hop_type[self.computed_path.index(n)],
-                                    'direction': 'not used'
-                                },
-                                'label-hop': {
-                                    'te-label': {
-                                        'generic': 'not used yet',
-                                        'direction': 'not used yet'
-                                        }
-                                    }
-                                }
-                            } for n in self.computed_path
-                            ]
-                    }
-                }
-
-    @property
-    def json(self):
-        return self.pathresult
-
-def compute_constrained_path(network, req):
-    trx = [n for n in network.nodes() if isinstance(n, Transceiver)]
-    roadm = [n for n in network.nodes() if isinstance(n, Roadm)]
-    edfa = [n for n in network.nodes() if isinstance(n, Edfa)]
-    anytypenode = [n for n in network.nodes()]
-
-    source = next(el for el in trx if el.uid == req.source)
-
-    # This method ensures that the constraint can be satisfied without loops
-    # except when it is not possible : eg if constraints makes a loop
-    # It requires that the source, dest and nodes are correct (no error in the names)
-    destination = next(el for el in trx if el.uid == req.destination)
-    nodes_list = []
-    for n in req.nodes_list :
-        # for debug excel print(n)
-        nodes_list.append(next(el for el in anytypenode if el.uid == n))
-    # nodes_list contains at least the destination
-    if nodes_list is None :
-        msg = f'Request {req.request_id} problem in the constitution of nodes_list: should at least include destination'
-        logger.critical(msg)
-        exit()
-    if req.nodes_list[-1] != req.destination:
-        msg = f'Request {req.request_id} malformed list of nodes: last node should be destination trx'
-        logger.critical(msg)
-        exit()
-
-    if len(nodes_list) == 1  :
-        try :
-            total_path = dijkstra_path(network, source, destination)
-        except NetworkXNoPath:
-            msg = f'\x1b[1;33;40m'+f'Request {req.request_id} could not find a path from {source.uid} to node : {destination.uid} in network topology'+ '\x1b[0m'
-            logger.critical(msg)
-            print(msg)
-            total_path = []        
-    else : 
-        all_simp_pths = list(all_simple_paths(network,source=source,\
-            target=destination, cutoff=120))
-        candidate = []
-        for p in all_simp_pths :
-            if ispart(nodes_list, p) :
-                # print(f'selection{[el.uid for el in p if el in roadm]}')
-                candidate.append(p)
-        # select the shortest path (in nb of hops)
-        if len(candidate)>0 :
-            candidate.sort(key=lambda x: len(x))
-            total_path = candidate[0]
-        else:
-            if req.loose_list[req.nodes_list.index(n)] == 'loose':
-                print(f'\x1b[1;33;40m'+f'Request {req.request_id} could not find a path crossing {nodes_list} in network topology'+ '\x1b[0m')
-                print(f'constraint ignored')
-                total_path = dijkstra_path(network, source, destination)
-            else:
-                msg = f'\x1b[1;33;40m'+f'Request {req.request_id} could not find a path crossing {nodes_list}.\nNo path computed'+ '\x1b[0m'
-                logger.critical(msg)
-                print(msg)
-                total_path = []
-
-    # obsolete method: this does not guaranty to avoid loops or correct results
-    # Here is the demonstration :
-    #         1     1
-    # eg    a----b-----c
-    #       |1   |0.5  |1
-    #       e----f--h--g
-    #         1  0.5 0.5
-    # if I have to compute a to g with constraint f-c
-    # result will be a concatenation of: a-b-f and f-b-c and c-g
-    # which means a loop. 
-    # if to avoid loops I iteratively suppress edges of the segmenst in the topo
-    # segment 1 = a-b-f
-    #               1
-    # eg    a    b-----c
-    #       |1         |1
-    #       e----f--h--g
-    #         1  0.5 0.5
-    # then 
-    # segment 2 = f-h-g-c
-    #               1
-    # eg    a    b-----c
-    #       |1          
-    #       e----f  h  g
-    #         1  
-    # then there is no more path to g destination
-    #
-    # 
-    # total_path = [source]
-
-    # for n in req.nodes_list:
-    #     try :
-    #         node = next(el for el in trx if el.uid == n)
-    #     except StopIteration:
-    #         try:
-    #             node = next(el for el in anytypenode if el.uid == n)
-    #         except StopIteration:
-    #             try:
-    #                 # TODO this test is not giving good results: full name of the 
-    #                 # amp is required to avoid ambiguity on the direction
-    #                 node = next(el for el in anytypenode 
-    #                     if n in el.uid)
-    #             except StopIteration:
-    #                 msg = f'could not find node : {n} in network topology: \
-    #                     not a trx, roadm, edfa, fiber or fused element'
-    #                 logger.critical(msg)
-    #                 raise ValueError(msg)
-    #     # extend path list without repeating source -> skip first element in the list
-    #     try:
-    #         # to avoid looping back: use an alternate graph were current path edges and vertex are suppressed
-
-    #         total_path.extend(dijkstra_path(network, source, node)[1:])
-    #         source = node
-    #     except NetworkXNoPath:
-    #         if req.loose_list[req.nodes_list.index(n)] == 'loose':
-    #             print(f'could not find a path from {source.uid} to loose node : {n} in network topology')
-    #             print(f'node  {n} is skipped')
-    #         else:
-    #             msg = f'could not find a path from {source.uid} to node : {n} in network topology'
-    #             logger.critical(msg)
-    #             print(msg)
-    #             total_path = []
-
-    return total_path
-
-def propagate(path, req, equipment, show=False):
-    #update roadm loss in case of power sweep (power mode only)
-    set_roadm_loss(path, equipment, lin2db(req.power*1e3))
-    si = create_input_spectral_information(
-        req.f_min, req.f_max, req.roll_off, req.baud_rate,
-        req.power, req.spacing)
-    for el in path:
-        si = el(si)
-        if show :
-            print(el)
-    path[-1].update_snr(req.tx_osnr, equipment['Roadms']['default'].add_drop_osnr)
-    return path
-
-def propagate2(path, req, equipment, show=False):
-    #update roadm loss in case of power sweep (power mode only)
-    set_roadm_loss(path, equipment, lin2db(req.power*1e3))
-    si = create_input_spectral_information(
-        req.f_min, req.f_max, req.roll_off, req.baud_rate,
-        req.power, req.spacing)
-    infos = {}
-    for el in path:
-        before_si = si
-        after_si  = si = el(si)
-        infos[el] = before_si, after_si
-        if show :
-            print(el)
-    path[-1].update_snr(req.tx_osnr, equipment['Roadms']['default'].add_drop_osnr)
-    return infos
-
-def propagate_and_optimize_mode(path, req, equipment):
-    #update roadm loss in case of power sweep (power mode only)
-    set_roadm_loss(path, equipment, lin2db(req.power*1e3))
-    # if mode is unknown : loops on the modes starting from the highest baudrate fiting in the
-    # step 1: create an ordered list of modes based on baudrate
-    baudrate_to_explore = list(set([m['baud_rate'] for m in equipment['Transceiver'][req.tsp].mode 
-        if float(m['min_spacing'])<= req.spacing]))  
-        # TODO be carefull on limits cases if spacing very close to req spacing eg 50.001 50.000
-    baudrate_to_explore = sorted(baudrate_to_explore, reverse=True)
-    if baudrate_to_explore : 
-        # at least 1 baudrate can be tested wrt spacing
-        for b in baudrate_to_explore :
-            modes_to_explore = [m for m in equipment['Transceiver'][req.tsp].mode 
-                if m['baud_rate'] == b]
-            modes_to_explore = sorted(modes_to_explore, 
-                key = lambda x: x['bit_rate'], reverse=True)
-            # print(modes_to_explore)
-            # step2 : computes propagation for each baudrate: stop and select the first that passes
-            found_a_feasible_mode = False
-            # TODO : the case of roll of is not included: for now use SI one
-            # TODO : if the loop in mode optimization does not have a feasible path, then bugs
-            si = create_input_spectral_information(
-            req.f_min, req.f_max, equipment['SI']['default'].roll_off,
-            b, req.power, req.spacing)
-            for el in path:
-                si = el(si)
-            for m in modes_to_explore :
-                if path[-1].snr is not None:
-                    path[-1].update_snr(m['tx_osnr'], equipment['Roadms']['default'].add_drop_osnr)
-                    if round(min(path[-1].snr+lin2db(b/(12.5e9))),2) > m['OSNR'] :
-                        found_a_feasible_mode = True
-                        return path, m
-                else:  
-                    return [], None
-        # only get to this point if no baudrate/mode satisfies OSNR requirement
-
-        # returns the last propagated path and mode
-        msg = f'\tWarning! Request {req.request_id}: no mode satisfies path SNR requirement.\n'
-        print(msg)
-        logger.info(msg)
-        return [],None
-    else :
-    #  no baudrate satisfying spacing
-        msg = f'\tWarning! Request {req.request_id}: no baudrate satisfies spacing requirement.\n'
-        print(msg)
-        logger.info(msg)
-        return [], None
-
-
-def jsontocsv(json_data,equipment,fileout):
-    # read json path result file in accordance with:
-    # Yang model for requesting Path Computation
-    # draft-ietf-teas-yang-path-computation-01.txt.
-    # and write results in an CSV file
-
-    mywriter = writer(fileout)
-    mywriter.writerow(('path-id','source','destination','path_bandwidth','Pass?',\
-        'nb of tsp pairs','total cost','transponder-type','transponder-mode',\
-        'OSNR@0.1nm','SNR@0.1nm','SNR@bandwidth','baud rate (Gbaud)',\
-        'input power (dBm)','path'))
-    tspjsondata = equipment['Transceiver']
-    #print(tspjsondata)
-    for p in json_data['path']:
-        path_id     = p['path-id']
-        source      = p['path-properties']['path-route-objects'][0]\
-        ['path-route-object']['unnumbered-hop']['node-id']
-        destination = p['path-properties']['path-route-objects'][-1]\
-        ['path-route-object']['unnumbered-hop']['node-id']
-        # selects only roadm nodes
-        pth        = ' | '.join([ e['path-route-object']['unnumbered-hop']['node-id']
-                 for e in p['path-properties']['path-route-objects'] 
-                 if e['path-route-object']['unnumbered-hop']['node-id'].startswith('roadm') or e['path-route-object']['unnumbered-hop']['node-id'].startswith('Edfa')])
-
-        [tsp,mode] = p['path-properties']['path-route-objects'][0]\
-        ['path-route-object']['unnumbered-hop']['hop-type'].split(' - ')
-
-        # find the min  acceptable OSNR, baud rate from the eqpt library based on tsp (tupe) and mode (format)
-        # loading equipment already tests the existence of tsp type and mode:
-        if mode !='not feasible with this transponder' :
-            [minosnr, baud_rate, bit_rate, cost] = next([m['OSNR'] , m['baud_rate'] , m['bit_rate'], m['cost']]  
-                for m in equipment['Transceiver'][tsp].mode if  m['format']==mode)
-        # else:
-        #     [minosnr, baud_rate, bit_rate] = ['','','','']
-        output_snr = next(e['accumulative-value'] 
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'SNR@0.1nm')
-        output_snrbandwidth = next(e['accumulative-value']
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'SNR@bandwidth')
-        output_osnr = next(e['accumulative-value']
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'OSNR@0.1nm')
-        output_osnrbandwidth = next(e['accumulative-value']
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'OSNR@bandwidth')
-        power = next(e['accumulative-value']
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'reference_power')
-        path_bandwidth = next(e['accumulative-value']
-            for e in p['path-properties']['path-metric'] if e['metric-type'] == 'path_bandwidth')
-        if isinstance(output_snr, str):
-            isok = False
-            nb_tsp = 0
-            pthbdbw = round(path_bandwidth*1e-9,2)
-            rosnr = ''
-            rsnr = ''
-            rsnrb = ''
-            br = ''
-            pw = ''
-            total_cost = ''
-        else:
-            isok   = output_snr >= minosnr
-            nb_tsp = ceil(path_bandwidth / bit_rate)
-            pthbdbw = round(path_bandwidth*1e-9,2)
-            rosnr  = round(output_osnr,2)
-            rsnr   = round(output_snr,2)
-            rsnrb  = round(output_snrbandwidth,2)
-            br     = round(baud_rate*1e-9,2) 
-            pw     = round(lin2db(power)+30,2)
-            total_cost = nb_tsp * cost
-        mywriter.writerow((path_id,
-            source,
-            destination,
-            pthbdbw,
-            isok,
-            nb_tsp,
-            total_cost,
-            tsp,
-            mode,
-            rosnr,
-            rsnr,
-            rsnrb,
-            br,
-            pw,
-            pth
-            ))
-
-
-def compute_path_dsjctn(network, equipment, pathreqlist, disjunctions_list):
-    # pathreqlist is a list of Path_request objects
-    # disjunctions_list a list of Disjunction objects
-    
-    # given a network, a list of requests with the set of disjunction features between
-    # request, the function computes the set of path satisfying : first the disjunction
-    # constraint and second the routing constraint if the request include an explicit 
-    # set of elements to pass through.
-    # the algorithm used allows to specify disjunction for demands not sharing source or
-    # destination.
-    # a request might be declared as disjoint from several requests
-    # it is a iterative process:
-    # first computes a list of all shortest path (this may add computation time)
-    # second elaborate the set of path solution for each synchronization vector
-    # third select only the candidates that satisfy all synchronization vectors they belong to
-    # fourth apply route constraints : remove candidate path that do not satisfy the constraint
-    # fifth select the first candidate among the set of candidates.
-    # the example network used in comments has been added to the set of data tests files
-
-    # define the list to be returned
-    path_res_list = []
-
-    # all disjctn must be computed at once together to avoid blocking
-    #         1     1
-    # eg    a----b-----c
-    #       |1   |0.5  |1
-    #       e----f--h--g
-    #         1  0.5 0.5
-    # if I have to compute a to g and a to h 
-    # I must not compute a-b-f-h-g, otherwise there is no disjoint path remaining for a to h
-    # instead I should list all most disjoint path and select the one that have the less
-    # number of commonalities
-    #     \     path abfh  aefh   abcgh 
-    #      \___cost   2     2.5    3.5
-    #   path| cost  
-    #  abfhg|  2.5    x      x      x
-    #  abcg |  3      x             x
-    #  aefhg|  3      x      x      x
-    # from this table abcg and aefh have no common links and should be preferred 
-    # even they are not the shortest paths
-
-    # build the list of pathreqlist elements not concerned by disjunction
-    global_disjunctions_list = [e for d in disjunctions_list for e in d.disjunctions_req ]
-    pathreqlist_simple = [e for e in pathreqlist if e.request_id not in global_disjunctions_list]
-    pathreqlist_disjt = [e for e in pathreqlist if e.request_id in global_disjunctions_list]
-
-    # use a mirror class to record path and the corresponding requests
-    class Pth:
-        def __init__(self, req, pth, simplepth):
-            self.req = req
-            self.pth = pth
-            self.simplepth = simplepth
-
-    # step 1
-    # for each remaining request compute a set of simple path
-    allpaths = {}
-    rqs = {}
-    simple_rqs = {}
-    simple_rqs_reversed = {}
-    for pathreq in pathreqlist_disjt :
-        all_simp_pths = list(all_simple_paths(network,\
-            source=next(el for el in network.nodes() if el.uid == pathreq.source),\
-            target=next(el for el in network.nodes() if el.uid == pathreq.destination),\
-            cutoff=80))
-        # sort them
-        all_simp_pths = sorted(all_simp_pths, key=lambda path: len(path))
-        # reversed direction paths required to check disjunction on both direction
-        all_simp_pths_reversed = []
-        for pth in all_simp_pths:
-            all_simp_pths_reversed.append(find_reversed_path(pth,network))
-        rqs[pathreq.request_id] = all_simp_pths 
-        temp =[]
-        for p in all_simp_pths :
-            # build a short list representing each roadm+direction with the first item
-            # start enumeration at 1 to avoid Trx in the list
-            s = [e.uid for i,e in enumerate(p[1:-1]) \
-                if (isinstance(e,Roadm) | (isinstance(p[i],Roadm) ))] 
-            temp.append(s)
-            # id(s) is unique even if path is the same: two objects with same 
-            # path have two different ids
-            allpaths[id(s)] = Pth(pathreq,p,s)
-        simple_rqs[pathreq.request_id] = temp
-        temp =[]
-        for p in all_simp_pths_reversed :
-            # build a short list representing each roadm+direction with the first item
-            # start enumeration at 1 to avoid Trx in the list
-            temp.append([e.uid for i,e in enumerate(p[1:-1]) \
-                if (isinstance(e,Roadm) | (isinstance(p[i],Roadm) ))] )
-        simple_rqs_reversed[pathreq.request_id] = temp
-    # step 2 
-    # for each set of requests that need to be disjoint
-    # select the disjoint path combination
-
-    candidates = {}
-    for d in disjunctions_list :
-        dlist = d.disjunctions_req.copy()
-        # each line of dpath is one combination of path that satisfies disjunction
-        dpath = []
-        for i,p in enumerate(simple_rqs[dlist[0]]):
-            dpath.append([p])
-            # allpaths[id(p)].d_id = d.disjunction_id
-        # in each loop, dpath is updated with a path for rq that satisfies 
-        # disjunction with each path in dpath
-        # for example, assume set of requests in the vector (disjunction_list) is  {rq1,rq2, rq3}
-        # rq1  p1: abfhg
-        #      p2: aefhg
-        #      p3: abcg
-        # rq2  p8: bf
-        # rq3  p4: abcgh
-        #      p6: aefh
-        #      p7: abfh
-        # initiate with rq1
-        #  dpath = [[p1]
-        #           [p2]
-        #           [p3]]
-        #  after first loop:
-        #  dpath = [[p1 p8]
-        #           [p3 p8]]
-        #  since p2 and p8 are not disjoint
-        #  after second loop:
-        #  dpath = [ p3 p8 p6 ]
-        #  since p1 and p4 are not disjoint 
-        #        p1 and p7 are not disjoint
-        #        p3 and p4 are not disjoint
-        #        p3 and p7 are not disjoint
-
-        for e1 in dlist[1:] :
-            temp = []
-            for j,p1 in enumerate(simple_rqs[e1]):
-                # allpaths[id(p1)].d_id = d.disjunction_id
-                # can use index j in simple_rqs_reversed because index 
-                # of direct and reversed paths have been kept identical
-                p1_reversed = simple_rqs_reversed[e1][j]
-                # print(p1_reversed)
-                # print('\n\n')
-                for k,c in enumerate(dpath) :
-                    # print(f' c: \t{c}')
-                    temp2 = c.copy()
-                    all_disjoint = 0
-                    for p in c :
-                        all_disjoint += isdisjoint(p1,p)+ isdisjoint(p1_reversed,p)
-                    if all_disjoint ==0:
-                        temp2.append(p1)
-                        temp.append(temp2)
-                            # print(f' coucou {e1}: \t{temp}')
-            dpath = temp
-        # print(dpath)
-        candidates[d.disjunction_id] = dpath
-
-    # for i in disjunctions_list  :
-    #     print(f'\n{candidates[i.disjunction_id]}')
-
-    # step 3
-    # now for each request, select the path that satisfies all disjunctions
-    # path must be in candidates[id] for all concerned ids
-    # for example, assume set of sync vectors (disjunction groups) is
-    #   s1 = {rq1 rq2}   s2 = {rq1 rq3}
-    #   candidate[s1] = [[p1 p8]
-    #                    [p3 p8]]
-    #   candidate[s2] = [[p3 p6]]
-    #   for rq1 p3 should be preferred
-
-
-    for pathreq in pathreqlist_disjt:
-        concerned_d_id = [d.disjunction_id for d in disjunctions_list if pathreq.request_id in d.disjunctions_req]
-        # for each set of solution, verify that the same path is used for the same request
-        candidate_paths = simple_rqs[pathreq.request_id]
-        # print('coucou')
-        # print(pathreq.request_id)
-        for p in candidate_paths :
-            iscandidate = 0
-            for sol in concerned_d_id :
-                test = 1
-                # for each solution test if p is part of the solution
-                # if yes, then p can remain a candidate
-                for i,m in enumerate(candidates[sol]) :
-                    if p in m:
-                        if allpaths[id(m[m.index(p)])].req.request_id == pathreq.request_id :
-                            test = 0
-                            break
-                iscandidate += test
-            if iscandidate != 0:
-                for l in concerned_d_id :
-                    for m in candidates[l] :
-                        if p in m :
-                            candidates[l].remove(m)
-
-#    for i in disjunctions_list  :
-#        print(i.disjunction_id)
-#        print(f'\n{candidates[i.disjunction_id]}')
-
-    # step 4 apply route constraints : remove candidate path that do not satisfy the constraint
-    # only in  the case of disjounction: the simple path is processed in request.compute_constrained_path
-    # TODO : keep a version without the loose constraint
-    for d in disjunctions_list  :
-        temp = []
-        for j,sol in enumerate(candidates[d.disjunction_id]) :
-            testispartok = True
-            for i,p in enumerate(sol) :
-                # print(f'test {allpaths[id(p)].req.request_id}')
-                # print(f'length of route {len(allpaths[id(p)].req.nodes_list)}')
-                if allpaths[id(p)].req.nodes_list :
-                    # if p does not containt the ordered list node, remove sol from the candidate
-                    # except if this was the last solution: then check if the constraint is loose or not
-                    if not ispart(allpaths[id(p)].req.nodes_list, p) : 
-                        # print(f'nb of solutions {len(temp)}')
-                        if j < len(candidates[d.disjunction_id])-1 :
-                            msg = f'removing {sol}'
-                            logger.info(msg)
-                            testispartok = False
-                            #break
-                        else:
-                            if 'loose' in allpaths[id(p)].req.loose_list:
-                                logger.info(f'Could not apply route constraint'+
-                                    f'{allpaths[id(p)].req.nodes_list} on request {allpaths[id(p)].req.request_id}')
-                            else :
-                                logger.info(f'removing last solution from candidate paths\n{sol}')
-                                testispartok = False
-            if testispartok :
-                temp.append(sol)
-        candidates[d.disjunction_id] = temp
-
-    # step 5 select the first combination that works
-    pathreslist_disjoint = {}
-    for d in disjunctions_list  :
-        test_sol = True
-        while test_sol:
-            # print('coucou')
-            if candidates[d.disjunction_id] :
-                for p in candidates[d.disjunction_id][0]:
-                    if allpaths[id(p)].req in pathreqlist_disjt: 
-                        # print(f'selected path :{p} for req {allpaths[id(p)].req.request_id}')
-                        pathreslist_disjoint[allpaths[id(p)].req] = allpaths[id(p)].pth
-                        pathreqlist_disjt.remove(allpaths[id(p)].req)
-                        candidates = remove_candidate(candidates, allpaths, allpaths[id(p)].req, p)
-                        test_sol = False
-            else:
-                msg = f'No disjoint path found with added constraint'
-                logger.critical(msg)
-                print(f'{msg}\nComputation stopped.')
-                # TODO in this case: replay step 5  with the candidate without constraints
-                exit()
-    
-    # for i in disjunctions_list  :
-    #     print(i.disjunction_id)
-    #     print(f'\n{candidates[i.disjunction_id]}')
-
-    # list the results in the same order as initial pathreqlist        
-    for req in pathreqlist :
-        req.nodes_list.append(req.destination)
-        # we assume that the destination is a strict constraint
-        req.loose_list.append('strict')
-        if req in pathreqlist_simple:
-            path_res_list.append(compute_constrained_path(network, req))
-        else:
-            path_res_list.append(pathreslist_disjoint[req])
-    return path_res_list
-
-def isdisjoint(p1,p2) :
-    # returns 0 if disjoint
-    edge1 = list(pairwise(p1))
-    edge2 = list(pairwise(p2))
-    for e in edge1 :
-        if e in edge2 :
-            return 1
-    return 0
-
-def find_reversed_path(p,network) :
-    # select of intermediate roadms and find the path between them
-    # note that this function may not give an exact result in case of multiple
-    # links between two adjacent nodes. 
-    # TODO add some indication on elements to indicate from which other they 
-    # are the reversed direction
-    reversed_roadm_path = list(reversed([e for e in p if isinstance (e,Roadm)]))
-    source = p[-1]
-    destination = p[0]
-    total_path = [source]
-    for node in reversed_roadm_path :
-        total_path.extend(dijkstra_path(network, source, node)[1:])
-        source = node
-    total_path.append(destination)
-    return total_path
-
-def ispart(a,b) :
-    # the functions takes two paths a and b and retrns True
-    # if all a elements are part of b and in the same order
-    j = 0
-    for i, el in enumerate(a):
-        if el in b :
-            if b.index(el) >= j :
-                j = b.index(el)
-            else: 
-                return False
-        else:
-            return False
-    return True
-
-def remove_candidate(candidates, allpaths, rq, pth) :
-    # print(f'coucou {rq.request_id}')
-    for key, candidate  in candidates.items() :
-        temp = candidate.copy()
-        for i,sol in enumerate(candidate) :
-            for p in sol :
-                if allpaths[id(p)].req.request_id == rq.request_id :
-                    if id(p) != id(pth) :
-                        temp.remove(sol)
-                        break
-        candidates[key] = temp
-    return candidates
-
-def compare_reqs(req1,req2,disjlist) :
-    dis1 = [d for d in disjlist if req1.request_id in d.disjunctions_req]
-    dis2 = [d for d in disjlist if req2.request_id in d.disjunctions_req]
-    same_disj = False
-    if dis1 and dis2 :
-        temp1 = []
-        for d in dis1:
-            temp1.extend(d.disjunctions_req)
-            temp1.remove(req1.request_id)
-        temp2 = []
-        for d in dis2:
-            temp2.extend(d.disjunctions_req)
-            temp2.remove(req2.request_id)
-        if set(temp1) == set(temp2) :
-            same_disj = True
-    elif not dis2 and not dis1:
-        same_disj = True
-
-    if req1.source     == req2.source and \
-        req1.destination == req2.destination and  \
-        req1.tsp        == req2.tsp and \
-        req1.tsp_mode   == req2.tsp_mode and \
-        req1.baud_rate  == req2.baud_rate and \
-        req1.nodes_list == req2.nodes_list and \
-        req1.loose_list == req2.loose_list and \
-        req1.spacing    == req2.spacing and \
-        req1.power      == req2.power and \
-        req1.nb_channel == req2.nb_channel and \
-        req1.f_min  == req2.f_min and \
-        req1.f_max  == req2.f_max and \
-        req1.format     == req2.format and \
-        req1.OSNR       == req2.OSNR and \
-        req1.roll_off   == req2.roll_off and \
-        same_disj :
-        return True
-    else:
-        return False
-
-def requests_aggregation(pathreqlist,disjlist) :
-    # this function aggregates requests so that if several requests
-    # exist between same source and destination and with same transponder type
-    # todo maybe add conditions on mode ??, spacing ...
-    # currently if undefined takes the default values
-    local_list = pathreqlist.copy()
-    for req in pathreqlist:
-        for r in local_list : 
-            if  req.request_id != r.request_id and compare_reqs(req, r, disjlist):
-                # aggregate
-                r.path_bandwidth += req.path_bandwidth
-                temp_r_id = r.request_id
-                r.request_id = ' | '.join((r.request_id,req.request_id))
-                # remove request from list
-                local_list.remove(req)
-                # todo change also disjunction req with new demand
-
-                for d in disjlist :
-                    if req.request_id in d.disjunctions_req :
-                        d.disjunctions_req.remove(req.request_id)
-                        d.disjunctions_req.append(r.request_id)
-                for d in disjlist :        
-                    if temp_r_id in d.disjunctions_req :
-                        disjlist.remove(d)
-                break
-    return local_list, disjlist

gnpy/core/science_utils.py

@@ -0,0 +1,742 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.core.science_utils
+=======================
+
+Solver definitions to calculate the Raman effect and the nonlinear interference noise
+
+The solvers take as input instances of the spectral information, the fiber and the simulation parameters
+"""
+
+from numpy import interp, pi, zeros, shape, where, cos, reshape, array, append, ones, argsort, nan, exp, arange, sqrt, \
+    empty, vstack, trapz, arcsinh, clip, abs, sum
+from operator import attrgetter
+from logging import getLogger
+import scipy.constants as ph
+from scipy.integrate import solve_bvp
+from scipy.integrate import cumtrapz
+from scipy.interpolate import interp1d
+from scipy.optimize import OptimizeResult
+from math import isclose
+
+from gnpy.core.utils import db2lin, lin2db
+from gnpy.core.exceptions import EquipmentConfigError
+
+logger = getLogger(__name__)
+
+
+def propagate_raman_fiber(fiber, *carriers):
+    simulation = Simulation.get_simulation()
+    sim_params = simulation.sim_params
+    raman_params = sim_params.raman_params
+    nli_params = sim_params.nli_params
+    # apply input attenuation to carriers
+    attenuation_in = db2lin(fiber.params.con_in + fiber.params.att_in)
+    chan = []
+    for carrier in carriers:
+        pwr = carrier.power
+        pwr = pwr._replace(signal=pwr.signal / attenuation_in,
+                           nli=pwr.nli / attenuation_in,
+                           ase=pwr.ase / attenuation_in)
+        carrier = carrier._replace(power=pwr)
+        chan.append(carrier)
+    carriers = tuple(f for f in chan)
+
+    # evaluate fiber attenuation involving also SRS if required by sim_params
+    raman_solver = fiber.raman_solver
+    raman_solver.carriers = carriers
+    raman_solver.raman_pumps = fiber.raman_pumps
+    stimulated_raman_scattering = raman_solver.stimulated_raman_scattering
+
+    fiber_attenuation = (stimulated_raman_scattering.rho[:, -1])**-2
+    if not raman_params.flag_raman:
+        fiber_attenuation = tuple(fiber.params.lin_attenuation for _ in carriers)
+
+    # evaluate Raman ASE noise if required by sim_params and if raman pumps are present
+    if raman_params.flag_raman and fiber.raman_pumps:
+        raman_ase = raman_solver.spontaneous_raman_scattering.power[:, -1]
+    else:
+        raman_ase = tuple(0 for _ in carriers)
+
+    # evaluate nli and propagate in fiber
+    attenuation_out = db2lin(fiber.params.con_out)
+    nli_solver = fiber.nli_solver
+    nli_solver.stimulated_raman_scattering = stimulated_raman_scattering
+
+    nli_frequencies = []
+    computed_nli = []
+    for carrier in (c for c in carriers if c.channel_number in sim_params.nli_params.computed_channels):
+        resolution_param = frequency_resolution(carrier, carriers, sim_params, fiber)
+        f_cut_resolution, f_pump_resolution, _, _ = resolution_param
+        nli_params.f_cut_resolution = f_cut_resolution
+        nli_params.f_pump_resolution = f_pump_resolution
+        nli_frequencies.append(carrier.frequency)
+        computed_nli.append(nli_solver.compute_nli(carrier, *carriers))
+
+    new_carriers = []
+    for carrier, attenuation, rmn_ase in zip(carriers, fiber_attenuation, raman_ase):
+        carrier_nli = interp(carrier.frequency, nli_frequencies, computed_nli)
+        pwr = carrier.power
+        pwr = pwr._replace(signal=pwr.signal / attenuation / attenuation_out,
+                           nli=(pwr.nli + carrier_nli) / attenuation / attenuation_out,
+                           ase=((pwr.ase / attenuation) + rmn_ase) / attenuation_out)
+        new_carriers.append(carrier._replace(power=pwr))
+    return new_carriers
+
+
+def frequency_resolution(carrier, carriers, sim_params, fiber):
+    def _get_freq_res_k_phi(delta_count, grid_size, alpha0, delta_z, beta2, k_tol, phi_tol):
+        res_phi = _get_freq_res_phase_rotation(delta_count, grid_size, delta_z, beta2, phi_tol)
+        res_k = _get_freq_res_dispersion_attenuation(delta_count, grid_size, alpha0, beta2, k_tol)
+        res_dict = {'res_phi': res_phi, 'res_k': res_k}
+        method = min(res_dict, key=res_dict.get)
+        return res_dict[method], method, res_dict
+
+    def _get_freq_res_dispersion_attenuation(delta_count, grid_size, alpha0, beta2, k_tol):
+        return k_tol * abs(alpha0) / abs(beta2) / (1 + delta_count) / (4 * pi ** 2 * grid_size)
+
+    def _get_freq_res_phase_rotation(delta_count, grid_size, delta_z, beta2, phi_tol):
+        return phi_tol / abs(beta2) / (1 + delta_count) / delta_z / (4 * pi ** 2 * grid_size)
+
+    grid_size = sim_params.nli_params.wdm_grid_size
+    delta_z = sim_params.raman_params.space_resolution
+    alpha0 = fiber.alpha0()
+    beta2 = fiber.params.beta2
+    k_tol = sim_params.nli_params.dispersion_tolerance
+    phi_tol = sim_params.nli_params.phase_shift_tolerance
+    f_pump_resolution, method_f_pump, res_dict_pump = \
+        _get_freq_res_k_phi(0, grid_size, alpha0, delta_z, beta2, k_tol, phi_tol)
+    f_cut_resolution = {}
+    method_f_cut = {}
+    res_dict_cut = {}
+    for cut_carrier in carriers:
+        delta_number = cut_carrier.channel_number - carrier.channel_number
+        delta_count = abs(delta_number)
+        f_res, method, res_dict = \
+            _get_freq_res_k_phi(delta_count, grid_size, alpha0, delta_z, beta2, k_tol, phi_tol)
+        f_cut_resolution[f'delta_{delta_number}'] = f_res
+        method_f_cut[delta_number] = method
+        res_dict_cut[delta_number] = res_dict
+    return [f_cut_resolution, f_pump_resolution, (method_f_cut, method_f_pump), (res_dict_cut, res_dict_pump)]
+
+
+def raised_cosine_comb(f, *carriers):
+    """ Returns an array storing the PSD of a WDM comb of raised cosine shaped
+    channels at the input frequencies defined in array f
+    :param f: numpy array of frequencies in Hz
+    :param carriers: namedtuple describing the WDM comb
+    :return: PSD of the WDM comb evaluated over f
+    """
+    psd = zeros(shape(f))
+    for carrier in carriers:
+        f_nch = carrier.frequency
+        g_ch = carrier.power.signal / carrier.baud_rate
+        ts = 1 / carrier.baud_rate
+        pass_band = (1 - carrier.roll_off) / (2 / carrier.baud_rate)
+        stop_band = (1 + carrier.roll_off) / (2 / carrier.baud_rate)
+        ff = abs(f - f_nch)
+        tf = ff - pass_band
+        if carrier.roll_off == 0:
+            psd = where(tf <= 0, g_ch, 0.) + psd
+        else:
+            psd = g_ch * (where(tf <= 0, 1., 0.) + 1 / 2 * (1 + cos(pi * ts / carrier.roll_off * tf)) *
+                          where(tf > 0, 1., 0.) * where(abs(ff) <= stop_band, 1., 0.)) + psd
+    return psd
+
+
+class Simulation:
+    _shared_dict = {}
+
+    def __init__(self):
+        if type(self) == Simulation:
+            raise NotImplementedError('Simulation cannot be instatiated')
+
+    @classmethod
+    def set_params(cls, sim_params):
+        cls._shared_dict['sim_params'] = sim_params
+
+    @classmethod
+    def get_simulation(cls):
+        self = cls.__new__(cls)
+        return self
+
+    @property
+    def sim_params(self):
+        return self._shared_dict['sim_params']
+
+
+class SpontaneousRamanScattering:
+    def __init__(self, frequency, z, power):
+        self.frequency = frequency
+        self.z = z
+        self.power = power
+
+
+class StimulatedRamanScattering:
+    def __init__(self, frequency, z, rho, power):
+        self.frequency = frequency
+        self.z = z
+        self.rho = rho
+        self.power = power
+
+
+class RamanSolver:
+    def __init__(self, fiber=None):
+        """ Initialize the Raman solver object.
+        :param fiber: instance of elements.py/Fiber.
+        :param carriers: tuple of carrier objects
+        :param raman_pumps: tuple containing pumps characteristics
+        """
+        self._fiber = fiber
+        self._carriers = None
+        self._raman_pumps = None
+        self._stimulated_raman_scattering = None
+        self._spontaneous_raman_scattering = None
+
+    @property
+    def fiber(self):
+        return self._fiber
+
+    @property
+    def carriers(self):
+        return self._carriers
+
+    @carriers.setter
+    def carriers(self, carriers):
+        self._carriers = carriers
+        self._spontaneous_raman_scattering = None
+        self._stimulated_raman_scattering = None
+
+    @property
+    def raman_pumps(self):
+        return self._raman_pumps
+
+    @raman_pumps.setter
+    def raman_pumps(self, raman_pumps):
+        self._raman_pumps = raman_pumps
+        self._stimulated_raman_scattering = None
+
+    @property
+    def stimulated_raman_scattering(self):
+        if self._stimulated_raman_scattering is None:
+            self.calculate_stimulated_raman_scattering(self.carriers, self.raman_pumps)
+        return self._stimulated_raman_scattering
+
+    @property
+    def spontaneous_raman_scattering(self):
+        if self._spontaneous_raman_scattering is None:
+            self.calculate_spontaneous_raman_scattering(self.carriers, self.raman_pumps)
+        return self._spontaneous_raman_scattering
+
+    def calculate_spontaneous_raman_scattering(self, carriers, raman_pumps):
+        raman_efficiency = self.fiber.params.raman_efficiency
+        temperature = self.fiber.operational['temperature']
+
+        logger.debug('Start computing fiber Spontaneous Raman Scattering')
+        power_spectrum, freq_array, prop_direct, bn_array = self._compute_power_spectrum(carriers, raman_pumps)
+
+        alphap_fiber = self.fiber.alpha(freq_array)
+
+        freq_diff = abs(freq_array - reshape(freq_array, (len(freq_array), 1)))
+        interp_cr = interp1d(raman_efficiency['frequency_offset'], raman_efficiency['cr'])
+        cr = interp_cr(freq_diff)
+
+        # z propagation axis
+        z_array = self.stimulated_raman_scattering.z
+        ase_bc = zeros(freq_array.shape)
+
+        # calculate ase power
+        int_spontaneous_raman = self._int_spontaneous_raman(z_array, self._stimulated_raman_scattering.power,
+                                                            alphap_fiber, freq_array, cr, freq_diff, ase_bc,
+                                                            bn_array, temperature)
+
+        spontaneous_raman_scattering = SpontaneousRamanScattering(freq_array, z_array, int_spontaneous_raman.x)
+        logger.debug("Spontaneous Raman Scattering evaluated successfully")
+        self._spontaneous_raman_scattering = spontaneous_raman_scattering
+
+    @staticmethod
+    def _compute_power_spectrum(carriers, raman_pumps=None):
+        """
+        Rearrangement of spectral and Raman pump information to make them compatible with Raman solver
+        :param carriers: a tuple of namedtuples describing the transmitted channels
+        :param raman_pumps: a namedtuple describing the Raman pumps
+        :return:
+        """
+
+        # Signal power spectrum
+        pow_array = array([])
+        f_array = array([])
+        noise_bandwidth_array = array([])
+        for carrier in sorted(carriers, key=attrgetter('frequency')):
+            f_array = append(f_array, carrier.frequency)
+            pow_array = append(pow_array, carrier.power.signal)
+            ref_bw = carrier.baud_rate
+            noise_bandwidth_array = append(noise_bandwidth_array, ref_bw)
+
+        propagation_direction = ones(len(f_array))
+
+        # Raman pump power spectrum
+        if raman_pumps:
+            for pump in raman_pumps:
+                pow_array = append(pow_array, pump.power)
+                f_array = append(f_array, pump.frequency)
+                direction = +1 if pump.propagation_direction.lower() == 'coprop' else -1
+                propagation_direction = append(propagation_direction, direction)
+                noise_bandwidth_array = append(noise_bandwidth_array, ref_bw)
+
+        # Final sorting
+        ind = argsort(f_array)
+        f_array = f_array[ind]
+        pow_array = pow_array[ind]
+        propagation_direction = propagation_direction[ind]
+
+        return pow_array, f_array, propagation_direction, noise_bandwidth_array
+
+    def _int_spontaneous_raman(self, z_array, raman_matrix, alphap_fiber, freq_array,
+                               cr_raman_matrix, freq_diff, ase_bc, bn_array, temperature):
+        spontaneous_raman_scattering = OptimizeResult()
+
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+
+        dx = sim_params.raman_params.space_resolution
+        h = ph.value('Planck constant')
+        kb = ph.value('Boltzmann constant')
+
+        power_ase = nan * ones(raman_matrix.shape)
+        int_pump = cumtrapz(raman_matrix, z_array, dx=dx, axis=1, initial=0)
+
+        for f_ind, f_ase in enumerate(freq_array):
+            cr_raman = cr_raman_matrix[f_ind, :]
+            vibrational_loss = f_ase / freq_array[:f_ind]
+            eta = 1 / (exp((h * freq_diff[f_ind, f_ind + 1:]) / (kb * temperature)) - 1)
+
+            int_fiber_loss = -alphap_fiber[f_ind] * z_array
+            int_raman_loss = sum((cr_raman[:f_ind] * vibrational_loss * int_pump[:f_ind, :].transpose()).transpose(),
+                                    axis=0)
+            int_raman_gain = sum((cr_raman[f_ind + 1:] * int_pump[f_ind + 1:, :].transpose()).transpose(), axis=0)
+
+            int_gain_loss = int_fiber_loss + int_raman_gain + int_raman_loss
+
+            new_ase = sum((cr_raman[f_ind + 1:] * (1 + eta) * raman_matrix[f_ind + 1:, :].transpose()).transpose()
+                             * h * f_ase * bn_array[f_ind], axis=0)
+
+            bc_evolution = ase_bc[f_ind] * exp(int_gain_loss)
+            ase_evolution = exp(int_gain_loss) * cumtrapz(new_ase * exp(-int_gain_loss), z_array, dx=dx, initial=0)
+
+            power_ase[f_ind, :] = bc_evolution + ase_evolution
+
+        spontaneous_raman_scattering.x = 2 * power_ase
+        return spontaneous_raman_scattering
+
+    def calculate_stimulated_raman_scattering(self, carriers, raman_pumps):
+        """ Returns stimulated Raman scattering solution including
+        fiber gain/loss profile.
+        :return: None
+        """
+        # fiber parameters
+        fiber_length = self.fiber.params.length
+        raman_efficiency = self.fiber.params.raman_efficiency
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+
+        if not sim_params.raman_params.flag_raman:
+            raman_efficiency['cr'] = zeros(len(raman_efficiency['cr']))
+        # raman solver parameters
+        z_resolution = sim_params.raman_params.space_resolution
+        tolerance = sim_params.raman_params.tolerance
+
+        logger.debug('Start computing fiber Stimulated Raman Scattering')
+
+        power_spectrum, freq_array, prop_direct, _ = self._compute_power_spectrum(carriers, raman_pumps)
+
+        alphap_fiber = self.fiber.alpha(freq_array)
+
+        freq_diff = abs(freq_array - reshape(freq_array, (len(freq_array), 1)))
+        interp_cr = interp1d(raman_efficiency['frequency_offset'], raman_efficiency['cr'])
+        cr = interp_cr(freq_diff)
+
+        # z propagation axis
+        z = append(arange(0, fiber_length, z_resolution), fiber_length)
+
+        def ode_function(z, p):
+            return self._ode_stimulated_raman(z, p, alphap_fiber, freq_array, cr, prop_direct)
+
+        def boundary_residual(ya, yb):
+            return self._residuals_stimulated_raman(ya, yb, power_spectrum, prop_direct)
+
+        initial_guess_conditions = self._initial_guess_stimulated_raman(z, power_spectrum, alphap_fiber, prop_direct)
+
+        # ODE SOLVER
+        bvp_solution = solve_bvp(ode_function, boundary_residual, z, initial_guess_conditions, tol=tolerance)
+
+        rho = (bvp_solution.y.transpose() / power_spectrum).transpose()
+        rho = sqrt(rho)    # From power attenuation to field attenuation
+        stimulated_raman_scattering = StimulatedRamanScattering(freq_array, bvp_solution.x, rho, bvp_solution.y)
+
+        self._stimulated_raman_scattering = stimulated_raman_scattering
+
+    def _residuals_stimulated_raman(self, ya, yb, power_spectrum, prop_direct):
+
+        computed_boundary_value = zeros(ya.size)
+
+        for index, direction in enumerate(prop_direct):
+            if direction == +1:
+                computed_boundary_value[index] = ya[index]
+            else:
+                computed_boundary_value[index] = yb[index]
+
+        return power_spectrum - computed_boundary_value
+
+    def _initial_guess_stimulated_raman(self, z, power_spectrum, alphap_fiber, prop_direct):
+        """ Computes the initial guess knowing the boundary conditions
+        :param z: patial axis [m]. numpy array
+        :param power_spectrum: power in each frequency slice [W].
+        Frequency axis is defined by freq_array. numpy array
+        :param alphap_fiber: frequency dependent fiber attenuation of signal power [1/m].
+        Frequency defined by freq_array. numpy array
+        :param prop_direct: indicates the propagation direction of each power slice in power_spectrum:
+        +1 for forward propagation and -1 for backward propagation. Frequency defined by freq_array. numpy array
+        :return: power_guess: guess on the initial conditions [W].
+        The first ndarray index identifies the frequency slice,
+        the second ndarray index identifies the step in z. ndarray
+        """
+
+        power_guess = empty((power_spectrum.size, z.size))
+        for f_index, power_slice in enumerate(power_spectrum):
+            if prop_direct[f_index] == +1:
+                power_guess[f_index, :] = exp(-alphap_fiber[f_index] * z) * power_slice
+            else:
+                power_guess[f_index, :] = exp(-alphap_fiber[f_index] * z[::-1]) * power_slice
+
+        return power_guess
+
+    def _ode_stimulated_raman(self, z, power_spectrum, alphap_fiber, freq_array, cr_raman_matrix, prop_direct):
+        """ Aim of ode_raman is to implement the set of ordinary differential equations (ODEs)
+        describing the Raman effect.
+        :param z: spatial axis (unused).
+        :param power_spectrum: power in each frequency slice [W].
+        Frequency axis is defined by freq_array. numpy array. Size n
+        :param alphap_fiber: frequency dependent fiber attenuation of signal power [1/m].
+        Frequency defined by freq_array. numpy array. Size n
+        :param freq_array: reference frequency axis [Hz]. numpy array. Size n
+        :param cr_raman: Cr(f) Raman gain efficiency variation in frequency [1/W/m].
+        Frequency defined by freq_array. numpy ndarray. Size nxn
+        :param prop_direct: indicates the propagation direction of each power slice in power_spectrum:
+        +1 for forward propagation and -1 for backward propagation.
+        Frequency defined by freq_array. numpy array. Size n
+        :return: dP/dz: the power variation in dz [W/m]. numpy array. Size n
+        """
+
+        dpdz = nan * ones(power_spectrum.shape)
+        for f_ind, power in enumerate(power_spectrum):
+            cr_raman = cr_raman_matrix[f_ind, :]
+            vibrational_loss = freq_array[f_ind] / freq_array[:f_ind]
+
+            for z_ind, power_sample in enumerate(power):
+                raman_gain = sum(cr_raman[f_ind + 1:] * power_spectrum[f_ind + 1:, z_ind])
+                raman_loss = sum(vibrational_loss * cr_raman[:f_ind] * power_spectrum[:f_ind, z_ind])
+
+                dpdz_element = prop_direct[f_ind] * (-alphap_fiber[f_ind] + raman_gain - raman_loss) * power_sample
+                dpdz[f_ind][z_ind] = dpdz_element
+
+        return vstack(dpdz)
+
+
+class NliSolver:
+    """ This class implements the NLI models.
+        Model and method can be specified in `sim_params.nli_params.method`.
+        List of implemented methods:
+        'gn_model_analytic': eq. 120 from arXiv:1209.0394
+        'ggn_spectrally_separated_xpm_spm': XPM plus SPM
+    """
+
+    def __init__(self, fiber=None):
+        """ Initialize the Nli solver object.
+        :param fiber: instance of elements.py/Fiber.
+        """
+        self._fiber = fiber
+        self._stimulated_raman_scattering = None
+
+    @property
+    def fiber(self):
+        return self._fiber
+
+    @property
+    def stimulated_raman_scattering(self):
+        return self._stimulated_raman_scattering
+
+    @stimulated_raman_scattering.setter
+    def stimulated_raman_scattering(self, stimulated_raman_scattering):
+        self._stimulated_raman_scattering = stimulated_raman_scattering
+
+    def compute_nli(self, carrier, *carriers):
+        """ Compute NLI power generated by the WDM comb `*carriers` on the channel under test `carrier`
+        at the end of the fiber span.
+        """
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+        if 'gn_model_analytic' == sim_params.nli_params.nli_method_name.lower():
+            carrier_nli = self._gn_analytic(carrier, *carriers)
+        elif 'ggn_spectrally_separated' in sim_params.nli_params.nli_method_name.lower():
+            eta_matrix = self._compute_eta_matrix(carrier, *carriers)
+            carrier_nli = self._carrier_nli_from_eta_matrix(eta_matrix, carrier, *carriers)
+        else:
+            raise ValueError(f'Method {sim_params.nli_params.nli_method_name} not implemented.')
+
+        return carrier_nli
+
+    @staticmethod
+    def _carrier_nli_from_eta_matrix(eta_matrix, carrier, *carriers):
+        carrier_nli = 0
+        for pump_carrier_1 in carriers:
+            for pump_carrier_2 in carriers:
+                carrier_nli += eta_matrix[pump_carrier_1.channel_number - 1, pump_carrier_2.channel_number - 1] * \
+                    pump_carrier_1.power.signal * pump_carrier_2.power.signal
+        carrier_nli *= carrier.power.signal
+
+        return carrier_nli
+
+    def _compute_eta_matrix(self, cut_carrier, *carriers):
+        cut_index = cut_carrier.channel_number - 1
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+        # Matrix initialization
+        matrix_size = max(carriers, key=lambda x: getattr(x, 'channel_number')).channel_number
+        eta_matrix = zeros(shape=(matrix_size, matrix_size))
+
+        # SPM
+        logger.debug(f'Start computing SPM on channel #{cut_carrier.channel_number}')
+        # SPM GGN
+        if 'ggn' in sim_params.nli_params.nli_method_name.lower():
+            partial_nli = self._generalized_spectrally_separated_spm(cut_carrier)
+        # SPM GN
+        elif 'gn' in sim_params.nli_params.nli_method_name.lower():
+            partial_nli = self._gn_analytic(cut_carrier, *[cut_carrier])
+        eta_matrix[cut_index, cut_index] = partial_nli / (cut_carrier.power.signal**3)
+
+        # XPM
+        for pump_carrier in carriers:
+            pump_index = pump_carrier.channel_number - 1
+            if not (cut_index == pump_index):
+                logger.debug(f'Start computing XPM on channel #{cut_carrier.channel_number} '
+                             f'from channel #{pump_carrier.channel_number}')
+                # XPM GGN
+                if 'ggn' in sim_params.nli_params.nli_method_name.lower():
+                    partial_nli = self._generalized_spectrally_separated_xpm(cut_carrier, pump_carrier)
+                # XPM GGN
+                elif 'gn' in sim_params.nli_params.nli_method_name.lower():
+                    partial_nli = self._gn_analytic(cut_carrier, *[pump_carrier])
+                eta_matrix[pump_index, pump_index] = \
+                    partial_nli / (cut_carrier.power.signal * pump_carrier.power.signal**2)
+        return eta_matrix
+
+    # Methods for computing GN-model
+    def _gn_analytic(self, carrier, *carriers):
+        """ Computes the nonlinear interference power on a single carrier.
+        The method uses eq. 120 from arXiv:1209.0394.
+        :param carrier: the signal under analysis
+        :param carriers: the full WDM comb
+        :return: carrier_nli: the amount of nonlinear interference in W on the carrier under analysis
+        """
+        beta2 = self.fiber.params.beta2
+        gamma = self.fiber.params.gamma
+        effective_length = self.fiber.params.effective_length
+        asymptotic_length = self.fiber.params.asymptotic_length
+
+        g_nli = 0
+        for interfering_carrier in carriers:
+            g_interfering = interfering_carrier.power.signal / interfering_carrier.baud_rate
+            g_signal = carrier.power.signal / carrier.baud_rate
+            g_nli += g_interfering**2 * g_signal \
+                * _psi(carrier, interfering_carrier, beta2=beta2, asymptotic_length=asymptotic_length)
+        g_nli *= (16.0 / 27.0) * (gamma * effective_length) ** 2 /\
+                 (2 * pi * abs(beta2) * asymptotic_length)
+        carrier_nli = carrier.baud_rate * g_nli
+        return carrier_nli
+
+    # Methods for computing the GGN-model
+    def _generalized_spectrally_separated_spm(self, carrier):
+        gamma = self.fiber.params.gamma
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+        f_cut_resolution = sim_params.nli_params.f_cut_resolution['delta_0']
+        f_eval = carrier.frequency
+        g_cut = (carrier.power.signal / carrier.baud_rate)
+
+        spm_nli = carrier.baud_rate * (16.0 / 27.0) * gamma ** 2 * g_cut ** 3 * \
+            self._generalized_psi(carrier, carrier, f_eval, f_cut_resolution, f_cut_resolution)
+        return spm_nli
+
+    def _generalized_spectrally_separated_xpm(self, cut_carrier, pump_carrier):
+        gamma = self.fiber.params.gamma
+        simulation = Simulation.get_simulation()
+        sim_params = simulation.sim_params
+        delta_index = pump_carrier.channel_number - cut_carrier.channel_number
+        f_cut_resolution = sim_params.nli_params.f_cut_resolution[f'delta_{delta_index}']
+        f_pump_resolution = sim_params.nli_params.f_pump_resolution
+        f_eval = cut_carrier.frequency
+        g_pump = (pump_carrier.power.signal / pump_carrier.baud_rate)
+        g_cut = (cut_carrier.power.signal / cut_carrier.baud_rate)
+        frequency_offset_threshold = self._frequency_offset_threshold(pump_carrier.baud_rate)
+        if abs(cut_carrier.frequency - pump_carrier.frequency) <= frequency_offset_threshold:
+            xpm_nli = cut_carrier.baud_rate * (16.0 / 27.0) * gamma ** 2 * g_pump**2 * g_cut * \
+                2 * self._generalized_psi(cut_carrier, pump_carrier, f_eval, f_cut_resolution, f_pump_resolution)
+        else:
+            xpm_nli = cut_carrier.baud_rate * (16.0 / 27.0) * gamma ** 2 * g_pump**2 * g_cut * \
+                2 * self._fast_generalized_psi(cut_carrier, pump_carrier, f_eval, f_cut_resolution)
+        return xpm_nli
+
+    def _fast_generalized_psi(self, cut_carrier, pump_carrier, f_eval, f_cut_resolution):
+        """ It computes the generalized psi function similarly to the one used in the GN model
+        :return: generalized_psi
+        """
+        # Fiber parameters
+        alpha0 = self.fiber.alpha0(f_eval)
+        beta2 = self.fiber.params.beta2
+        beta3 = self.fiber.params.beta3
+        f_ref_beta = self.fiber.params.ref_frequency
+        z = self.stimulated_raman_scattering.z
+        frequency_rho = self.stimulated_raman_scattering.frequency
+        rho_norm = self.stimulated_raman_scattering.rho * exp(abs(alpha0) * z / 2)
+        if len(frequency_rho) == 1:
+            def rho_function(f): return rho_norm[0, :]
+        else:
+            rho_function = interp1d(frequency_rho, rho_norm, axis=0, fill_value='extrapolate')
+        rho_norm_pump = rho_function(pump_carrier.frequency)
+
+        f1_array = array([pump_carrier.frequency - (pump_carrier.baud_rate * (1 + pump_carrier.roll_off) / 2),
+                         pump_carrier.frequency + (pump_carrier.baud_rate * (1 + pump_carrier.roll_off) / 2)])
+        f2_array = arange(cut_carrier.frequency,
+                          cut_carrier.frequency + (cut_carrier.baud_rate * (1 + cut_carrier.roll_off) / 2),
+                          f_cut_resolution)  # Only positive f2 is used since integrand_f2 is symmetric
+
+        integrand_f1 = zeros(len(f1_array))
+        for f1_index, f1 in enumerate(f1_array):
+            delta_beta = 4 * pi**2 * (f1 - f_eval) * (f2_array - f_eval) * \
+                (beta2 + pi * beta3 * (f1 + f2_array - 2 * f_ref_beta))
+            integrand_f2 = self._generalized_rho_nli(delta_beta, rho_norm_pump, z, alpha0)
+            integrand_f1[f1_index] = 2 * trapz(integrand_f2, f2_array)  # 2x since integrand_f2 is symmetric in f2
+        generalized_psi = 0.5 * sum(integrand_f1) * pump_carrier.baud_rate
+        return generalized_psi
+
+    def _generalized_psi(self, cut_carrier, pump_carrier, f_eval, f_cut_resolution, f_pump_resolution):
+        """ It computes the generalized psi function similarly to the one used in the GN model
+        :return: generalized_psi
+        """
+        # Fiber parameters
+        alpha0 = self.fiber.alpha0(f_eval)
+        beta2 = self.fiber.params.beta2
+        beta3 = self.fiber.params.beta3
+        f_ref_beta = self.fiber.params.ref_frequency
+        z = self.stimulated_raman_scattering.z
+        frequency_rho = self.stimulated_raman_scattering.frequency
+        rho_norm = self.stimulated_raman_scattering.rho * exp(abs(alpha0) * z / 2)
+        if len(frequency_rho) == 1:
+            def rho_function(f): return rho_norm[0, :]
+        else:
+            rho_function = interp1d(frequency_rho, rho_norm, axis=0, fill_value='extrapolate')
+        rho_norm_pump = rho_function(pump_carrier.frequency)
+
+        f1_array = arange(pump_carrier.frequency - (pump_carrier.baud_rate * (1 + pump_carrier.roll_off) / 2),
+                          pump_carrier.frequency + (pump_carrier.baud_rate * (1 + pump_carrier.roll_off) / 2),
+                          f_pump_resolution)
+        f2_array = arange(cut_carrier.frequency - (cut_carrier.baud_rate * (1 + cut_carrier.roll_off) / 2),
+                          cut_carrier.frequency + (cut_carrier.baud_rate * (1 + cut_carrier.roll_off) / 2),
+                          f_cut_resolution)
+        psd1 = raised_cosine_comb(f1_array, pump_carrier) * (pump_carrier.baud_rate / pump_carrier.power.signal)
+
+        integrand_f1 = zeros(len(f1_array))
+        for f1_index, (f1, psd1_sample) in enumerate(zip(f1_array, psd1)):
+            f3_array = f1 + f2_array - f_eval
+            psd2 = raised_cosine_comb(f2_array, cut_carrier) * (cut_carrier.baud_rate / cut_carrier.power.signal)
+            psd3 = raised_cosine_comb(f3_array, pump_carrier) * (pump_carrier.baud_rate / pump_carrier.power.signal)
+            ggg = psd1_sample * psd2 * psd3
+
+            delta_beta = 4 * pi**2 * (f1 - f_eval) * (f2_array - f_eval) * \
+                (beta2 + pi * beta3 * (f1 + f2_array - 2 * f_ref_beta))
+
+            integrand_f2 = ggg * self._generalized_rho_nli(delta_beta, rho_norm_pump, z, alpha0)
+            integrand_f1[f1_index] = trapz(integrand_f2, f2_array)
+        generalized_psi = trapz(integrand_f1, f1_array)
+        return generalized_psi
+
+    @staticmethod
+    def _generalized_rho_nli(delta_beta, rho_norm_pump, z, alpha0):
+        w = 1j * delta_beta - alpha0
+        generalized_rho_nli = (rho_norm_pump[-1]**2 * exp(w * z[-1]) - rho_norm_pump[0]**2 * exp(w * z[0])) / w
+        for z_ind in range(0, len(z) - 1):
+            derivative_rho = (rho_norm_pump[z_ind + 1]**2 - rho_norm_pump[z_ind]**2) / (z[z_ind + 1] - z[z_ind])
+            generalized_rho_nli -= derivative_rho * (exp(w * z[z_ind + 1]) - exp(w * z[z_ind])) / (w**2)
+        generalized_rho_nli = abs(generalized_rho_nli)**2
+        return generalized_rho_nli
+
+    def _frequency_offset_threshold(self, symbol_rate):
+        k_ref = 5
+        beta2_ref = 21.3e-27
+        delta_f_ref = 50e9
+        rs_ref = 32e9
+        beta2 = abs(self.fiber.params.beta2)
+        freq_offset_th = ((k_ref * delta_f_ref) * rs_ref * beta2_ref) / (beta2 * symbol_rate)
+        return freq_offset_th
+
+
+def _psi(carrier, interfering_carrier, beta2, asymptotic_length):
+    """Calculates eq. 123 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__"""
+    if carrier.channel_number == interfering_carrier.channel_number:  # SCI, SPM
+        psi = arcsinh(0.5 * pi**2 * asymptotic_length * abs(beta2) * carrier.baud_rate**2)
+    else:  # XCI, XPM
+        delta_f = carrier.frequency - interfering_carrier.frequency
+        psi = arcsinh(pi**2 * asymptotic_length * abs(beta2) *
+                      carrier.baud_rate * (delta_f + 0.5 * interfering_carrier.baud_rate))
+        psi -= arcsinh(pi**2 * asymptotic_length * abs(beta2) *
+                       carrier.baud_rate * (delta_f - 0.5 * interfering_carrier.baud_rate))
+    return psi
+
+
+def estimate_nf_model(type_variety, gain_min, gain_max, nf_min, nf_max):
+    if nf_min < -10:
+        raise EquipmentConfigError(f'Invalid nf_min value {nf_min!r} for amplifier {type_variety}')
+    if nf_max < -10:
+        raise EquipmentConfigError(f'Invalid nf_max value {nf_max!r} for amplifier {type_variety}')
+
+    # NF estimation model based on nf_min and nf_max
+    # delta_p:  max power dB difference between first and second stage coils
+    # dB g1a:   first stage gain - internal VOA attenuation
+    # nf1, nf2: first and second stage coils
+    #           calculated by solving nf_{min,max} = nf1 + nf2 / g1a{min,max}
+    delta_p = 5
+    g1a_min = gain_min - (gain_max - gain_min) - delta_p
+    g1a_max = gain_max - delta_p
+    nf2 = lin2db((db2lin(nf_min) - db2lin(nf_max)) /
+                 (1 / db2lin(g1a_max) - 1 / db2lin(g1a_min)))
+    nf1 = lin2db(db2lin(nf_min) - db2lin(nf2) / db2lin(g1a_max))
+
+    if nf1 < 4:
+        raise EquipmentConfigError(f'First coil value too low {nf1} for amplifier {type_variety}')
+
+    # Check 1 dB < delta_p < 6 dB to ensure nf_min and nf_max values make sense.
+    # There shouldn't be high nf differences between the two coils:
+    #    nf2 should be nf1 + 0.3 < nf2 < nf1 + 2
+    # If not, recompute and check delta_p
+    if not nf1 + 0.3 < nf2 < nf1 + 2:
+        nf2 = clip(nf2, nf1 + 0.3, nf1 + 2)
+        g1a_max = lin2db(db2lin(nf2) / (db2lin(nf_min) - db2lin(nf1)))
+        delta_p = gain_max - g1a_max
+        g1a_min = gain_min - (gain_max - gain_min) - delta_p
+        if not 1 < delta_p < 11:
+            raise EquipmentConfigError(f'Computed \N{greek capital letter delta}P invalid \
+                \n 1st coil vs 2nd coil calculated DeltaP {delta_p:.2f} for \
+                \n amplifier {type_variety} is not valid: revise inputs \
+                \n calculated 1st coil NF = {nf1:.2f}, 2nd coil NF = {nf2:.2f}')
+    # Check calculated values for nf1 and nf2
+    calc_nf_min = lin2db(db2lin(nf1) + db2lin(nf2) / db2lin(g1a_max))
+    if not isclose(nf_min, calc_nf_min, abs_tol=0.01):
+        raise EquipmentConfigError(f'nf_min does not match calc_nf_min, {nf_min} vs {calc_nf_min} for amp {type_variety}')
+    calc_nf_max = lin2db(db2lin(nf1) + db2lin(nf2) / db2lin(g1a_min))
+    if not isclose(nf_max, calc_nf_max, abs_tol=0.01):
+        raise EquipmentConfigError(f'nf_max does not match calc_nf_max, {nf_max} vs {calc_nf_max} for amp {type_variety}')
+
+    return nf1, nf2, delta_p

gnpy/core/service_sheet.py

@@ -1,256 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-gnpy.core.service_sheet
-========================
-
-XLS parser that can be called to create a JSON request file in accordance with
-Yang model for requesting path computation.
-
-See: draft-ietf-teas-yang-path-computation-01.txt
-"""
-
-from sys import exit
-try:
-    from xlrd import open_workbook, XL_CELL_EMPTY
-except ModuleNotFoundError:
-    exit('Required: `pip install xlrd`')
-from collections import namedtuple
-from logging import getLogger, basicConfig, CRITICAL, DEBUG, INFO
-from json import dumps
-from pathlib import Path
-from gnpy.core.equipment import load_equipment
-from gnpy.core.utils import db2lin, lin2db
-
-SERVICES_COLUMN = 12
-#EQPT_LIBRARY_FILENAME = Path(__file__).parent / 'eqpt_config.json'
-
-all_rows = lambda sheet, start=0: (sheet.row(x) for x in range(start, sheet.nrows))
-logger = getLogger(__name__)
-
-# Type for input data
-class Request(namedtuple('Request', 'request_id source destination trx_type mode \
-    spacing power nb_channel disjoint_from nodes_list is_loose path_bandwidth')):
-    def __new__(cls, request_id, source, destination, trx_type,  mode=None , spacing= None , power = None, nb_channel = None , disjoint_from ='' ,  nodes_list = None, is_loose = '', path_bandwidth = None):
-        return super().__new__(cls, request_id, source, destination, trx_type, mode, spacing, power, nb_channel, disjoint_from,  nodes_list, is_loose, path_bandwidth)
-
-# Type for output data:  // from dutc
-class Element:
-    def __eq__(self, other):
-        return type(self) == type(other) and self.uid == other.uid
-    def __hash__(self):
-        return hash((type(self), self.uid))
-
-class Request_element(Element):
-    def __init__(self,Request,eqpt_filename):
-        # request_id is str
-        # excel has automatic number formatting that adds .0 on integer values
-        # the next lines recover the pure int value, assuming this .0 is unwanted
-        self.request_id = correct_xlrd_int_to_str_reading(Request.request_id)
-        self.source = Request.source
-        self.destination = Request.destination
-        # TODO: the automatic naming generated by excel parser requires that source and dest name 
-        # be a string starting with 'trx' : this is manually added here.
-        self.srctpid = f'trx {Request.source}'
-        self.dsttpid = f'trx {Request.destination}'
-        # test that trx_type belongs to eqpt_config.json
-        # if not replace it with a default
-        equipment = load_equipment(eqpt_filename)
-        try :
-            if equipment['Transceiver'][Request.trx_type]:
-                self.trx_type = correct_xlrd_int_to_str_reading(Request.trx_type)
-            if Request.mode is not None :
-                Requestmode = correct_xlrd_int_to_str_reading(Request.mode)
-                if [mode for mode in equipment['Transceiver'][Request.trx_type].mode if mode['format'] == Requestmode]:
-                    self.mode = Requestmode
-                else : 
-                    msg = f'Request Id: {self.request_id} - could not find tsp : \'{Request.trx_type}\' with mode: \'{Requestmode}\' in eqpt library \nComputation stopped.'
-                    #print(msg)
-                    logger.critical(msg)
-                    exit(1)
-            else:
-                Requestmode = None
-                self.mode = Request.mode
-        except KeyError:
-            msg = f'Request Id: {self.request_id} - could not find tsp : \'{Request.trx_type}\' with mode: \'{Requestmode}\' in eqpt library \nComputation stopped.'
-            #print(msg)
-            logger.critical(msg)
-            exit()
-        # excel input are in GHz and dBm
-        if Request.spacing is not None:
-            self.spacing = Request.spacing * 1e9
-        else:
-            msg = f'Request {self.request_id} missing spacing: spacing is mandatory.\ncomputation stopped'
-            logger.critical(msg)
-            exit()
-        if Request.power is not None:
-            self.power =  db2lin(Request.power) * 1e-3
-        else:
-            self.power = None
-        if Request.nb_channel is not None :
-            self.nb_channel = int(Request.nb_channel)
-        else:
-            self.nb_channel = None
-        
-        value = correct_xlrd_int_to_str_reading(Request.disjoint_from)
-        self.disjoint_from = [n for n in value.split(' | ') if value]
-        self.nodes_list = []
-        if Request.nodes_list :
-            self.nodes_list = Request.nodes_list.split(' | ')
-
-        # cleaning the list of nodes to remove source and destination
-        # (because the remaining of the program assumes that the nodes list are nodes 
-        # on the path and should not include source and destination)
-        try :
-            self.nodes_list.remove(self.source)
-            msg = f'{self.source} removed from explicit path node-list'
-            logger.info(msg)
-        except ValueError:
-            msg = f'{self.source} already removed from explicit path node-list'
-            logger.info(msg)
-
-        try :
-            self.nodes_list.remove(self.destination)
-            msg = f'{self.destination} removed from explicit path node-list'
-            logger.info(msg)
-        except ValueError:
-            msg = f'{self.destination} already removed from explicit path node-list'
-            logger.info(msg)
-
-        # the excel parser applies the same hop-type to all nodes in the route nodes_list.
-        # user can change this per node in the generated json
-        self.loose = 'loose'
-        if Request.is_loose == 'no' :
-            self.loose = 'strict'
-        self.path_bandwidth = None
-        if Request.path_bandwidth is not None:
-            self.path_bandwidth = Request.path_bandwidth * 1e9
-        else:
-            self.path_bandwidth = 0
-
-    uid = property(lambda self: repr(self))
-    @property
-    def pathrequest(self):
-        req_dictionnary = {
-                    'request-id':self.request_id,
-                    'source':    self.source,
-                    'destination':  self.destination,
-                    'src-tp-id': self.srctpid,
-                    'dst-tp-id': self.dsttpid,
-                    'path-constraints':{
-                        'te-bandwidth': {
-                            'technology': 'flexi-grid',
-                            'trx_type'  : self.trx_type,
-                            'trx_mode'  : self.mode,
-                            'effective-freq-slot':[{'n': 'null','m': 'null'}] ,
-                            'spacing'   : self.spacing,
-                            'max-nb-of-channel'  : self.nb_channel,
-                            'output-power'       : self.power
-                            # 'path_bandwidth'       : self.path_bandwidth 
-                        }
-                    },
-                    'optimizations': {
-                        'explicit-route-include-objects': [
-                        {
-                            'index': self.nodes_list.index(node),
-                            'unnumbered-hop':{
-                                'node-id': f'{node}',
-                                'link-tp-id': 'link-tp-id is not used',
-                                'hop-type': f'{self.loose}',
-                                'direction': 'direction is not used'
-                            },
-                            'label-hop':{
-                                'te-label': {
-                                    'generic': 'generic is not used',
-                                    'direction': 'direction is not used'
-                                }
-                            }
-                        }
-                        for node in self.nodes_list
-                    ]
-
-                }
-            }
-        if self.path_bandwidth is not None:
-            req_dictionnary['path-constraints']['te-bandwidth']['path_bandwidth'] = self.path_bandwidth
-            
-        return req_dictionnary
-    @property
-    def pathsync(self):
-        if self.disjoint_from :
-            return {'synchronization-id':self.request_id,
-                'svec': {
-                    'relaxable' : 'False',
-                    'link-diverse': 'True',
-                    'node-diverse': 'True',
-                    'request-id-number': [self.request_id]+ [n for n in self.disjoint_from]
-                }
-            }
-        # TO-DO: avoid multiple entries with same synchronisation vectors
-    @property
-    def json(self):
-        return self.pathrequest , self.pathsync
-
-def convert_service_sheet(input_filename, eqpt_filename, output_filename='', filter_region=[]):
-    service = parse_excel(input_filename)
-    req = [Request_element(n,eqpt_filename) for n in service]
-    # dumps the output into a json file with name
-    # split_filename = [input_filename[0:len(input_filename)-len(suffix_filename)] , suffix_filename[1:]]
-    if output_filename=='':
-        output_filename = f'{str(input_filename)[0:len(str(input_filename))-len(str(input_filename.suffixes[0]))]}_services.json'
-    # for debug
-    # print(json_filename)
-    data = {
-        'path-request': [n.json[0] for n in req],
-        'synchronization': [n.json[1] for n in req
-        if n.json[1] is not None]
-    }
-    with open(output_filename, 'w', encoding='utf-8') as f:
-            f.write(dumps(data, indent=2, ensure_ascii=False))
-    return data
-
-def correct_xlrd_int_to_str_reading(v) :
-    if not isinstance(v,str):
-        value = str(int(v))
-        if value.endswith('.0'):
-            value = value[:-2]
-    else:
-        value = v
-    return value
-
-# to be used from dutc
-def parse_row(row, fieldnames):
-    return {f: r.value for f, r in zip(fieldnames, row[0:SERVICES_COLUMN])
-            if r.ctype != XL_CELL_EMPTY}
-#
-
-def parse_excel(input_filename):
-    with open_workbook(input_filename) as wb:
-        service_sheet = wb.sheet_by_name('Service')
-        services = list(parse_service_sheet(service_sheet))
-    return services
-
-def parse_service_sheet(service_sheet):
-        logger.info(f'Validating headers on {service_sheet.name!r}')
-        # add a test on field to enable the '' field case that arises when columns on the 
-        # right hand side are used as comments or drawing in the excel sheet
-        header = [x.value.strip() for x in service_sheet.row(4)[0:SERVICES_COLUMN] if len(x.value.strip())>0]
-
-        # create a service_fieldname independant from the excel column order
-        # to be compatible with any version of the sheet
-        # the following dictionnary records the excel field names and the corresponding parameter's name
-
-        authorized_fieldnames = {'route id':'request_id', 'Source':'source', 'Destination':'destination', \
-         'TRX type':'trx_type', 'Mode' : 'mode', 'System: spacing':'spacing', \
-         'System: input power (dBm)':'power', 'System: nb of channels':'nb_channel',\
-         'routing: disjoint from': 'disjoint_from', 'routing: path':'nodes_list',\
-         'routing: is loose?':'is_loose', 'path bandwidth':'path_bandwidth'}
-        try :
-            service_fieldnames = [authorized_fieldnames[e] for e in header]
-        except KeyError:
-            msg = f'Malformed header on Service sheet: {header} field not in {authorized_fieldnames}'
-            logger.critical(msg)
-            raise ValueError(msg)
-        for row in all_rows(service_sheet, start=5):
-            yield Request(**parse_row(row[0:SERVICES_COLUMN], service_fieldnames))

gnpy/core/units.py

@@ -1,5 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-UNITS = {'m': 1,
-         'km': 1E3}

gnpy/core/utils.py

@@ -1,38 +1,26 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-'''
+"""
 gnpy.core.utils
 ===============
 
 This module contains utility functions that are used with gnpy.
-'''
+"""
 
-
-import json
-
-import numpy as np
 from csv import writer
-from numpy import pi, cos, sqrt, log10
+from numpy import pi, cos, sqrt, log10, linspace, zeros, shape, where, logical_and
 from scipy import constants
 
+from gnpy.core.exceptions import ConfigurationError
 
-def load_json(filename):
-    with open(filename, 'r', encoding='utf-8') as f:
-        data = json.load(f)
-    return data
-
-
-def save_json(obj, filename):
-    with open(filename, 'w', encoding='utf-8') as f:
-        json.dump(obj, f, indent=2, ensure_ascii=False)
 
 def write_csv(obj, filename):
     """
-    convert dictionary items to a csv file
-    the dictionary format :
+    Convert dictionary items to a CSV file the dictionary format:
+    ::
 
-    {'result category 1':
+        {'result category 1':
                         [
                         # 1st line of results
                         {'header 1' : value_xxx,
@@ -41,68 +29,83 @@ def write_csv(obj, filename):
                         {'header 1' : value_www,
                          'header 2' : value_zzz}
                         ],
-    'result_category 2':
+        'result_category 2':
                         [
                         {},{}
                         ]
-    }
+        }
 
-    the generated csv file will be:
-    result_category 1
-    header 1    header 2
-    value_xxx   value_yyy
-    value_www   value_zzz
-    result_category 2
-    ...
+    The generated csv file will be:
+    ::
+
+        result_category 1
+        header 1    header 2
+        value_xxx   value_yyy
+        value_www   value_zzz
+        result_category 2
+        ...
     """
     with open(filename, 'w', encoding='utf-8') as f:
         w = writer(f)
         for data_key, data_list in obj.items():
-            #main header
+            # main header
             w.writerow([data_key])
-            #sub headers:
+            # sub headers:
             headers = [_ for _ in data_list[0].keys()]
             w.writerow(headers)
             for data_dict in data_list:
                 w.writerow([_ for _ in data_dict.values()])
 
-def c():
-    """
-    Returns the speed of light in meters per second
-    """
-    return constants.c
 
+def arrange_frequencies(length, start, stop):
+    """Create an array of frequencies
 
-def itufs(spacing, startf=191.35, stopf=196.10):
-    """Creates an array of frequencies whose default range is
-    191.35-196.10 THz
-
-    :param spacing: Frequency spacing in THz
-    :param starf: Start frequency in THz
-    :param stopf: Stop frequency in THz
-    :type spacing: float
-    :type startf: float
-    :type stopf: float
-    :return an array of frequnecies determined by the spacing parameter
+    :param length: number of elements
+    :param start: Start frequency in THz
+    :param stop: Stop frequency in THz
+    :type length: integer
+    :type start: float
+    :type stop: float
+    :return: an array of frequencies determined by the spacing parameter
     :rtype: numpy.ndarray
     """
-    return np.arange(startf, stopf + spacing / 2, spacing)
-
-
-def h():
-    """
-    Returns plank's constant in J*s
-    """
-    return constants.h
+    return linspace(start, stop, length)
 
 
 def lin2db(value):
+    """Convert linear unit to logarithmic (dB)
+
+    >>> lin2db(0.001)
+    -30.0
+    >>> round(lin2db(1.0), 2)
+    0.0
+    >>> round(lin2db(1.26), 2)
+    1.0
+    >>> round(lin2db(10.0), 2)
+    10.0
+    >>> round(lin2db(100.0), 2)
+    20.0
+    """
     return 10 * log10(value)
 
 
 def db2lin(value):
+    """Convert logarithimic units to linear
+
+    >>> round(db2lin(10.0), 2)
+    10.0
+    >>> round(db2lin(20.0), 2)
+    100.0
+    >>> round(db2lin(1.0), 2)
+    1.26
+    >>> round(db2lin(0.0), 2)
+    1.0
+    >>> round(db2lin(-10.0), 2)
+    0.1
+    """
     return 10**(value / 10)
 
+
 def round2float(number, step):
     step = round(step, 1)
     if step >= 0.01:
@@ -112,19 +115,28 @@ def round2float(number, step):
         number = round(number, 2)
     return number
 
+
 wavelength2freq = constants.lambda2nu
 freq2wavelength = constants.nu2lambda
 
+
 def freq2wavelength(value):
     """ Converts frequency units to wavelength units.
+
+    >>> round(freq2wavelength(191.35e12) * 1e9, 3)
+    1566.723
+    >>> round(freq2wavelength(196.1e12) * 1e9, 3)
+    1528.773
     """
-    return c() / value
+    return constants.c / value
+
 
 def snr_sum(snr, bw, snr_added, bw_added=12.5e9):
-    snr_added = snr_added - lin2db(bw/bw_added)
-    snr = -lin2db(db2lin(-snr)+db2lin(-snr_added))
+    snr_added = snr_added - lin2db(bw / bw_added)
+    snr = -lin2db(db2lin(-snr) + db2lin(-snr_added))
     return snr
 
+
 def deltawl2deltaf(delta_wl, wavelength):
     """ deltawl2deltaf(delta_wl, wavelength):
     delta_wl is BW in wavelength units
@@ -177,11 +189,109 @@ def rrc(ffs, baud_rate, alpha):
     Ts = 1 / baud_rate
     l_lim = (1 - alpha) / (2 * Ts)
     r_lim = (1 + alpha) / (2 * Ts)
-    hf = np.zeros(np.shape(ffs))
-    slope_inds = np.where(
-        np.logical_and(np.abs(ffs) > l_lim, np.abs(ffs) < r_lim))
+    hf = zeros(shape(ffs))
+    slope_inds = where(
+        logical_and(abs(ffs) > l_lim, abs(ffs) < r_lim))
     hf[slope_inds] = 0.5 * (1 + cos((pi * Ts / alpha) *
-                                    (np.abs(ffs[slope_inds]) - l_lim)))
-    p_inds = np.where(np.logical_and(np.abs(ffs) > 0, np.abs(ffs) < l_lim))
+                                    (abs(ffs[slope_inds]) - l_lim)))
+    p_inds = where(logical_and(abs(ffs) > 0, abs(ffs) < l_lim))
     hf[p_inds] = 1
     return sqrt(hf)
+
+
+def merge_amplifier_restrictions(dict1, dict2):
+    """Updates contents of dicts recursively
+
+    >>> d1 = {'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}}}
+    >>> d2 = {'params': {'target_pch_out_db': -20}}
+    >>> merge_amplifier_restrictions(d1, d2)
+    {'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}, 'target_pch_out_db': -20}}
+
+    >>> d3 = {'params': {'restrictions': {'preamp_variety_list': ['foo'], 'booster_variety_list': ['bar']}}}
+    >>> merge_amplifier_restrictions(d1, d3)
+    {'params': {'restrictions': {'preamp_variety_list': [], 'booster_variety_list': []}}}
+    """
+
+    copy_dict1 = dict1.copy()
+    for key in dict2:
+        if key in dict1:
+            if isinstance(dict1[key], dict):
+                copy_dict1[key] = merge_amplifier_restrictions(copy_dict1[key], dict2[key])
+        else:
+            copy_dict1[key] = dict2[key]
+    return copy_dict1
+
+
+def silent_remove(this_list, elem):
+    """Remove matching elements from a list without raising ValueError
+
+    >>> li = [0, 1]
+    >>> li = silent_remove(li, 1)
+    >>> li
+    [0]
+    >>> li = silent_remove(li, 1)
+    >>> li
+    [0]
+    """
+
+    try:
+        this_list.remove(elem)
+    except ValueError:
+        pass
+    return this_list
+
+
+def automatic_nch(f_min, f_max, spacing):
+    """How many channels are available in the spectrum
+
+    :param f_min Lowest frequenecy [Hz]
+    :param f_max Highest frequency [Hz]
+    :param spacing Channel width [Hz]
+    :return Number of uniform channels
+
+    >>> automatic_nch(191.325e12, 196.125e12, 50e9)
+    96
+    >>> automatic_nch(193.475e12, 193.525e12, 50e9)
+    1
+    """
+    return int((f_max - f_min) // spacing)
+
+
+def automatic_fmax(f_min, spacing, nch):
+    """Find the high-frequenecy boundary of a spectrum
+
+    :param f_min Start of the spectrum (lowest frequency edge) [Hz]
+    :param spacing Grid/channel spacing [Hz]
+    :param nch Number of channels
+    :return End of the spectrum (highest frequency) [Hz]
+
+    >>> automatic_fmax(191.325e12, 50e9, 96)
+    196125000000000.0
+    """
+    return f_min + spacing * nch
+
+
+def convert_length(value, units):
+    """Convert length into basic SI units
+
+    >>> convert_length(1, 'km')
+    1000.0
+    >>> convert_length(2.0, 'km')
+    2000.0
+    >>> convert_length(123, 'm')
+    123.0
+    >>> convert_length(123.0, 'm')
+    123.0
+    >>> convert_length(42.1, 'km')
+    42100.0
+    >>> convert_length(666, 'yards')
+    Traceback (most recent call last):
+        ...
+    gnpy.core.exceptions.ConfigurationError: Cannot convert length in "yards" into meters
+    """
+    if units == 'm':
+        return value * 1e0
+    elif units == 'km':
+        return value * 1e3
+    else:
+        raise ConfigurationError(f'Cannot convert length in "{units}" into meters')

gnpy/example-data/Juniper-BoosterHG.json

@@ -0,0 +1,160 @@
+{
+    "nf_fit_coeff": [
+        0.0008,
+        0.0272,
+        -0.2249,
+        6.4902
+    ],
+    "f_min": 191.4e12,
+    "f_max": 196.1e12,
+    "nf_ripple": [
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0
+    ],
+    "gain_ripple": [
+        -0.15656302345061,
+        -0.22244242043552,
+        -0.25188965661642,
+        -0.23575900335007,
+        -0.20897508375209,
+        -0.19440221943049,
+        -0.18324644053602,
+        -0.18053287269681,
+        -0.17113588777219,
+        -0.15460322445561,
+        -0.13550774706866,
+        -0.10606051088777,
+        -0.0765630234506,
+        -0.04962835008375,
+        -0.01319618927973,
+        0.01027114740367,
+        0.03378873534338,
+        0.04961788107202,
+        0.04494451423784,
+        0.0399193886097,
+        0.01584903685091,
+        -0.00420121440538,
+        -0.01847257118928,
+        -0.02475397822447,
+        -0.01053287269681,
+        0.01509526800668,
+        0.05921587102177,
+        0.1191656197655,
+        0.18147717755444,
+        0.23579878559464,
+        0.26941687604691,
+        0.27836159966498,
+        0.26956762981574,
+        0.23826109715241,
+        0.18936662479061,
+        0.1204721524288,
+        0.0453465242881,
+        -0.00877407872698,
+        -0.02199015912898,
+        0.00107516750419,
+        0.02795958961474,
+        0.02740682579566,
+        -0.01028161641541,
+        -0.05982935510889,
+        -0.06701528475711,
+        0.00223094639866,
+        0.14157768006701,
+        0.15017064489112
+    ],
+    "dgt": [
+        1.0,
+        1.03941448941778,
+        1.07773189112355,
+        1.11575888725852,
+        1.15209185089701,
+        1.18632744096844,
+        1.21911100318577,
+        1.24931318255134,
+        1.27657903892303,
+        1.30069883494415,
+        1.32210817897091,
+        1.3405812000038,
+        1.35690844654118,
+        1.3710092503689,
+        1.38430337205545,
+        1.3966294751726,
+        1.40864903907609,
+        1.42089447397912,
+        1.43476940680732,
+        1.44977369463316,
+        1.46637521309853,
+        1.48420288841848,
+        1.50335352244996,
+        1.5242627235492,
+        1.54578500307573,
+        1.56750088631614,
+        1.58973304612691,
+        1.61073904908309,
+        1.63068023161292,
+        1.64799163036252,
+        1.66286684904577,
+        1.6761448370895,
+        1.68845480656382,
+        1.70379790088896,
+        1.72461030013125,
+        1.75428006928365,
+        1.79748596476494,
+        1.85543800978691,
+        1.92915262384742,
+        2.01414465424155,
+        2.10336369905543,
+        2.19013043016015,
+        2.26678136721453,
+        2.33147727493671,
+        2.38192717604575,
+        2.41879254989742,
+        2.44342862248888,
+        2.4553191172498
+    ]
+}

gnpy/example-data/create_eqpt_sheet.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+create_eqpt_sheet.py
+====================
+
+XLS parser that can be called to create a "City" column in the "Eqpt" sheet.
+
+If not present in the "Nodes" sheet, the "Type" column will be implicitly
+determined based on the topology.
+"""
+
+from xlrd import open_workbook
+from argparse import ArgumentParser
+
+PARSER = ArgumentParser()
+PARSER.add_argument('workbook', nargs='?', default='meshTopologyExampleV2.xls',
+                    help='create the mandatory columns in Eqpt sheet')
+
+
+def ALL_ROWS(sh, start=0):
+    return (sh.row(x) for x in range(start, sh.nrows))
+
+
+class Node:
+    """ Node element contains uid, list of connected nodes and eqpt type
+    """
+
+    def __init__(self, uid, to_node):
+        self.uid = uid
+        self.to_node = to_node
+        self.eqpt = None
+
+    def __repr__(self):
+        return f'uid {self.uid} \nto_node {[node for node in self.to_node]}\neqpt {self.eqpt}\n'
+
+    def __str__(self):
+        return f'uid {self.uid} \nto_node {[node for node in self.to_node]}\neqpt {self.eqpt}\n'
+
+
+def read_excel(input_filename):
+    """ read excel Nodes and Links sheets and create a dict of nodes with
+    their to_nodes and type of eqpt
+    """
+    with open_workbook(input_filename) as wobo:
+        # reading Links sheet
+        links_sheet = wobo.sheet_by_name('Links')
+        nodes = {}
+        for row in ALL_ROWS(links_sheet, start=5):
+            try:
+                nodes[row[0].value].to_node.append(row[1].value)
+            except KeyError:
+                nodes[row[0].value] = Node(row[0].value, [row[1].value])
+            try:
+                nodes[row[1].value].to_node.append(row[0].value)
+            except KeyError:
+                nodes[row[1].value] = Node(row[1].value, [row[0].value])
+
+        nodes_sheet = wobo.sheet_by_name('Nodes')
+        for row in ALL_ROWS(nodes_sheet, start=5):
+            node = row[0].value
+            eqpt = row[6].value
+            try:
+                if eqpt == 'ILA' and len(nodes[node].to_node) != 2:
+                    print(f'Inconsistancy ILA node with degree > 2: {node} ')
+                    exit()
+                if eqpt == '' and len(nodes[node].to_node) == 2:
+                    nodes[node].eqpt = 'ILA'
+                elif eqpt == '' and len(nodes[node].to_node) != 2:
+                    nodes[node].eqpt = 'ROADM'
+                else:
+                    nodes[node].eqpt = eqpt
+            except KeyError:
+                print(f'inconsistancy between nodes and links sheet: {node} is not listed in links')
+                exit()
+        return nodes
+
+
+def create_eqt_template(nodes, input_filename):
+    """ writes list of node A node Z corresponding to Nodes and Links sheets in order
+    to help user populating Eqpt
+    """
+    output_filename = f'{input_filename[:-4]}_eqpt_sheet.txt'
+    with open(output_filename, 'w', encoding='utf-8') as my_file:
+        # print header similar to excel
+        my_file.write('OPTIONAL\n\n\n\
+           \t\tNode a egress amp (from a to z)\t\t\t\t\tNode a ingress amp (from z to a) \
+           \nNode A \tNode Z \tamp type \tatt_in \tamp gain \ttilt \tatt_out\
+           amp type   \tatt_in \tamp gain   \ttilt   \tatt_out\n')
+
+        for node in nodes.values():
+            if node.eqpt == 'ILA':
+                my_file.write(f'{node.uid}\t{node.to_node[0]}\n')
+            if node.eqpt == 'ROADM':
+                for to_node in node.to_node:
+                    my_file.write(f'{node.uid}\t{to_node}\n')
+
+        print(f'File {output_filename} successfully created with Node A - Node Z entries for Eqpt sheet in excel file.')
+
+
+if __name__ == '__main__':
+    ARGS = PARSER.parse_args()
+    create_eqt_template(read_excel(ARGS.workbook), ARGS.workbook)

gnpy/example-data/default_edfa_config.json

@@ -1,296 +1,106 @@
 {
     "nf_ripple": [
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
         0.0
     ],
     "gain_ripple": [
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
-        0.0,
         0.0
     ],
     "dgt": [
-        2.714526681131686,
-        2.705443819238505,
-        2.6947834587664494,
-        2.6841217449620203,
-        2.6681935771243177,
-        2.6521732021128046,
-        2.630396440815385,
-        2.602860350286428,
-        2.5696460593920065,
-        2.5364027376452056,
-        2.499446286796604,
-        2.4587748041127506,
-        2.414398437185221,
-        2.3699990328716107,
-        2.322373696229342,
-        2.271520771371253,
-        2.2174389328192197,
-        2.16337565384239,
-        2.1183028432496016,
-        2.082225099873648,
-        2.055100772005235,
-        2.0279625371819305,
-        2.0008103857988204,
-        1.9736443063300082,
-        1.9482128147680253,
-        1.9245345552113182,
-        1.9026104247588487,
-        1.8806927939516411,
-        1.862235672444246,
-        1.847275503201129,
-        1.835814081380705,
-        1.824381436842932,
-        1.8139629377087627,
-        1.8045606557581335,
-        1.7961751115773796,
-        1.7877868031023945,
-        1.7793941781790852,
-        1.7709972329654864,
-        1.7625959636196327,
-        1.7541903672600494,
-        1.7459181197626403,
-        1.737780757913635,
-        1.7297783508684146,
-        1.7217732861435076,
-        1.7137640932265894,
-        1.7057507692361864,
-        1.6918150918099673,
-        1.6719047669939942,
-        1.6460167077689267,
-        1.6201194134191075,
-        1.5986915141218316,
-        1.5817353179379183,
-        1.569199764184379,
-        1.5566577309558969,
-        1.545374152761467,
-        1.5353620432989845,
-        1.5266220576235803,
-        1.5178910621476225,
-        1.5097346239790443,
-        1.502153039909686,
-        1.495145456062699,
-        1.488134243479226,
-        1.48111939735681,
-        1.474100442252211,
-        1.4670307626366115,
-        1.4599103316162523,
-        1.45273959485914,
-        1.445565137158368,
-        1.4340878115214444,
-        1.418273806730323,
-        1.3981208704326855,
-        1.3779439775587023,
-        1.3598972673004606,
-        1.3439818461440451,
-        1.3301807335621048,
-        1.316383926863083,
-        1.3040618749785347,
-        1.2932153453410835,
-        1.2838336236692311,
-        1.2744470198196236,
-        1.2650555289898042,
-        1.2556591482982988,
-        1.2428104897182262,
-        1.2264996957264114,
-        1.2067249615595257,
-        1.1869318618366975,
-        1.1672278304018044,
-        1.1476135933863398,
-        1.1280891949729075,
-        1.108555289615659,
-        1.0895983485572227,
-        1.0712204022764056,
-        1.0534217504465226,
-        1.0356155337864215,
+        1.0,
         1.017807767853702,
-        1.0
+        1.0356155337864215,
+        1.0534217504465226,
+        1.0712204022764056,
+        1.0895983485572227,
+        1.108555289615659,
+        1.1280891949729075,
+        1.1476135933863398,
+        1.1672278304018044,
+        1.1869318618366975,
+        1.2067249615595257,
+        1.2264996957264114,
+        1.2428104897182262,
+        1.2556591482982988,
+        1.2650555289898042,
+        1.2744470198196236,
+        1.2838336236692311,
+        1.2932153453410835,
+        1.3040618749785347,
+        1.316383926863083,
+        1.3301807335621048,
+        1.3439818461440451,
+        1.3598972673004606,
+        1.3779439775587023,
+        1.3981208704326855,
+        1.418273806730323,
+        1.4340878115214444,
+        1.445565137158368,
+        1.45273959485914,
+        1.4599103316162523,
+        1.4670307626366115,
+        1.474100442252211,
+        1.48111939735681,
+        1.488134243479226,
+        1.495145456062699,
+        1.502153039909686,
+        1.5097346239790443,
+        1.5178910621476225,
+        1.5266220576235803,
+        1.5353620432989845,
+        1.545374152761467,
+        1.5566577309558969,
+        1.569199764184379,
+        1.5817353179379183,
+        1.5986915141218316,
+        1.6201194134191075,
+        1.6460167077689267,
+        1.6719047669939942,
+        1.6918150918099673,
+        1.7057507692361864,
+        1.7137640932265894,
+        1.7217732861435076,
+        1.7297783508684146,
+        1.737780757913635,
+        1.7459181197626403,
+        1.7541903672600494,
+        1.7625959636196327,
+        1.7709972329654864,
+        1.7793941781790852,
+        1.7877868031023945,
+        1.7961751115773796,
+        1.8045606557581335,
+        1.8139629377087627,
+        1.824381436842932,
+        1.835814081380705,
+        1.847275503201129,
+        1.862235672444246,
+        1.8806927939516411,
+        1.9026104247588487,
+        1.9245345552113182,
+        1.9482128147680253,
+        1.9736443063300082,
+        2.0008103857988204,
+        2.0279625371819305,
+        2.055100772005235,
+        2.082225099873648,
+        2.1183028432496016,
+        2.16337565384239,
+        2.2174389328192197,
+        2.271520771371253,
+        2.322373696229342,
+        2.3699990328716107,
+        2.414398437185221,
+        2.4587748041127506,
+        2.499446286796604,
+        2.5364027376452056,
+        2.5696460593920065,
+        2.602860350286428,
+        2.630396440815385,
+        2.6521732021128046,
+        2.6681935771243177,
+        2.6841217449620203,
+        2.6947834587664494,
+        2.705443819238505,
+        2.714526681131686
     ]
-}
+}

gnpy/example-data/edfa_model/OA.json

@@ -0,0 +1,6 @@
+{
+    "nf_ripple": "NFR_96.txt", 
+    "gain_ripple": "DFG_96.txt",
+    "dgt": "DGT_96.txt",
+    "nf_fit_coeff": "pNFfit3.txt"
+}

gnpy/example-data/edfa_model/amplifier_models_description.rst

@@ -0,0 +1,300 @@
+*********************************************
+Amplifier models and configuration
+*********************************************
+
+
+1. Equipment configuration description
+#######################################
+
+Equipment description defines equipment types and parameters.
+It takes place in the default **eqpt_config.json** file. 
+By default **gnpy-transmission-example** uses **eqpt_config.json** file and that
+can be changed with **-e** or **--equipment** command line parameter.
+
+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.
+
+- *"type_variety"*:
+    Each amplifier is identified by its unique *"type_variety"*, which is used in the topology files input to reference a specific amplifier. It is a user free defined id.
+    
+    For each amplifier *type_variety*, specific parameters are describing its attributes and performance:
+
+- *"type_def"*:
+    Sets the amplifier model that the simulation will use to calculate the ase noise contribution. 5 models are defined with reserved words:
+
+    - *"advanced_model"*
+    - *"variable_gain"*
+    - *"fixed_gain"*
+    - *"dual_stage"*
+    - *"openroadm"*
+        *see next section for a full description of these models*
+
+- *"advanced_config_from_json"*:
+    **This parameter is only applicable to the _"advanced_model"_ model**
+    
+    json file name describing:
+
+    - nf_fit_coeff
+    - f_min/max
+    - gain_ripple
+    - nf_ripple 
+    - dgt
+    
+    *see next section for a full description*
+
+- *"gain_flatmax"*: 
+    amplifier maximum gain in dB before its extended gain range: flat or nominal tilt output. 
+    
+    If gain > gain_flatmax, the amplifier will tilt, based on its dgt function
+
+    If gain > gain_flatmax + target_extended_gain, the amplifier output power is reduced to  not exceed the extended gain range.
+
+- *"gain_min"*: 
+    amplifier minimum gain in dB.
+
+    If gain < gain_min, the amplifier input is automatically padded, which results in
+
+    NF += gain_min - gain 
+
+- *"p_max"*: 
+    amplifier max output power, full load
+
+    Total signal output power will not be allowed beyond this value
+
+- *"nf_min/max"*:
+    **These parameters are only applicable to the _"variable_gain"_ model**
+
+    min & max NF values in dB
+
+    NF_min is the amplifier NF @ gain_max  
+
+    NF_max is the amplifier NF @ gain_min  
+
+- *"nf_coef"*: 
+    **This parameter is only applicable to the *"openroadm"* model**
+
+    [a, b, c, d] 3rd order polynomial coefficients list to define the incremental OSNR vs Pin
+    
+    Incremental OSNR is the amplifier OSNR contribution
+    
+    Pin is the amplifier channel input power defined in a 50GHz bandwidth
+    
+    Incremental OSNR = a*Pin³ + b*Pin² + c*Pin + d
+
+- *"preamp_variety"*: 
+    **This parameter is only applicable to the _"dual_stage"_ model**
+
+    1st stage type_variety
+
+- *"booster_variety"*: 
+    **This parameter is only applicable to the *"dual_stage"* model**
+
+    2nd stage type_variety
+
+- *"out_voa_auto"*: true/false
+    **power_mode only**
+
+    **This parameter is only applicable to the *"advanced_model"* and *"variable_gain"* models**
+
+    If "out_voa_auto": true, auto_design will chose the output_VOA value that maximizes the amplifier gain within its power capability and therefore minimizes its NF.
+
+- *"allowed_for_design"*: true/false
+    **auto_design only**
+
+    Tells auto_design if this amplifier can be picked for the design (deactivates unwanted amplifiers)
+
+    It does not prevent the use of an amplifier if it is placed in the topology input.
+
+    .. code-block:: json
+
+        {"Edfa": [{
+                    "type_variety": "std_medium_gain",
+                    "type_def": "variable_gain",
+                    "gain_flatmax": 26,
+                    "gain_min": 15,
+                    "p_max": 23,
+                    "nf_min": 6,
+                    "nf_max": 10,
+                    "out_voa_auto": false,
+                    "allowed_for_design": true
+                    },
+                    {
+                    "type_variety": "std_low_gain",
+                    "type_def": "variable_gain",
+                    "gain_flatmax": 16,
+                    "gain_min": 8,
+                    "p_max": 23,
+                    "nf_min": 6.5,
+                    "nf_max": 11,
+                    "out_voa_auto": false,
+                    "allowed_for_design": true
+                    }
+            ]}
+
+
+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.
+
+5 types of EDFA definition are possible and referenced by the *"type_def"* parameter with the following reserved words:
+
+-  *"advanced_model"* 
+    This model is refered as a whitebox model because of the detailed level of knowledge that is required. The amplifier NF model and ripple definition are described by a json file referenced with *"advanced_config_from_json"*: json filename. This json file contains:
+
+    - nf_fit_coeff: [a,b,c,d]
+         
+        3rd order polynomial NF = f(-dg) coeficients list
+
+        dg = gain - gain_max
+
+    - f_min/max: amplifier frequency range in Hz
+    - gain_ripple : [...]
+
+        amplifier gain ripple excursion comb list in dB across the frequency range.
+    - nf_ripple : [...]
+        
+        amplifier nf ripple excursion comb list in dB across the frequency range. 
+    - dgt : [...]
+        amplifier dynamic gain tilt comb list across the frequency range.
+            
+        *See next section for the generation of this json file*
+
+    .. code-block:: json-object
+
+        "Edfa":[{
+                "type_variety": "high_detail_model_example",
+                "type_def": "advanced_model",
+                "gain_flatmax": 25,
+                "gain_min": 15,
+                "p_max": 21,
+                "advanced_config_from_json": "std_medium_gain_advanced_config.json",
+                "out_voa_auto": false,
+                "allowed_for_design": false
+                }
+            ]
+
+- *"variable_gain"* 
+    This model is refered as an operator model because a lower level of knowledge is required. A full polynomial description of the NF cross the gain range is not required. Instead, NF_min and NF_max values are required and used by the code to model a dual stage amplifier with an internal mid stage VOA. NF_min and NF_max values are typically available from equipment suppliers data-sheet.
+
+    There is a default JSON file ”default_edfa_config.json”* to enforce 0 tilt and ripple values because GNpy core algorithm is a multi-carrier propogation.
+    - gain_ripple =[0,...,0]
+    - nf_ripple = [0,...,0]
+    - dgt = [...] generic dgt comb
+
+    .. code-block:: json-object
+
+        "Edfa":[{
+                "type_variety": "std_medium_gain",
+                "type_def": "variable_gain",
+                "gain_flatmax": 26,
+                "gain_min": 15,
+                "p_max": 23,
+                "nf_min": 6,
+                "nf_max": 10,
+                "out_voa_auto": false,
+                "allowed_for_design": true
+                }
+            ]
+
+-  *"fixed_gain"* 
+    This model is also an operator model with a single NF value that emulates basic single coil amplifiers without internal VOA.
+
+    if gain_min < gain < gain_max, NF == nf0
+    
+    if gain < gain_min, the amplifier input is automatically padded, which results in 
+
+    NF += gain_min - gain
+
+    .. code-block:: json-object
+
+        "Edfa":[{
+                "type_variety": "std_fixed_gain",
+                "type_def": "fixed_gain",
+                "gain_flatmax": 21,
+                "gain_min": 20,
+                "p_max": 21,
+                "nf0": 5.5,
+                "allowed_for_design": false
+                }
+            ]
+
+- *"openroadm"* 
+    This model is a black box model replicating OpenRoadm MSA spec for ILA.
+
+    .. code-block:: json-object
+
+        "Edfa":[{
+                "type_variety": "openroadm_ila_low_noise",
+                "type_def": "openroadm",
+                "gain_flatmax": 27,
+                "gain_min": 12,
+                "p_max": 22,
+                "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62],
+                "allowed_for_design": false
+                }
+            ]
+
+- *"dual_stage"* 
+    This model allows the cascade (pre-defined combination) of any 2 amplifiers already described in the eqpt_config.json library.
+    
+    - preamp_variety defines the 1st stge type variety
+    
+    - booster variety defines the 2nd stage type variety
+    
+    Both preamp and booster variety must exist in the eqpt libray
+    The resulting NF is the sum of the 2 amplifiers 
+    The preamp is operated to its maximum gain
+    
+    - gain_min indicates to auto_design when this dual_stage should be used
+    
+    But unlike other models the 1st stage input will not be padded: it is always operated to its maximu gain and min NF. Therefore if gain adaptation and padding is needed it will be performed by the 2nd stage.
+
+    .. code-block:: json
+
+                {
+                "type_variety": "medium+low_gain",
+                "type_def": "dual_stage",
+                "gain_min": 25,
+                "preamp_variety": "std_medium_gain",
+                "booster_variety": "std_low_gain",
+                "allowed_for_design": true
+                }
+
+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:
+
+Update an existing json file with all the 96ch txt files for a given amplifier type
+amplifier type 'OA_type1' is hard coded but can be modified and other types added
+returns an updated amplifier json file: output_json_file_name = 'edfa_config.json'
+amplifier file names
+
+Convert a set of amplifier files + input json definiton file into a valid edfa_json_file:
+
+nf_fit_coeff: NF 3rd order polynomial coefficients txt file
+
+nf = f(dg) with dg = gain_operational - gain_max
+
+nf_ripple: NF ripple excursion txt file
+
+gain_ripple: gain ripple txt file
+
+dgt: dynamic gain txt file
+
+input json file in argument (defult = 'OA.json')
+
+the json input file should have the following fields:
+
+    .. code-block:: json
+
+        {
+            "nf_fit_coeff": "nf_filename.txt",
+            "nf_ripple": "nf_ripple_filename.txt", 
+            "gain_ripple": "DFG_filename.txt",
+            "dgt": "DGT_filename.txt"
+        }
+

gnpy/example-data/edfa_model/build_oa_json.py

@@ -4,7 +4,6 @@
 Created on Tue Jan 30 12:32:00 2018
 
 @author: jeanluc-auge
-@comments about amplifier input files from Brian Taylor & Dave Boertjes
 
 update an existing json file with all the 96ch txt files for a given amplifier type
 amplifier type 'OA_type1' is hard coded but can be modified and other types added
@@ -14,91 +13,77 @@ import re
 import sys
 import json
 import numpy as np
-from gnpy.core.utils import lin2db, db2lin
 
 """amplifier file names
 convert a set of amplifier files + input json definiton file into a valid edfa_json_file:
-nf_fit_coeff: NF polynomial coefficients txt file (optional)
+nf_fit_coeff: NF 3rd order polynomial coefficients txt file
+    nf = f(dg)
+    with dg = gain_operational - gain_max
 nf_ripple: NF ripple excursion txt file
-dfg: gain txt file
+gain_ripple: gain ripple txt file
 dgt: dynamic gain txt file
 input json file in argument (defult = 'OA.json')
+
 the json input file should have the following fields:
 {
-    "gain_flatmax": 25,
-    "gain_min": 15,
-    "p_max": 21,
-    "nf_fit_coeff": "pNFfit3.txt",
-    "nf_ripple": "NFR_96.txt", 
-    "dfg": "DFG_96.txt",
-    "dgt": "DGT_96.txt",
-    "nf_model": 
-        {
-        "enabled": true,
-        "nf_min": 5.8,
-        "nf_max": 10
-        }
+    "nf_fit_coeff": "nf_filename.txt",
+    "nf_ripple": "nf_ripple_filename.txt",
+    "gain_ripple": "DFG_filename.txt",
+    "dgt": "DGT_filename.txt",
 }
-gain_flat = max flat gain (dB)
-gain_min = min gain (dB) : will consider an input VOA if below (TBD vs throwing an exception)
-p_max = max power (dBm)
-nf_fit = boolean (True, False) : 
-        if False nf_fit_coeff are ignored and nf_model fields are used
+
 """
 
-input_json_file_name = "OA.json" #default path
+input_json_file_name = "OA.json"  # default path
 output_json_file_name = "default_edfa_config.json"
-param_field  ="params"
-gain_min_field = "gain_min"
-gain_max_field = "gain_flatmax"
-gain_ripple_field = "dfg"
+gain_ripple_field = "gain_ripple"
 nf_ripple_field = "nf_ripple"
 nf_fit_coeff = "nf_fit_coeff"
-nf_model_field = "nf_model"
-nf_model_enabled_field = "enabled"
-nf_min_field  ="nf_min"
-nf_max_field = "nf_max"
+
 
 def read_file(field, file_name):
     """read and format the 96 channels txt files describing the amplifier NF and ripple
         convert dfg into gain ripple by removing the mean component
     """
 
-    #with open(path + file_name,'r') as this_file:
+    # with open(path + file_name,'r') as this_file:
     #   data = this_file.read()
-    #data.strip()
+    # data.strip()
     #data = re.sub(r"([0-9])([ ]{1,3})([0-9-+])",r"\1,\3",data)
     #data = list(data.split(","))
     #data = [float(x) for x in data]
     data = np.loadtxt(file_name)
     print(len(data), file_name)
     if field == gain_ripple_field or field == nf_ripple_field:
-        #consider ripple excursion only to avoid redundant information
-        #because the max flat_gain is already given by the 'gain_flat' field in json
-        #remove the mean component
+        # consider ripple excursion only to avoid redundant information
+        # because the max flat_gain is already given by the 'gain_flat' field in json
+        # remove the mean component
+        print(file_name, ', mean value =', data.mean(), ' is substracted')
         data = data - data.mean()
     data = data.tolist()
     return data
 
+
 def input_json(path):
     """read the json input file and add all the 96 channels txt files
     create the output json file with output_json_file_name"""
-    with open(path,'r') as edfa_json_file:
+    with open(path, 'r') as edfa_json_file:
         amp_text = edfa_json_file.read()
     amp_dict = json.loads(amp_text)
 
     for k, v in amp_dict.items():
-        if re.search(r'.txt$',str(v)) :
+        if re.search(r'.txt$', str(v)):
             amp_dict[k] = read_file(k, v)
 
     amp_text = json.dumps(amp_dict, indent=4)
-    #print(amp_text)
-    with  open(output_json_file_name,'w') as edfa_json_file:
+    # print(amp_text)
+    with open(output_json_file_name, 'w') as edfa_json_file:
         edfa_json_file.write(amp_text)
 
+
 if __name__ == '__main__':
     if len(sys.argv) == 2:
         path = sys.argv[1]
     else:
         path = input_json_file_name
-    input_json(path)
+    input_json(path)

gnpy/example-data/eqpt_config.json

@@ -0,0 +1,328 @@
+{     "Edfa":[{
+            "type_variety": "high_detail_model_example",
+            "type_def": "advanced_model",
+            "gain_flatmax": 25,
+            "gain_min": 15,
+            "p_max": 21,
+            "advanced_config_from_json": "std_medium_gain_advanced_config.json",
+            "out_voa_auto": false,
+            "allowed_for_design": false
+            },                  {
+            "type_variety": "Juniper_BoosterHG",
+            "type_def": "advanced_model",
+            "gain_flatmax": 25,
+            "gain_min": 10,
+            "p_max": 21,
+            "advanced_config_from_json": "Juniper-BoosterHG.json",
+            "out_voa_auto": false,
+            "allowed_for_design": false
+            }, 
+            {
+            "type_variety": "operator_model_example",
+            "type_def": "variable_gain",
+            "gain_flatmax": 26,
+            "gain_min": 15,
+            "p_max": 23,
+            "nf_min": 6,
+            "nf_max": 10,
+            "out_voa_auto": false,
+            "allowed_for_design": false           
+            },
+            {
+            "type_variety": "openroadm_ila_low_noise",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62],
+            "allowed_for_design": false
+            },          
+            {
+            "type_variety": "openroadm_ila_standard",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-5.952e-4,-6.250e-2,-1.071,28.99],
+            "allowed_for_design": false
+            },
+            {
+            "type_variety": "openroadm_mw_mw_preamp",
+            "type_def": "openroadm_preamp",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "allowed_for_design": false
+            },
+            {
+            "type_variety": "openroadm_mw_mw_booster",
+            "type_def": "openroadm_booster",
+            "gain_flatmax": 32,
+            "gain_min": 0,
+            "p_max": 22,
+            "allowed_for_design": false
+            },
+            {
+            "type_variety": "std_high_gain",
+            "type_def": "variable_gain",
+            "gain_flatmax": 35,
+            "gain_min": 25,
+            "p_max": 21,
+            "nf_min": 5.5,
+            "nf_max": 7,
+            "out_voa_auto": false,
+            "allowed_for_design": true
+            },            
+            {
+            "type_variety": "std_medium_gain",
+            "type_def": "variable_gain",
+            "gain_flatmax": 26,
+            "gain_min": 15,
+            "p_max": 23,
+            "nf_min": 6,
+            "nf_max": 10,
+            "out_voa_auto": false,
+            "allowed_for_design": true
+            },
+            {
+            "type_variety": "std_low_gain",
+            "type_def": "variable_gain",
+            "gain_flatmax": 16,
+            "gain_min": 8,
+            "p_max": 23,
+            "nf_min": 6.5,
+            "nf_max": 11,
+            "out_voa_auto": false,
+            "allowed_for_design": true
+            },
+            {
+            "type_variety": "high_power",
+            "type_def": "variable_gain",
+            "gain_flatmax": 16,
+            "gain_min": 8,
+            "p_max": 25,
+            "nf_min": 9,
+            "nf_max": 15,
+            "out_voa_auto": false,
+            "allowed_for_design": false
+            },            
+            {
+            "type_variety": "std_fixed_gain",
+            "type_def": "fixed_gain",
+            "gain_flatmax": 21,
+            "gain_min": 20,
+            "p_max": 21,
+            "nf0": 5.5,
+            "allowed_for_design": false
+            },
+            {
+            "type_variety": "4pumps_raman",
+            "type_def": "fixed_gain",
+            "gain_flatmax": 12,
+            "gain_min": 12,
+            "p_max": 21,
+            "nf0": -1,
+            "allowed_for_design": false
+            },   
+            {
+            "type_variety": "hybrid_4pumps_lowgain",
+            "type_def": "dual_stage",
+            "raman": true,
+            "gain_min": 25,
+            "preamp_variety": "4pumps_raman",
+            "booster_variety": "std_low_gain",
+            "allowed_for_design": true
+            },
+            {
+            "type_variety": "hybrid_4pumps_mediumgain",
+            "type_def": "dual_stage",
+            "raman": true,
+            "gain_min": 25,
+            "preamp_variety": "4pumps_raman",
+            "booster_variety": "std_medium_gain",
+            "allowed_for_design": true
+            },            
+            {
+            "type_variety": "medium+low_gain",
+            "type_def": "dual_stage",
+            "gain_min": 25,
+            "preamp_variety": "std_medium_gain",
+            "booster_variety": "std_low_gain",
+            "allowed_for_design": true
+            },
+            {
+            "type_variety": "medium+high_power",
+            "type_def": "dual_stage",
+            "gain_min": 25,
+            "preamp_variety": "std_medium_gain",
+            "booster_variety": "high_power",
+            "allowed_for_design": false
+            }                                  
+      ],
+      "Fiber":[{
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "gamma": 0.00127,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "NZDF",
+            "dispersion": 0.5e-05,
+            "gamma": 0.00146,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "LOF",
+            "dispersion": 2.2e-05,
+            "gamma": 0.000843,
+            "pmd_coef": 1.265e-15
+            }
+      ],
+      "RamanFiber":[{
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "gamma": 0.00127,
+            "pmd_coef": 1.265e-15,
+            "raman_efficiency": {
+              "cr":[
+                  0, 9.4E-06, 2.92E-05, 4.88E-05, 6.82E-05, 8.31E-05, 9.4E-05, 0.0001014, 0.0001069, 0.0001119,
+                  0.0001217, 0.0001268, 0.0001365, 0.000149, 0.000165, 0.000181, 0.0001977, 0.0002192, 0.0002469,
+                  0.0002749, 0.0002999, 0.0003206, 0.0003405, 0.0003592, 0.000374, 0.0003826, 0.0003841, 0.0003826,
+                  0.0003802, 0.0003756, 0.0003549, 0.0003795, 0.000344, 0.0002933, 0.0002024, 0.0001158, 8.46E-05,
+                  7.14E-05, 6.86E-05, 8.5E-05, 8.93E-05, 9.01E-05, 8.15E-05, 6.67E-05, 4.37E-05, 3.28E-05, 2.96E-05,
+                  2.65E-05, 2.57E-05, 2.81E-05, 3.08E-05, 3.67E-05, 5.85E-05, 6.63E-05, 6.36E-05, 5.5E-05, 4.06E-05,
+                  2.77E-05, 2.42E-05, 1.87E-05, 1.6E-05, 1.4E-05, 1.13E-05, 1.05E-05, 9.8E-06, 9.8E-06, 1.13E-05,
+                  1.64E-05, 1.95E-05, 2.38E-05, 2.26E-05, 2.03E-05, 1.48E-05, 1.09E-05, 9.8E-06, 1.05E-05, 1.17E-05,
+                  1.25E-05, 1.21E-05, 1.09E-05, 9.8E-06, 8.2E-06, 6.6E-06, 4.7E-06, 2.7E-06, 1.9E-06, 1.2E-06, 4E-07,
+                  2E-07, 1E-07
+              ],
+              "frequency_offset":[
+                0, 0.5e12, 1e12, 1.5e12, 2e12, 2.5e12, 3e12, 3.5e12, 4e12, 4.5e12, 5e12, 5.5e12, 6e12, 6.5e12, 7e12,
+                7.5e12, 8e12, 8.5e12, 9e12, 9.5e12, 10e12, 10.5e12, 11e12, 11.5e12, 12e12, 12.5e12, 12.75e12,
+                13e12, 13.25e12, 13.5e12, 14e12, 14.5e12, 14.75e12, 15e12, 15.5e12, 16e12, 16.5e12, 17e12,
+                17.5e12, 18e12, 18.25e12, 18.5e12, 18.75e12, 19e12, 19.5e12, 20e12, 20.5e12, 21e12, 21.5e12,
+                22e12, 22.5e12, 23e12, 23.5e12, 24e12, 24.5e12, 25e12, 25.5e12, 26e12, 26.5e12, 27e12, 27.5e12, 28e12,
+                28.5e12, 29e12, 29.5e12, 30e12, 30.5e12, 31e12, 31.5e12, 32e12, 32.5e12, 33e12, 33.5e12, 34e12, 34.5e12,
+                35e12, 35.5e12, 36e12, 36.5e12, 37e12, 37.5e12, 38e12, 38.5e12, 39e12, 39.5e12, 40e12, 40.5e12, 41e12,
+                41.5e12, 42e12
+              ]
+              }
+            }
+      ],
+      "Span":[{
+            "power_mode":true,
+            "delta_power_range_db": [-2,3,0.5],
+            "max_fiber_lineic_loss_for_raman": 0.25,
+            "target_extended_gain": 2.5,
+            "max_length": 150,
+            "length_units": "km",
+            "max_loss": 28,
+            "padding": 10,
+            "EOL": 0,
+            "con_in": 0,
+            "con_out": 0
+            }
+      ],
+      "Roadm":[{
+            "target_pch_out_db": -20,
+            "add_drop_osnr": 38,
+            "pmd": 0,
+            "restrictions": {
+                            "preamp_variety_list":[],
+                            "booster_variety_list":[]
+                            }            
+            }],
+      "SI":[{
+            "f_min": 191.3e12,
+            "baud_rate": 32e9,
+            "f_max":195.1e12,
+            "spacing": 50e9,
+            "power_dbm": 0,
+            "power_range_db": [0,0,1],
+            "roll_off": 0.15,
+            "tx_osnr": 40,
+            "sys_margins": 2
+            }],
+      "Transceiver":[
+            {
+            "type_variety": "vendorA_trx-type1",
+            "frequency":{
+                        "min": 191.35e12,
+                        "max": 196.1e12
+                        },
+            "mode":[
+                       {
+
+                       "format": "mode 1",
+                       "baud_rate": 32e9,
+                       "OSNR": 11,
+                       "bit_rate": 100e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 37.5e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "mode 2",
+                       "baud_rate": 66e9,
+                       "OSNR": 15,
+                       "bit_rate": 200e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 75e9,
+                       "cost":1
+                       }
+                   ]
+            },
+            {
+            "type_variety": "Voyager",
+            "frequency":{
+                        "min": 191.35e12,
+                        "max": 196.1e12
+                        },
+            "mode":[
+                       {
+                       "format": "mode 1",
+                       "baud_rate": 32e9,
+                       "OSNR": 12,
+                       "bit_rate": 100e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 37.5e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "mode 3",
+                       "baud_rate": 44e9,
+                       "OSNR": 18,
+                       "bit_rate": 300e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 62.5e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "mode 2",
+                       "baud_rate": 66e9,
+                       "OSNR": 21,
+                       "bit_rate": 400e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 75e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "mode 4",
+                       "baud_rate": 66e9,
+                       "OSNR": 16,
+                       "bit_rate": 200e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 40,
+                       "min_spacing": 75e9,
+                       "cost":1
+                       }
+                   ]
+            }
+      ]
+
+}

gnpy/example-data/eqpt_config_openroadm.json

@@ -0,0 +1,190 @@
+{     "Edfa":[
+            {
+            "type_variety": "openroadm_ila_low_noise",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62],
+            "allowed_for_design": true
+            },
+            {
+            "type_variety": "openroadm_ila_standard",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-5.952e-4,-6.250e-2,-1.071,28.99],
+            "allowed_for_design": true
+            },
+		{
+            "type_variety": "openroadm_mw_mw_preamp",
+            "type_def": "openroadm_preamp",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "allowed_for_design": false
+            },
+		{
+            "type_variety": "openroadm_mw_mw_booster",
+            "type_def": "openroadm_booster",
+            "gain_flatmax": 32,
+            "gain_min": 0,
+            "p_max": 22,
+            "allowed_for_design": false
+            }
+      ],
+      "Fiber":[
+            {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "gamma": 0.00127,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "NZDF",
+            "dispersion": 0.5e-05,
+            "gamma": 0.00146,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "LOF",
+            "dispersion": 2.2e-05,
+            "gamma": 0.000843,
+            "pmd_coef": 1.265e-15
+            }
+      ],
+      "RamanFiber":[
+            {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "gamma": 0.00127,
+            "pmd_coef": 1.265e-15,
+            "raman_efficiency": {
+              "cr":[
+                  0, 9.4E-06, 2.92E-05, 4.88E-05, 6.82E-05, 8.31E-05, 9.4E-05, 0.0001014, 0.0001069, 0.0001119,
+                  0.0001217, 0.0001268, 0.0001365, 0.000149, 0.000165, 0.000181, 0.0001977, 0.0002192, 0.0002469,
+                  0.0002749, 0.0002999, 0.0003206, 0.0003405, 0.0003592, 0.000374, 0.0003826, 0.0003841, 0.0003826,
+                  0.0003802, 0.0003756, 0.0003549, 0.0003795, 0.000344, 0.0002933, 0.0002024, 0.0001158, 8.46E-05,
+                  7.14E-05, 6.86E-05, 8.5E-05, 8.93E-05, 9.01E-05, 8.15E-05, 6.67E-05, 4.37E-05, 3.28E-05, 2.96E-05,
+                  2.65E-05, 2.57E-05, 2.81E-05, 3.08E-05, 3.67E-05, 5.85E-05, 6.63E-05, 6.36E-05, 5.5E-05, 4.06E-05,
+                  2.77E-05, 2.42E-05, 1.87E-05, 1.6E-05, 1.4E-05, 1.13E-05, 1.05E-05, 9.8E-06, 9.8E-06, 1.13E-05,
+                  1.64E-05, 1.95E-05, 2.38E-05, 2.26E-05, 2.03E-05, 1.48E-05, 1.09E-05, 9.8E-06, 1.05E-05, 1.17E-05,
+                  1.25E-05, 1.21E-05, 1.09E-05, 9.8E-06, 8.2E-06, 6.6E-06, 4.7E-06, 2.7E-06, 1.9E-06, 1.2E-06, 4E-07,
+                  2E-07, 1E-07
+              ],
+              "frequency_offset":[
+                0, 0.5e12, 1e12, 1.5e12, 2e12, 2.5e12, 3e12, 3.5e12, 4e12, 4.5e12, 5e12, 5.5e12, 6e12, 6.5e12, 7e12,
+                7.5e12, 8e12, 8.5e12, 9e12, 9.5e12, 10e12, 10.5e12, 11e12, 11.5e12, 12e12, 12.5e12, 12.75e12,
+                13e12, 13.25e12, 13.5e12, 14e12, 14.5e12, 14.75e12, 15e12, 15.5e12, 16e12, 16.5e12, 17e12,
+                17.5e12, 18e12, 18.25e12, 18.5e12, 18.75e12, 19e12, 19.5e12, 20e12, 20.5e12, 21e12, 21.5e12,
+                22e12, 22.5e12, 23e12, 23.5e12, 24e12, 24.5e12, 25e12, 25.5e12, 26e12, 26.5e12, 27e12, 27.5e12, 28e12,
+                28.5e12, 29e12, 29.5e12, 30e12, 30.5e12, 31e12, 31.5e12, 32e12, 32.5e12, 33e12, 33.5e12, 34e12, 34.5e12,
+                35e12, 35.5e12, 36e12, 36.5e12, 37e12, 37.5e12, 38e12, 38.5e12, 39e12, 39.5e12, 40e12, 40.5e12, 41e12,
+                41.5e12, 42e12
+              ]
+              }
+            }
+      ],
+      "Span":[
+            {
+            "power_mode":true,
+            "delta_power_range_db": [0,0,0],
+            "max_fiber_lineic_loss_for_raman": 0.25,
+            "target_extended_gain": 0,
+            "max_length": 135,
+            "length_units": "km",
+            "max_loss": 28,
+            "padding": 11,
+            "EOL": 0,
+            "con_in": 0,
+            "con_out": 0
+            }
+      ],
+      "Roadm":[
+            {
+            "target_pch_out_db": -20,
+            "add_drop_osnr": 30,
+            "pmd": 0,
+            "restrictions": {
+                            "preamp_variety_list":["openroadm_mw_mw_preamp"],
+                            "booster_variety_list":["openroadm_mw_mw_booster"]
+                            }            
+            }
+      ],
+      "SI":[
+            {
+            "f_min": 191.3e12,
+            "baud_rate": 31.57e9,
+            "f_max":196.1e12,
+            "spacing": 50e9,
+            "power_dbm": 2,
+            "power_range_db": [0,0,1],
+            "roll_off": 0.15,
+            "tx_osnr": 35,
+            "sys_margins": 2
+            }
+      ],
+      "Transceiver":[
+		{
+            "type_variety": "OpenROADM MSA ver. 4.0",
+            "frequency":{
+                        "min": 191.35e12,
+                        "max": 196.1e12
+                        },
+            "mode":[
+                       {
+                       "format": "100 Gbit/s, 27.95 Gbaud, DP-QPSK",
+                       "baud_rate": 27.95e9,
+                       "OSNR": 17,
+                       "bit_rate": 100e9,
+                       "roll_off": null,
+                       "tx_osnr": 33,
+                       "min_spacing": 50e9,
+                       "cost":1
+                       },
+					   {
+                       "format": "100 Gbit/s, 31.57 Gbaud, DP-QPSK",
+                       "baud_rate": 31.57e9,
+                       "OSNR": 12,
+                       "bit_rate": 100e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 35,
+                       "min_spacing": 50e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "200 Gbit/s, DP-QPSK",
+                       "baud_rate": 63.1e9,
+                       "OSNR": 17,
+                       "bit_rate": 200e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 36,
+                       "min_spacing": 87.5e9,
+                       "cost":1
+                       },
+                       {
+                       "format": "300 Gbit/s, DP-8QAM",
+                       "baud_rate": 63.1e9,
+                       "OSNR": 21,
+                       "bit_rate": 300e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 36,
+                       "min_spacing": 87.5e9,
+                       "cost":1
+                       },
+					   {
+                       "format": "400 Gbit/s, DP-16QAM",
+                       "baud_rate": 63.1e9,
+                       "OSNR": 24,
+                       "bit_rate": 400e9,
+                       "roll_off": 0.15,
+                       "tx_osnr": 36,
+                       "min_spacing": 87.5e9,
+                       "cost":1
+                       }
+                   ]
+            }
+      ]
+
+}

gnpy/example-data/meshTopologyExampleV2.json

@@ -623,31 +623,457 @@
         "con_in": null,
         "con_out": null
       }
+    },
+    {
+      "uid": "west edfa in Quimper",
+      "metadata": {
+        "location": {
+          "city": "Quimper",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 1.0
+        }
+      },
+      "type": "Edfa",
+      "operational": {
+        "gain_target": null,
+        "tilt_target": 0
+      }
+    },
+    {
+      "uid": "west edfa in Ploermel",
+      "metadata": {
+        "location": {
+          "city": "Ploermel",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 2.0
+        }
+      },
+      "type": "Edfa",
+      "operational": {
+        "gain_target": null,
+        "tilt_target": 0
+      }
+    },
+    {
+      "uid": "east edfa in Quimper",
+      "metadata": {
+        "location": {
+          "city": "Quimper",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 1.0
+        }
+      },
+      "type": "Edfa",
+      "operational": {
+        "gain_target": null,
+        "tilt_target": 0
+      }
+    },
+    {
+      "uid": "east edfa in Ploermel",
+      "metadata": {
+        "location": {
+          "city": "Ploermel",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 2.0
+        }
+      },
+      "type": "Edfa",
+      "operational": {
+        "gain_target": null,
+        "tilt_target": 0
+      }
+    },
+    {
+      "uid": "east edfa in Lannion_CAS to Corlay",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Lorient_KMA to Vannes_KBE",
+      "metadata": {
+        "location": {
+          "city": "Lorient_KMA",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 3.0
+        }
+      },
+      "type": "Fused",
+      "params": {
+        "loss": 0
+      }
+    },
+    {
+      "uid": "east edfa in Lannion_CAS to Stbrieuc",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Stbrieuc to Rennes_STA",
+      "metadata": {
+        "location": {
+          "city": "Stbrieuc",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Lannion_CAS to Morlaix",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Lorient_KMA to Loudeac",
+      "metadata": {
+        "location": {
+          "city": "Lorient_KMA",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 3.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Vannes_KBE to Lorient_KMA",
+      "metadata": {
+        "location": {
+          "city": "Vannes_KBE",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 4.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Rennes_STA to Stbrieuc",
+      "metadata": {
+        "location": {
+          "city": "Rennes_STA",
+          "region": "RLD",
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "east edfa in Brest_KLA to Morlaix",
+      "metadata": {
+        "location": {
+          "city": "Brest_KLA",
+          "region": "RLD",
+          "latitude": 4.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Lannion_CAS to Corlay",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_high_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Lorient_KMA to Vannes_KBE",
+      "metadata": {
+        "location": {
+          "city": "Lorient_KMA",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 3.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Lannion_CAS to Stbrieuc",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Stbrieuc to Rennes_STA",
+      "metadata": {
+        "location": {
+          "city": "Stbrieuc",
+          "region": "RLD",
+          "latitude": 1.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Lannion_CAS to Morlaix",
+      "metadata": {
+        "location": {
+          "city": "Lannion_CAS",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Lorient_KMA to Loudeac",
+      "metadata": {
+        "location": {
+          "city": "Lorient_KMA",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 3.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_high_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Vannes_KBE to Lorient_KMA",
+      "metadata": {
+        "location": {
+          "city": "Vannes_KBE",
+          "region": "RLD",
+          "latitude": 2.0,
+          "longitude": 4.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_medium_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Rennes_STA to Stbrieuc",
+      "metadata": {
+        "location": {
+          "city": "Rennes_STA",
+          "region": "RLD",
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
+    },
+    {
+      "uid": "west edfa in Brest_KLA to Morlaix",
+      "metadata": {
+        "location": {
+          "city": "Brest_KLA",
+          "region": "RLD",
+          "latitude": 4.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": null,
+        "delta_p": 1.0,
+        "tilt_target": 0,
+        "out_voa": null
+      }
     }
   ],
   "connections": [
     {
       "from_node": "roadm Lannion_CAS",
+      "to_node": "east edfa in Lannion_CAS to Corlay"
+    },
+    {
+      "from_node": "east edfa in Lannion_CAS to Corlay",
       "to_node": "fiber (Lannion_CAS → Corlay)-F061"
     },
     {
       "from_node": "fiber (Corlay → Lannion_CAS)-F061",
+      "to_node": "west edfa in Lannion_CAS to Corlay"
+    },
+    {
+      "from_node": "west edfa in Lannion_CAS to Corlay",
       "to_node": "roadm Lannion_CAS"
     },
     {
       "from_node": "roadm Lannion_CAS",
+      "to_node": "east edfa in Lannion_CAS to Stbrieuc"
+    },
+    {
+      "from_node": "east edfa in Lannion_CAS to Stbrieuc",
       "to_node": "fiber (Lannion_CAS → Stbrieuc)-F056"
     },
     {
       "from_node": "fiber (Stbrieuc → Lannion_CAS)-F056",
+      "to_node": "west edfa in Lannion_CAS to Stbrieuc"
+    },
+    {
+      "from_node": "west edfa in Lannion_CAS to Stbrieuc",
       "to_node": "roadm Lannion_CAS"
     },
     {
       "from_node": "roadm Lannion_CAS",
+      "to_node": "east edfa in Lannion_CAS to Morlaix"
+    },
+    {
+      "from_node": "east edfa in Lannion_CAS to Morlaix",
       "to_node": "fiber (Lannion_CAS → Morlaix)-F059"
     },
     {
       "from_node": "fiber (Morlaix → Lannion_CAS)-F059",
+      "to_node": "west edfa in Lannion_CAS to Morlaix"
+    },
+    {
+      "from_node": "west edfa in Lannion_CAS to Morlaix",
       "to_node": "roadm Lannion_CAS"
     },
     {
@@ -684,18 +1110,34 @@
     },
     {
       "from_node": "roadm Lorient_KMA",
+      "to_node": "east edfa in Lorient_KMA to Loudeac"
+    },
+    {
+      "from_node": "east edfa in Lorient_KMA to Loudeac",
       "to_node": "fiber (Lorient_KMA → Loudeac)-F054"
     },
     {
       "from_node": "fiber (Loudeac → Lorient_KMA)-F054",
+      "to_node": "west edfa in Lorient_KMA to Loudeac"
+    },
+    {
+      "from_node": "west edfa in Lorient_KMA to Loudeac",
       "to_node": "roadm Lorient_KMA"
     },
     {
       "from_node": "roadm Lorient_KMA",
+      "to_node": "east edfa in Lorient_KMA to Vannes_KBE"
+    },
+    {
+      "from_node": "east edfa in Lorient_KMA to Vannes_KBE",
       "to_node": "fiber (Lorient_KMA → Vannes_KBE)-F055"
     },
     {
       "from_node": "fiber (Vannes_KBE → Lorient_KMA)-F055",
+      "to_node": "west edfa in Lorient_KMA to Vannes_KBE"
+    },
+    {
+      "from_node": "west edfa in Lorient_KMA to Vannes_KBE",
       "to_node": "roadm Lorient_KMA"
     },
     {
@@ -708,10 +1150,18 @@
     },
     {
       "from_node": "roadm Vannes_KBE",
+      "to_node": "east edfa in Vannes_KBE to Lorient_KMA"
+    },
+    {
+      "from_node": "east edfa in Vannes_KBE to Lorient_KMA",
       "to_node": "fiber (Vannes_KBE → Lorient_KMA)-F055"
     },
     {
       "from_node": "fiber (Lorient_KMA → Vannes_KBE)-F055",
+      "to_node": "west edfa in Vannes_KBE to Lorient_KMA"
+    },
+    {
+      "from_node": "west edfa in Vannes_KBE to Lorient_KMA",
       "to_node": "roadm Vannes_KBE"
     },
     {
@@ -724,18 +1174,34 @@
     },
     {
       "from_node": "fiber (Lannion_CAS → Stbrieuc)-F056",
+      "to_node": "east edfa in Stbrieuc to Rennes_STA"
+    },
+    {
+      "from_node": "east edfa in Stbrieuc to Rennes_STA",
       "to_node": "fiber (Stbrieuc → Rennes_STA)-F057"
     },
     {
       "from_node": "fiber (Rennes_STA → Stbrieuc)-F057",
+      "to_node": "west edfa in Stbrieuc to Rennes_STA"
+    },
+    {
+      "from_node": "west edfa in Stbrieuc to Rennes_STA",
       "to_node": "fiber (Stbrieuc → Lannion_CAS)-F056"
     },
     {
       "from_node": "roadm Rennes_STA",
+      "to_node": "east edfa in Rennes_STA to Stbrieuc"
+    },
+    {
+      "from_node": "east edfa in Rennes_STA to Stbrieuc",
       "to_node": "fiber (Rennes_STA → Stbrieuc)-F057"
     },
     {
       "from_node": "fiber (Stbrieuc → Rennes_STA)-F057",
+      "to_node": "west edfa in Rennes_STA to Stbrieuc"
+    },
+    {
+      "from_node": "west edfa in Rennes_STA to Stbrieuc",
       "to_node": "roadm Rennes_STA"
     },
     {
@@ -764,10 +1230,18 @@
     },
     {
       "from_node": "roadm Brest_KLA",
+      "to_node": "east edfa in Brest_KLA to Morlaix"
+    },
+    {
+      "from_node": "east edfa in Brest_KLA to Morlaix",
       "to_node": "fiber (Brest_KLA → Morlaix)-F060"
     },
     {
       "from_node": "fiber (Morlaix → Brest_KLA)-F060",
+      "to_node": "west edfa in Brest_KLA to Morlaix"
+    },
+    {
+      "from_node": "west edfa in Brest_KLA to Morlaix",
       "to_node": "roadm Brest_KLA"
     },
     {
@@ -780,18 +1254,34 @@
     },
     {
       "from_node": "fiber (Brest_KLA → Quimper)-",
+      "to_node": "west edfa in Quimper"
+    },
+    {
+      "from_node": "west edfa in Quimper",
       "to_node": "fiber (Quimper → Lorient_KMA)-"
     },
     {
       "from_node": "fiber (Lorient_KMA → Quimper)-",
+      "to_node": "east edfa in Quimper"
+    },
+    {
+      "from_node": "east edfa in Quimper",
       "to_node": "fiber (Quimper → Brest_KLA)-"
     },
     {
       "from_node": "fiber (Vannes_KBE → Ploermel)-",
+      "to_node": "west edfa in Ploermel"
+    },
+    {
+      "from_node": "west edfa in Ploermel",
       "to_node": "fiber (Ploermel → Rennes_STA)-"
     },
     {
       "from_node": "fiber (Rennes_STA → Ploermel)-",
+      "to_node": "east edfa in Ploermel"
+    },
+    {
+      "from_node": "east edfa in Ploermel",
       "to_node": "fiber (Ploermel → Vannes_KBE)-"
     },
     {
@@ -835,4 +1325,4 @@
       "to_node": "trx Brest_KLA"
     }
   ]
-}
+}

gnpy/example-data/meshTopologyExampleV2_services.json

@@ -2,10 +2,11 @@
   "path-request": [
     {
       "request-id": "0",
-      "source": "Lorient_KMA",
-      "destination": "Vannes_KBE",
+      "source": "trx Lorient_KMA",
+      "destination": "trx Vannes_KBE",
       "src-tp-id": "trx Lorient_KMA",
       "dst-tp-id": "trx Vannes_KBE",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -13,8 +14,8 @@
           "trx_mode": null,
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 50000000000.0,
@@ -22,17 +23,15 @@
           "output-power": 0.0012589254117941673,
           "path_bandwidth": 100000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "1",
-      "source": "Brest_KLA",
-      "destination": "Vannes_KBE",
+      "source": "trx Brest_KLA",
+      "destination": "trx Vannes_KBE",
       "src-tp-id": "trx Brest_KLA",
       "dst-tp-id": "trx Vannes_KBE",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -40,8 +39,8 @@
           "trx_mode": "mode 1",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 50000000000.0,
@@ -50,66 +49,42 @@
           "path_bandwidth": 200000000000.0
         }
       },
-      "optimizations": {
-        "explicit-route-include-objects": [
+      "explicit-route-objects": {
+        "route-object-include-exclude": [
           {
+            "explicit-route-usage": "route-include-ero",
             "index": 0,
-            "unnumbered-hop": {
+            "num-unnum-hop": {
               "node-id": "roadm Brest_KLA",
               "link-tp-id": "link-tp-id is not used",
-              "hop-type": "loose",
-              "direction": "direction is not used"
-            },
-            "label-hop": {
-              "te-label": {
-                "generic": "generic is not used",
-                "direction": "direction is not used"
-              }
+              "hop-type": "LOOSE"
             }
           },
           {
+            "explicit-route-usage": "route-include-ero",
             "index": 1,
-            "unnumbered-hop": {
+            "num-unnum-hop": {
               "node-id": "roadm Lannion_CAS",
               "link-tp-id": "link-tp-id is not used",
-              "hop-type": "loose",
-              "direction": "direction is not used"
-            },
-            "label-hop": {
-              "te-label": {
-                "generic": "generic is not used",
-                "direction": "direction is not used"
-              }
+              "hop-type": "LOOSE"
             }
           },
           {
+            "explicit-route-usage": "route-include-ero",
             "index": 2,
-            "unnumbered-hop": {
+            "num-unnum-hop": {
               "node-id": "roadm Lorient_KMA",
               "link-tp-id": "link-tp-id is not used",
-              "hop-type": "loose",
-              "direction": "direction is not used"
-            },
-            "label-hop": {
-              "te-label": {
-                "generic": "generic is not used",
-                "direction": "direction is not used"
-              }
+              "hop-type": "LOOSE"
             }
           },
           {
+            "explicit-route-usage": "route-include-ero",
             "index": 3,
-            "unnumbered-hop": {
+            "num-unnum-hop": {
               "node-id": "roadm Vannes_KBE",
               "link-tp-id": "link-tp-id is not used",
-              "hop-type": "loose",
-              "direction": "direction is not used"
-            },
-            "label-hop": {
-              "te-label": {
-                "generic": "generic is not used",
-                "direction": "direction is not used"
-              }
+              "hop-type": "LOOSE"
             }
           }
         ]
@@ -117,10 +92,11 @@
     },
     {
       "request-id": "3",
-      "source": "Lannion_CAS",
-      "destination": "Rennes_STA",
+      "source": "trx Lannion_CAS",
+      "destination": "trx Rennes_STA",
       "src-tp-id": "trx Lannion_CAS",
       "dst-tp-id": "trx Rennes_STA",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -128,8 +104,8 @@
           "trx_mode": "mode 1",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 50000000000.0,
@@ -137,17 +113,15 @@
           "output-power": null,
           "path_bandwidth": 60000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "4",
-      "source": "Rennes_STA",
-      "destination": "Lannion_CAS",
+      "source": "trx Rennes_STA",
+      "destination": "trx Lannion_CAS",
       "src-tp-id": "trx Rennes_STA",
       "dst-tp-id": "trx Lannion_CAS",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -155,8 +129,8 @@
           "trx_mode": null,
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 75000000000.0,
@@ -164,17 +138,15 @@
           "output-power": 0.0019952623149688794,
           "path_bandwidth": 150000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "5",
-      "source": "Rennes_STA",
-      "destination": "Lannion_CAS",
+      "source": "trx Rennes_STA",
+      "destination": "trx Lannion_CAS",
       "src-tp-id": "trx Rennes_STA",
       "dst-tp-id": "trx Lannion_CAS",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -182,8 +154,8 @@
           "trx_mode": "mode 2",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 75000000000.0,
@@ -191,17 +163,15 @@
           "output-power": 0.0019952623149688794,
           "path_bandwidth": 20000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "6",
-      "source": "Lannion_CAS",
-      "destination": "Lorient_KMA",
+      "source": "trx Lannion_CAS",
+      "destination": "trx Lorient_KMA",
       "src-tp-id": "trx Lannion_CAS",
       "dst-tp-id": "trx Lorient_KMA",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -209,8 +179,8 @@
           "trx_mode": "mode 1",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 50000000000.0,
@@ -218,17 +188,15 @@
           "output-power": 0.001,
           "path_bandwidth": 300000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "7",
-      "source": "Lannion_CAS",
-      "destination": "Lorient_KMA",
+      "source": "trx Lannion_CAS",
+      "destination": "trx Lorient_KMA",
       "src-tp-id": "trx Lannion_CAS",
       "dst-tp-id": "trx Lorient_KMA",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -236,8 +204,8 @@
           "trx_mode": "mode 1",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 50000000000.0,
@@ -245,17 +213,15 @@
           "output-power": 0.001,
           "path_bandwidth": 400000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     },
     {
       "request-id": "7b",
-      "source": "Lannion_CAS",
-      "destination": "Lorient_KMA",
+      "source": "trx Lannion_CAS",
+      "destination": "trx Lorient_KMA",
       "src-tp-id": "trx Lannion_CAS",
       "dst-tp-id": "trx Lorient_KMA",
+      "bidirectional": false,
       "path-constraints": {
         "te-bandwidth": {
           "technology": "flexi-grid",
@@ -263,8 +229,8 @@
           "trx_mode": "mode 1",
           "effective-freq-slot": [
             {
-              "n": "null",
-              "m": "null"
+              "N": "null",
+              "M": "null"
             }
           ],
           "spacing": 75000000000.0,
@@ -272,9 +238,6 @@
           "output-power": 0.001,
           "path_bandwidth": 400000000000.0
         }
-      },
-      "optimizations": {
-        "explicit-route-include-objects": []
       }
     }
   ],
@@ -282,9 +245,8 @@
     {
       "synchronization-id": "3",
       "svec": {
-        "relaxable": "False",
-        "link-diverse": "True",
-        "node-diverse": "True",
+        "relaxable": "false",
+        "disjointness": "node link",
         "request-id-number": [
           "3",
           "1"
@@ -294,9 +256,8 @@
     {
       "synchronization-id": "4",
       "svec": {
-        "relaxable": "False",
-        "link-diverse": "True",
-        "node-diverse": "True",
+        "relaxable": "false",
+        "disjointness": "node link",
         "request-id-number": [
           "4",
           "5"

gnpy/example-data/raman_edfa_example_network.json

@@ -0,0 +1,98 @@
+{
+  "elements": [
+    {
+      "uid": "Site_A",
+      "type": "Transceiver",
+      "metadata": {
+        "location": {
+          "latitude": 0,
+          "longitude": 0,
+          "city": "Site A",
+          "region": ""
+        }
+      }
+    },
+    {
+      "uid": "Span1",
+      "type": "RamanFiber",
+      "type_variety": "SSMF",
+      "operational": {
+        "temperature": 283,
+        "raman_pumps": [
+          {
+            "power": 200e-3,
+            "frequency": 205e12,
+            "propagation_direction": "counterprop"
+          },
+          {
+            "power": 206e-3,
+            "frequency": 201e12,
+            "propagation_direction": "counterprop"
+          }
+        ]
+      },
+      "params": {
+        "type_variety": "SSMF",
+        "length": 80.0,
+        "loss_coef": 0.2,
+        "length_units": "km",
+        "att_in": 0,
+        "con_in": 0.5,
+        "con_out": 0.5
+      },
+      "metadata": {
+        "location": {
+          "latitude": 1,
+          "longitude": 0,
+          "city": null,
+          "region": ""
+        }
+      }
+    },
+    {
+      "uid": "Edfa1",
+      "type": "Edfa",
+      "type_variety": "std_low_gain",
+      "operational": {
+        "gain_target": 15.0,
+        "delta_p": -2,
+        "tilt_target": 0,
+        "out_voa": 0
+      },
+      "metadata": {
+        "location": {
+          "latitude": 2,
+          "longitude": 0,
+          "city": null,
+          "region": ""
+        }
+      }
+    },
+    {
+      "uid": "Site_B",
+      "type": "Transceiver",
+      "metadata": {
+        "location": {
+          "latitude": 2,
+          "longitude": 0,
+          "city": "Site B",
+          "region": ""
+        }
+      }
+    }
+  ],
+  "connections": [
+    {
+      "from_node": "Site_A",
+      "to_node": "Span1"
+    },
+    {
+      "from_node": "Span1",
+      "to_node": "Edfa1"
+    },
+    {
+      "from_node": "Edfa1",
+      "to_node": "Site_B"
+    }
+  ]
+}

gnpy/example-data/sim_params.json

@@ -0,0 +1,14 @@
+{
+  "raman_parameters": {
+    "flag_raman": true,
+    "space_resolution": 10e3,
+    "tolerance": 1e-8
+  },
+  "nli_parameters": {
+  	"nli_method_name": "ggn_spectrally_separated",
+  	"wdm_grid_size": 50e9,
+  	"dispersion_tolerance": 1,
+  	"phase_shift_tolerance": 0.1,
+	"computed_channels": [1, 18, 37, 56, 75] 
+  }
+}

gnpy/example-data/std_medium_gain_advanced_config.json

@@ -0,0 +1,304 @@
+{
+    "nf_fit_coeff": [
+        0.000168241,
+        0.0469961,
+        0.0359549,
+        5.82851
+    ],
+    "f_min": 191.35e12,
+    "f_max": 196.1e12,
+    "nf_ripple": [
+        0.4372876328262819,
+        0.4372876328262819,
+        0.41270842850729195,
+        0.38814205928193013,
+        0.36358851509924695,
+        0.3390191214858807,
+        0.30474360397422756,
+        0.27048596623174515,
+        0.23624619427167134,
+        0.202035284929368,
+        0.1694483010211072,
+        0.13687829834471027,
+        0.1043252636301016,
+        0.07184040799914815,
+        0.061288823415841555,
+        0.050742731588695494,
+        0.04020212822983975,
+        0.029667009055877668,
+        0.01913736978785662,
+        0.00861320615127981,
+        -0.010157321677553965,
+        -0.028982516728038848,
+        -0.04779792991567815,
+        -0.06660356886269536,
+        -0.06256260169582961,
+        -0.05832916277634124,
+        -0.05409792133358102,
+        -0.04990610405914272,
+        -0.05078533294804249,
+        -0.05166410580536087,
+        -0.05254242298580185,
+        -0.05342028484370278,
+        -0.051742390657545205,
+        -0.050039429413028365,
+        -0.048337350303318156,
+        -0.04663615264317309,
+        -0.04493583574805963,
+        -0.043236398934156144,
+        -0.035622012697103154,
+        -0.027999803010447587,
+        -0.02038153550619876,
+        -0.012779471908040341,
+        -0.006436207679519103,
+        -9.622162373026585e-05,
+        0.006240488799898697,
+        0.012573926129294415,
+        0.021418708618354456,
+        0.030289222542492025,
+        0.03915515813685565,
+        0.047899419704645264,
+        0.04256372893215024,
+        0.03723078993416436,
+        0.03190060058247842,
+        0.02657315875107553,
+        0.021248462316134083,
+        0.01605877647020772,
+        0.02326948274513522,
+        0.03047647598902483,
+        0.037679759069084225,
+        0.044883315610536455,
+        0.052470799141237305,
+        0.06005437964543287,
+        0.0676340601339394,
+        0.07521193198077789,
+        0.08415906712621996,
+        0.09310160456603413,
+        0.1020395478432815,
+        0.11079585523492333,
+        0.1018180306253394,
+        0.09284481475528361,
+        0.0838762040768461,
+        0.07482015390297145,
+        0.05670549786742816,
+        0.03860013139908377,
+        0.020504047353947653,
+        0.0024172385953583004,
+        -0.015660302006048,
+        -0.03372858157230583,
+        -0.07037375788020579,
+        -0.10709599992470213,
+        -0.14379944379052215,
+        -0.18048410390821285,
+        -0.20911178784023846,
+        -0.23772399031437283,
+        -0.26632156113294336,
+        -0.2949045115165272,
+        -0.30206775396360075,
+        -0.30915729645781326,
+        -0.31624321721895354,
+        -0.3233255190215882,
+        -0.32037911876162584,
+        -0.3172854168606314,
+        -0.31419329378173544,
+        -0.31110274831665313,
+        -0.3110761646066259,
+        -0.3110761646066259
+    ],
+    "dgt": [
+        1.0,
+        1.017807767853702,
+        1.0356155337864215,
+        1.0534217504465226,
+        1.0712204022764056,
+        1.0895983485572227,
+        1.108555289615659,
+        1.1280891949729075,
+        1.1476135933863398,
+        1.1672278304018044,
+        1.1869318618366975,
+        1.2067249615595257,
+        1.2264996957264114,
+        1.2428104897182262,
+        1.2556591482982988,
+        1.2650555289898042,
+        1.2744470198196236,
+        1.2838336236692311,
+        1.2932153453410835,
+        1.3040618749785347,
+        1.316383926863083,
+        1.3301807335621048,
+        1.3439818461440451,
+        1.3598972673004606,
+        1.3779439775587023,
+        1.3981208704326855,
+        1.418273806730323,
+        1.4340878115214444,
+        1.445565137158368,
+        1.45273959485914,
+        1.4599103316162523,
+        1.4670307626366115,
+        1.474100442252211,
+        1.48111939735681,
+        1.488134243479226,
+        1.495145456062699,
+        1.502153039909686,
+        1.5097346239790443,
+        1.5178910621476225,
+        1.5266220576235803,
+        1.5353620432989845,
+        1.545374152761467,
+        1.5566577309558969,
+        1.569199764184379,
+        1.5817353179379183,
+        1.5986915141218316,
+        1.6201194134191075,
+        1.6460167077689267,
+        1.6719047669939942,
+        1.6918150918099673,
+        1.7057507692361864,
+        1.7137640932265894,
+        1.7217732861435076,
+        1.7297783508684146,
+        1.737780757913635,
+        1.7459181197626403,
+        1.7541903672600494,
+        1.7625959636196327,
+        1.7709972329654864,
+        1.7793941781790852,
+        1.7877868031023945,
+        1.7961751115773796,
+        1.8045606557581335,
+        1.8139629377087627,
+        1.824381436842932,
+        1.835814081380705,
+        1.847275503201129,
+        1.862235672444246,
+        1.8806927939516411,
+        1.9026104247588487,
+        1.9245345552113182,
+        1.9482128147680253,
+        1.9736443063300082,
+        2.0008103857988204,
+        2.0279625371819305,
+        2.055100772005235,
+        2.082225099873648,
+        2.1183028432496016,
+        2.16337565384239,
+        2.2174389328192197,
+        2.271520771371253,
+        2.322373696229342,
+        2.3699990328716107,
+        2.414398437185221,
+        2.4587748041127506,
+        2.499446286796604,
+        2.5364027376452056,
+        2.5696460593920065,
+        2.602860350286428,
+        2.630396440815385,
+        2.6521732021128046,
+        2.6681935771243177,
+        2.6841217449620203,
+        2.6947834587664494,
+        2.705443819238505,
+        2.714526681131686
+    ],
+    "gain_ripple": [
+        0.07704745697916238,
+        0.06479749697916048,
+        0.05257029697916238,
+        0.040326236979161934,
+        0.028098946979159933,
+        0.01393231697916164,
+        -0.0021726530208390216,
+        -0.01819858302084043,
+        -0.03218106302083967,
+        -0.042428283020839785,
+        -0.05095282302083959,
+        -0.05947139302083926,
+        -0.06968090302083851,
+        -0.07844600302084004,
+        -0.08407607302083875,
+        -0.0865687230208394,
+        -0.08906007302083907,
+        -0.0913487130208388,
+        -0.09343261302083761,
+        -0.09717347302083823,
+        -0.1027863830208382,
+        -0.11089282302084058,
+        -0.11963431302083904,
+        -0.1279646530208396,
+        -0.13525493302083902,
+        -0.1409032730208395,
+        -0.14591937302083835,
+        -0.14823350302084037,
+        -0.1484450830208388,
+        -0.1455411330208385,
+        -0.14160178302083892,
+        -0.1353792530208402,
+        -0.12789859302083784,
+        -0.11916081302083725,
+        -0.11041488302083735,
+        -0.10103437302083762,
+        -0.09101254302083817,
+        -0.07868024302083754,
+        -0.06468462302083822,
+        -0.051112303020840244,
+        -0.039618433020837784,
+        -0.028748483020837767,
+        -0.016475303020840215,
+        -0.006936193020838033,
+        -0.0015763130208377163,
+        0.0007104669791608842,
+        0.0040435869791615175,
+        0.006965146979162284,
+        0.00842583697916055,
+        0.00874012697916271,
+        0.00936596697916059,
+        0.01030063697916006,
+        0.011234826979162449,
+        0.013321846979160057,
+        0.01659282697915998,
+        0.023488786979161347,
+        0.03285456697916089,
+        0.04072968697916224,
+        0.04467697697916151,
+        0.04551704697916037,
+        0.04717897697916129,
+        0.04946107697915991,
+        0.05154489697916276,
+        0.05447361697916264,
+        0.05848224697916038,
+        0.06916723697916183,
+        0.08548825697916129,
+        0.10802383697916085,
+        0.13114358697916018,
+        0.15216302697916007,
+        0.17037189697916233,
+        0.1767381569791624,
+        0.1739275269791598,
+        0.15945681697916214,
+        0.14239527697916188,
+        0.12276252697916235,
+        0.10313984697916112,
+        0.08731066697916035,
+        0.07533675697916209,
+        0.07114372697916238,
+        0.07094413697916124,
+        0.07091459697916136,
+        0.0670723869791594,
+        0.054956336979159914,
+        0.038328296979159404,
+        0.017572956979162058,
+        -0.0028138630208403015,
+        -0.016792253020838643,
+        -0.0246928330208398,
+        -0.018326963020840026,
+        -0.0036199830208403228,
+        0.02602813697916062,
+        0.06245819697916133,
+        0.09542181697916163,
+        0.11822862697916037,
+        0.1359703369791596
+    ]
+}

gnpy/example-data/write_path_jsontocsv.py

@@ -14,14 +14,14 @@ See: draft-ietf-teas-yang-path-computation-01.txt
 from argparse import ArgumentParser
 from pathlib import Path
 from json import loads
-from gnpy.core.equipment  import load_equipment
-from gnpy.core.request  import jsontocsv
+from gnpy.tools.json_io import load_equipment
+from gnpy.topology.request import jsontocsv
 
 
-parser = ArgumentParser(description = 'A function that writes json path results in an excel sheet.')
-parser.add_argument('filename', nargs='?', type = Path)
-parser.add_argument('output_filename', nargs='?', type = Path)
-parser.add_argument('eqpt_filename', nargs='?', type = Path, default=Path(__file__).parent / 'eqpt_config.json')
+parser = ArgumentParser(description='A function that writes json path results in an excel sheet.')
+parser.add_argument('filename', nargs='?', type=Path)
+parser.add_argument('output_filename', nargs='?', type=Path)
+parser.add_argument('eqpt_filename', nargs='?', type=Path, default=Path(__file__).parent / 'eqpt_config.json')
 
 if __name__ == '__main__':
     args = parser.parse_args()
@@ -32,5 +32,4 @@ if __name__ == '__main__':
             json_data = loads(f.read())
             equipment = load_equipment(args.eqpt_filename)
             print(f'Writing in {args.output_filename}')
-            jsontocsv(json_data,equipment,file)
-
+            jsontocsv(json_data, equipment, file)

gnpy/tools/__init__.py

@@ -0,0 +1,5 @@
+'''
+Processing of data via :py:mod:`.json_io`.
+Utilities for Excel conversion in :py:mod:`.convert` and :py:mod:`.service_sheet`.
+Example code in :py:mod:`.cli_examples` and :py:mod:`.plots`.
+'''

gnpy/tools/cli_examples.py

@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.tools.cli_examples
+=======================
+
+Common code for CLI examples
+'''
+
+import argparse
+import logging
+import os.path
+import sys
+from math import ceil
+from numpy import linspace, mean
+from pathlib import Path
+import gnpy.core.ansi_escapes as ansi_escapes
+from gnpy.core.elements import Transceiver, Fiber, RamanFiber
+from gnpy.core.equipment import trx_mode_params
+import gnpy.core.exceptions as exceptions
+from gnpy.core.network import build_network
+from gnpy.core.parameters import SimParams
+from gnpy.core.science_utils import Simulation
+from gnpy.core.utils import db2lin, lin2db, automatic_nch
+from gnpy.topology.request import (ResultElement, jsontocsv, compute_path_dsjctn, requests_aggregation,
+                                   BLOCKING_NOPATH, correct_json_route_list,
+                                   deduplicate_disjunctions, compute_path_with_disjunction,
+                                   PathRequest, compute_constrained_path, propagate)
+from gnpy.topology.spectrum_assignment import build_oms_list, pth_assign_spectrum
+from gnpy.tools.json_io import load_equipment, load_network, load_json, load_requests, save_network, \
+                               requests_from_json, disjunctions_from_json, save_json
+from gnpy.tools.plots import plot_baseline, plot_results
+
+_logger = logging.getLogger(__name__)
+_examples_dir = Path(__file__).parent.parent / 'example-data'
+_help_footer = '''
+This program is part of GNPy, https://github.com/TelecomInfraProject/oopt-gnpy
+
+Learn more at https://gnpy.readthedocs.io/
+
+'''
+_help_fname_json = 'FILE.json'
+_help_fname_json_csv = 'FILE.(json|csv)'
+
+
+def show_example_data_dir():
+    print(f'{_examples_dir}/')
+
+
+def load_common_data(equipment_filename, topology_filename, simulation_filename, save_raw_network_filename):
+    '''Load common configuration from JSON files'''
+
+    try:
+        equipment = load_equipment(equipment_filename)
+        network = load_network(topology_filename, equipment)
+        if save_raw_network_filename is not None:
+            save_network(network, save_raw_network_filename)
+            print(f'{ansi_escapes.blue}Raw network (no optimizations) saved to {save_raw_network_filename}{ansi_escapes.reset}')
+        sim_params = SimParams(**load_json(simulation_filename)) if simulation_filename is not None else None
+        if not sim_params:
+            if next((node for node in network if isinstance(node, RamanFiber)), None) is not None:
+                print(f'{ansi_escapes.red}Invocation error:{ansi_escapes.reset} '
+                      f'RamanFiber requires passing simulation params via --sim-params')
+                sys.exit(1)
+        else:
+            Simulation.set_params(sim_params)
+    except exceptions.EquipmentConfigError as e:
+        print(f'{ansi_escapes.red}Configuration error in the equipment library:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.NetworkTopologyError as e:
+        print(f'{ansi_escapes.red}Invalid network definition:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.ParametersError as e:
+        print(f'{ansi_escapes.red}Simulation parameters error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.ConfigurationError as e:
+        print(f'{ansi_escapes.red}Configuration error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.ServiceError as e:
+        print(f'{ansi_escapes.red}Service error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+
+    return (equipment, network)
+
+
+def _setup_logging(args):
+    logging.basicConfig(level={2: logging.DEBUG, 1: logging.INFO, 0: logging.CRITICAL}.get(args.verbose, logging.DEBUG))
+
+
+def _add_common_options(parser: argparse.ArgumentParser, network_default: Path):
+    parser.add_argument('topology', nargs='?', type=Path, metavar='NETWORK-TOPOLOGY.(json|xls|xlsx)',
+                        default=network_default,
+                        help='Input network topology')
+    parser.add_argument('-v', '--verbose', action='count', default=0,
+                        help='Increase verbosity (can be specified several times)')
+    parser.add_argument('-e', '--equipment', type=Path, metavar=_help_fname_json,
+                        default=_examples_dir / 'eqpt_config.json', help='Equipment library')
+    parser.add_argument('--sim-params', type=Path, metavar=_help_fname_json,
+                        default=None, help='Path to the JSON containing simulation parameters (required for Raman). '
+                                           f'Example: {_examples_dir / "sim_params.json"}')
+    parser.add_argument('--save-network', type=Path, metavar=_help_fname_json,
+                        help='Save the final network as a JSON file')
+    parser.add_argument('--save-network-before-autodesign', type=Path, metavar=_help_fname_json,
+                        help='Dump the network into a JSON file prior to autodesign')
+
+
+def transmission_main_example(args=None):
+    parser = argparse.ArgumentParser(
+        description='Send a full spectrum load through the network from point A to point B',
+        epilog=_help_footer,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        )
+    _add_common_options(parser, network_default=_examples_dir / 'edfa_example_network.json')
+    parser.add_argument('--show-channels', action='store_true', help='Show final per-channel OSNR and GSNR summary')
+    parser.add_argument('-pl', '--plot', action='store_true')
+    parser.add_argument('-l', '--list-nodes', action='store_true', help='list all transceiver nodes')
+    parser.add_argument('-po', '--power', default=0, help='channel ref power in dBm')
+    parser.add_argument('source', nargs='?', help='source node')
+    parser.add_argument('destination', nargs='?', help='destination node')
+
+    args = parser.parse_args(args if args is not None else sys.argv[1:])
+    _setup_logging(args)
+
+    (equipment, network) = load_common_data(args.equipment, args.topology, args.sim_params, args.save_network_before_autodesign)
+
+    if args.plot:
+        plot_baseline(network)
+
+    transceivers = {n.uid: n for n in network.nodes() if isinstance(n, Transceiver)}
+
+    if not transceivers:
+        sys.exit('Network has no transceivers!')
+    if len(transceivers) < 2:
+        sys.exit('Network has only one transceiver!')
+
+    if args.list_nodes:
+        for uid in transceivers:
+            print(uid)
+        sys.exit()
+
+    # First try to find exact match if source/destination provided
+    if args.source:
+        source = transceivers.pop(args.source, None)
+        valid_source = True if source else False
+    else:
+        source = None
+        _logger.info('No source node specified: picking random transceiver')
+
+    if args.destination:
+        destination = transceivers.pop(args.destination, None)
+        valid_destination = True if destination else False
+    else:
+        destination = None
+        _logger.info('No destination node specified: picking random transceiver')
+
+    # If no exact match try to find partial match
+    if args.source and not source:
+        # TODO code a more advanced regex to find nodes match
+        source = next((transceivers.pop(uid) for uid in transceivers
+                       if args.source.lower() in uid.lower()), None)
+
+    if args.destination and not destination:
+        # TODO code a more advanced regex to find nodes match
+        destination = next((transceivers.pop(uid) for uid in transceivers
+                            if args.destination.lower() in uid.lower()), None)
+
+    # If no partial match or no source/destination provided pick random
+    if not source:
+        source = list(transceivers.values())[0]
+        del transceivers[source.uid]
+
+    if not destination:
+        destination = list(transceivers.values())[0]
+
+    _logger.info(f'source = {args.source!r}')
+    _logger.info(f'destination = {args.destination!r}')
+
+    params = {}
+    params['request_id'] = 0
+    params['trx_type'] = ''
+    params['trx_mode'] = ''
+    params['source'] = source.uid
+    params['destination'] = destination.uid
+    params['bidir'] = False
+    params['nodes_list'] = [destination.uid]
+    params['loose_list'] = ['strict']
+    params['format'] = ''
+    params['path_bandwidth'] = 0
+    trx_params = trx_mode_params(equipment)
+    if args.power:
+        trx_params['power'] = db2lin(float(args.power)) * 1e-3
+    params.update(trx_params)
+    req = PathRequest(**params)
+
+    power_mode = equipment['Span']['default'].power_mode
+    print('\n'.join([f'Power mode is set to {power_mode}',
+                     f'=> it can be modified in eqpt_config.json - Span']))
+
+    pref_ch_db = lin2db(req.power * 1e3)  # reference channel power / span (SL=20dB)
+    pref_total_db = pref_ch_db + lin2db(req.nb_channel)  # reference total power / span (SL=20dB)
+    try:
+        build_network(network, equipment, pref_ch_db, pref_total_db)
+    except exceptions.NetworkTopologyError as e:
+        print(f'{ansi_escapes.red}Invalid network definition:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.ConfigurationError as e:
+        print(f'{ansi_escapes.red}Configuration error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    path = compute_constrained_path(network, req)
+
+    spans = [s.params.length for s in path if isinstance(s, RamanFiber) or isinstance(s, Fiber)]
+    print(f'\nThere are {len(spans)} fiber spans over {sum(spans)/1000:.0f} km between {source.uid} '
+          f'and {destination.uid}')
+    print(f'\nNow propagating between {source.uid} and {destination.uid}:')
+
+    try:
+        p_start, p_stop, p_step = equipment['SI']['default'].power_range_db
+        p_num = abs(int(round((p_stop - p_start) / p_step))) + 1 if p_step != 0 else 1
+        power_range = list(linspace(p_start, p_stop, p_num))
+    except TypeError:
+        print('invalid power range definition in eqpt_config, should be power_range_db: [lower, upper, step]')
+        power_range = [0]
+
+    if not power_mode:
+        # power cannot be changed in gain mode
+        power_range = [0]
+    for dp_db in power_range:
+        req.power = db2lin(pref_ch_db + dp_db) * 1e-3
+        if power_mode:
+            print(f'\nPropagating with input power = {ansi_escapes.cyan}{lin2db(req.power*1e3):.2f} dBm{ansi_escapes.reset}:')
+        else:
+            print(f'\nPropagating in {ansi_escapes.cyan}gain mode{ansi_escapes.reset}: power cannot be set manually')
+        infos = propagate(path, req, equipment)
+        if len(power_range) == 1:
+            for elem in path:
+                print(elem)
+            if power_mode:
+                print(f'\nTransmission result for input power = {lin2db(req.power*1e3):.2f} dBm:')
+            else:
+                print(f'\nTransmission results:')
+            print(f'  Final GSNR (0.1 nm): {ansi_escapes.cyan}{mean(destination.snr_01nm):.02f} dB{ansi_escapes.reset}')
+        else:
+            print(path[-1])
+
+    if args.save_network is not None:
+        save_network(network, args.save_network)
+        print(f'{ansi_escapes.blue}Network (after autodesign) saved to {args.save_network}{ansi_escapes.reset}')
+
+    if args.show_channels:
+        print('\nThe GSNR per channel at the end of the line is:')
+        print(
+            '{:>5}{:>26}{:>26}{:>28}{:>28}{:>28}' .format(
+                'Ch. #',
+                'Channel frequency (THz)',
+                'Channel power (dBm)',
+                'OSNR ASE (signal bw, dB)',
+                'SNR NLI (signal bw, dB)',
+                'GSNR (signal bw, dB)'))
+        for final_carrier, ch_osnr, ch_snr_nl, ch_snr in zip(
+                infos.carriers, path[-1].osnr_ase, path[-1].osnr_nli, path[-1].snr):
+            ch_freq = final_carrier.frequency * 1e-12
+            ch_power = lin2db(final_carrier.power.signal * 1e3)
+            print(
+                '{:5}{:26.2f}{:26.2f}{:28.2f}{:28.2f}{:28.2f}' .format(
+                    final_carrier.channel_number, round(
+                        ch_freq, 2), round(
+                        ch_power, 2), round(
+                        ch_osnr, 2), round(
+                        ch_snr_nl, 2), round(
+                            ch_snr, 2)))
+
+    if not args.source:
+        print(f'\n(No source node specified: picked {source.uid})')
+    elif not valid_source:
+        print(f'\n(Invalid source node {args.source!r} replaced with {source.uid})')
+
+    if not args.destination:
+        print(f'\n(No destination node specified: picked {destination.uid})')
+    elif not valid_destination:
+        print(f'\n(Invalid destination node {args.destination!r} replaced with {destination.uid})')
+
+    if args.plot:
+        plot_results(network, path, source, destination)
+
+
+def _path_result_json(pathresult):
+    return {'response': [n.json for n in pathresult]}
+
+
+def path_requests_run(args=None):
+    parser = argparse.ArgumentParser(
+        description='Compute performance for a list of services provided in a json file or an excel sheet',
+        epilog=_help_footer,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        )
+    _add_common_options(parser, network_default=_examples_dir / 'meshTopologyExampleV2.xls')
+    parser.add_argument('service_filename', nargs='?', type=Path, metavar='SERVICES-REQUESTS.(json|xls|xlsx)',
+                        default=_examples_dir / 'meshTopologyExampleV2.xls',
+                        help='Input service file')
+    parser.add_argument('-bi', '--bidir', action='store_true',
+                        help='considers that all demands are bidir')
+    parser.add_argument('-o', '--output', type=Path, metavar=_help_fname_json_csv,
+                        help='Store satisifed requests into a JSON or CSV file')
+
+    args = parser.parse_args(args if args is not None else sys.argv[1:])
+    _setup_logging(args)
+
+    _logger.info(f'Computing path requests {args.service_filename} into JSON format')
+    print(f'{ansi_escapes.blue}Computing path requests {os.path.relpath(args.service_filename)} into JSON format{ansi_escapes.reset}')
+
+    (equipment, network) = load_common_data(args.equipment, args.topology, args.sim_params, args.save_network_before_autodesign)
+
+    # Build the network once using the default power defined in SI in eqpt config
+    # TODO power density: db2linp(ower_dbm": 0)/power_dbm": 0 * nb channels as defined by
+    # spacing, f_min and f_max
+    p_db = equipment['SI']['default'].power_dbm
+
+    p_total_db = p_db + lin2db(automatic_nch(equipment['SI']['default'].f_min,
+                                             equipment['SI']['default'].f_max, equipment['SI']['default'].spacing))
+    try:
+        build_network(network, equipment, p_db, p_total_db)
+    except exceptions.NetworkTopologyError as e:
+        print(f'{ansi_escapes.red}Invalid network definition:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    except exceptions.ConfigurationError as e:
+        print(f'{ansi_escapes.red}Configuration error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    if args.save_network is not None:
+        save_network(network, args.save_network)
+        print(f'{ansi_escapes.blue}Network (after autodesign) saved to {args.save_network}{ansi_escapes.reset}')
+    oms_list = build_oms_list(network, equipment)
+
+    try:
+        data = load_requests(args.service_filename, equipment, bidir=args.bidir,
+                             network=network, network_filename=args.topology)
+        rqs = requests_from_json(data, equipment)
+    except exceptions.ServiceError as e:
+        print(f'{ansi_escapes.red}Service error:{ansi_escapes.reset} {e}')
+        sys.exit(1)
+    # check that request ids are unique. Non unique ids, may
+    # mess the computation: better to stop the computation
+    all_ids = [r.request_id for r in rqs]
+    if len(all_ids) != len(set(all_ids)):
+        for item in list(set(all_ids)):
+            all_ids.remove(item)
+        msg = f'Requests id {all_ids} are not unique'
+        _logger.critical(msg)
+        sys.exit()
+    rqs = correct_json_route_list(network, rqs)
+
+    # pths = compute_path(network, equipment, rqs)
+    dsjn = disjunctions_from_json(data)
+
+    print(f'{ansi_escapes.blue}List of disjunctions{ansi_escapes.reset}')
+    print(dsjn)
+    # need to warn or correct in case of wrong disjunction form
+    # disjunction must not be repeated with same or different ids
+    dsjn = deduplicate_disjunctions(dsjn)
+
+    # Aggregate demands with same exact constraints
+    print(f'{ansi_escapes.blue}Aggregating similar requests{ansi_escapes.reset}')
+
+    rqs, dsjn = requests_aggregation(rqs, dsjn)
+    # TODO export novel set of aggregated demands in a json file
+
+    print(f'{ansi_escapes.blue}The following services have been requested:{ansi_escapes.reset}')
+    print(rqs)
+
+    print(f'{ansi_escapes.blue}Computing all paths with constraints{ansi_escapes.reset}')
+    try:
+        pths = compute_path_dsjctn(network, equipment, rqs, dsjn)
+    except exceptions.DisjunctionError as this_e:
+        print(f'{ansi_escapes.red}Disjunction error:{ansi_escapes.reset} {this_e}')
+        sys.exit(1)
+
+    print(f'{ansi_escapes.blue}Propagating on selected path{ansi_escapes.reset}')
+    propagatedpths, reversed_pths, reversed_propagatedpths = compute_path_with_disjunction(network, equipment, rqs, pths)
+    # Note that deepcopy used in compute_path_with_disjunction returns
+    # a list of nodes which are not belonging to network (they are copies of the node objects).
+    # so there can not be propagation on these nodes.
+
+    pth_assign_spectrum(pths, rqs, oms_list, reversed_pths)
+
+    print(f'{ansi_escapes.blue}Result summary{ansi_escapes.reset}')
+    header = ['req id', '  demand', ' GSNR@bandwidth A-Z (Z-A)', ' GSNR@0.1nm A-Z (Z-A)',
+              '  Receiver minOSNR', '  mode', '  Gbit/s', '  nb of tsp pairs',
+              'N,M or blocking reason']
+    data = []
+    data.append(header)
+    for i, this_p in enumerate(propagatedpths):
+        rev_pth = reversed_propagatedpths[i]
+        if rev_pth and this_p:
+            psnrb = f'{round(mean(this_p[-1].snr),2)} ({round(mean(rev_pth[-1].snr),2)})'
+            psnr = f'{round(mean(this_p[-1].snr_01nm), 2)}' +\
+                f' ({round(mean(rev_pth[-1].snr_01nm),2)})'
+        elif this_p:
+            psnrb = f'{round(mean(this_p[-1].snr),2)}'
+            psnr = f'{round(mean(this_p[-1].snr_01nm),2)}'
+
+        try:
+            if rqs[i].blocking_reason in BLOCKING_NOPATH:
+                line = [f'{rqs[i].request_id}', f' {rqs[i].source} to {rqs[i].destination} :',
+                        f'-', f'-', f'-', f'{rqs[i].tsp_mode}', f'{round(rqs[i].path_bandwidth * 1e-9,2)}',
+                        f'-', f'{rqs[i].blocking_reason}']
+            else:
+                line = [f'{rqs[i].request_id}', f' {rqs[i].source} to {rqs[i].destination} : ', psnrb,
+                        psnr, f'-', f'{rqs[i].tsp_mode}', f'{round(rqs[i].path_bandwidth * 1e-9, 2)}',
+                        f'-', f'{rqs[i].blocking_reason}']
+        except AttributeError:
+            line = [f'{rqs[i].request_id}', f' {rqs[i].source} to {rqs[i].destination} : ', psnrb,
+                    psnr, f'{rqs[i].OSNR + equipment["SI"]["default"].sys_margins}',
+                    f'{rqs[i].tsp_mode}', f'{round(rqs[i].path_bandwidth * 1e-9,2)}',
+                    f'{ceil(rqs[i].path_bandwidth / rqs[i].bit_rate) }', f'({rqs[i].N},{rqs[i].M})']
+        data.append(line)
+
+    col_width = max(len(word) for row in data for word in row[2:])   # padding
+    firstcol_width = max(len(row[0]) for row in data)   # padding
+    secondcol_width = max(len(row[1]) for row in data)   # padding
+    for row in data:
+        firstcol = ''.join(row[0].ljust(firstcol_width))
+        secondcol = ''.join(row[1].ljust(secondcol_width))
+        remainingcols = ''.join(word.center(col_width, ' ') for word in row[2:])
+        print(f'{firstcol} {secondcol} {remainingcols}')
+    print(f'{ansi_escapes.yellow}Result summary shows mean GSNR and OSNR (average over all channels){ansi_escapes.reset}')
+
+    if args.output:
+        result = []
+        # assumes that list of rqs and list of propgatedpths have same order
+        for i, pth in enumerate(propagatedpths):
+            result.append(ResultElement(rqs[i], pth, reversed_propagatedpths[i]))
+        temp = _path_result_json(result)
+        if args.output.suffix.lower() == '.json':
+            save_json(temp, args.output)
+            print(f'{ansi_escapes.blue}Saved JSON to {args.output}{ansi_escapes.reset}')
+        elif args.output.suffix.lower() == '.csv':
+            with open(args.output, "w", encoding='utf-8') as fcsv:
+                jsontocsv(temp, equipment, fcsv)
+            print(f'{ansi_escapes.blue}Saved CSV to {args.output}{ansi_escapes.reset}')
+        else:
+            print(f'{ansi_escapes.red}Cannot save output: neither JSON nor CSV file{ansi_escapes.reset}')
+            sys.exit(1)

gnpy/tools/convert.py

@@ -0,0 +1,830 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.tools.convert
+==================
+
+This module contains utilities for converting between XLS and JSON.
+
+The input XLS file must contain sheets named "Nodes" and "Links".
+It may optionally contain a sheet named "Eqpt".
+
+In the "Nodes" sheet, only the "City" column is mandatory. The column "Type"
+can be determined automatically given the topology (e.g., if degree 2, ILA;
+otherwise, ROADM.) Incorrectly specified types (e.g., ILA for node of
+degree ≠ 2) will be automatically corrected.
+
+In the "Links" sheet, only the first three columns ("Node A", "Node Z" and
+"east Distance (km)") are mandatory.  Missing "west" information is copied from
+the "east" information so that it is possible to input undirected data.
+"""
+
+from xlrd import open_workbook
+from argparse import ArgumentParser
+from collections import namedtuple, Counter, defaultdict
+from itertools import chain
+from json import dumps
+from pathlib import Path
+from copy import copy
+from gnpy.core import ansi_escapes
+from gnpy.core.utils import silent_remove
+from gnpy.core.exceptions import NetworkTopologyError
+from gnpy.core.elements import Edfa, Fused, Fiber
+
+
+def all_rows(sh, start=0):
+    return (sh.row(x) for x in range(start, sh.nrows))
+
+
+class Node(object):
+    def __init__(self, **kwargs):
+        super(Node, self).__init__()
+        self.update_attr(kwargs)
+
+    def update_attr(self, kwargs):
+        clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
+        for k, v in self.default_values.items():
+            v = clean_kwargs.get(k, v)
+            setattr(self, k, v)
+
+    default_values = {
+        'city': '',
+        'state': '',
+        'country': '',
+        'region': '',
+        'latitude': 0,
+        'longitude': 0,
+        'node_type': 'ILA',
+        'booster_restriction': '',
+        'preamp_restriction': ''
+    }
+
+
+class Link(object):
+    """attribtes from west parse_ept_headers dict
+    +node_a, node_z, west_fiber_con_in, east_fiber_con_in
+    """
+
+    def __init__(self, **kwargs):
+        super(Link, self).__init__()
+        self.update_attr(kwargs)
+        self.distance_units = 'km'
+
+    def update_attr(self, kwargs):
+        clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
+        for k, v in self.default_values.items():
+            v = clean_kwargs.get(k, v)
+            setattr(self, k, v)
+            k = 'west' + k.split('east')[-1]
+            v = clean_kwargs.get(k, v)
+            setattr(self, k, v)
+
+    def __eq__(self, link):
+        return (self.from_city == link.from_city and self.to_city == link.to_city) \
+            or (self.from_city == link.to_city and self.to_city == link.from_city)
+
+    default_values = {
+        'from_city': '',
+        'to_city': '',
+        'east_distance': 80,
+        'east_fiber': 'SSMF',
+        'east_lineic': 0.2,
+        'east_con_in': None,
+        'east_con_out': None,
+        'east_pmd': 0.1,
+        'east_cable': ''
+    }
+
+
+class Eqpt(object):
+    def __init__(self, **kwargs):
+        super(Eqpt, self).__init__()
+        self.update_attr(kwargs)
+
+    def update_attr(self, kwargs):
+        clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
+        for k, v in self.default_values.items():
+            v_east = clean_kwargs.get(k, v)
+            setattr(self, k, v_east)
+            k = 'west' + k.split('east')[-1]
+            v_west = clean_kwargs.get(k, v)
+            setattr(self, k, v_west)
+
+    default_values = {
+        'from_city': '',
+        'to_city': '',
+        'east_amp_type': '',
+        'east_att_in': 0,
+        'east_amp_gain': None,
+        'east_amp_dp': None,
+        'east_tilt': 0,
+        'east_att_out': None
+    }
+
+
+class Roadm(object):
+    def __init__(self, **kwargs):
+        super(Roadm, self).__init__()
+        self.update_attr(kwargs)
+
+    def update_attr(self, kwargs):
+        clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
+        for k, v in self.default_values.items():
+            v = clean_kwargs.get(k, v)
+            setattr(self, k, v)
+
+    default_values = {'from_node': '',
+                      'to_node': '',
+                      'target_pch_out_db': None
+                      }
+
+
+def read_header(my_sheet, line, slice_):
+    """ return the list of headers !:= ''
+    header_i = [(header, header_column_index), ...]
+    in a {line, slice1_x, slice_y} range
+    """
+    Param_header = namedtuple('Param_header', 'header colindex')
+    try:
+        header = [x.value.strip() for x in my_sheet.row_slice(line, slice_[0], slice_[1])]
+        header_i = [Param_header(header, i + slice_[0]) for i, header in enumerate(header) if header != '']
+    except Exception:
+        header_i = []
+    if header_i != [] and header_i[-1].colindex != slice_[1]:
+        header_i.append(Param_header('', slice_[1]))
+    return header_i
+
+
+def read_slice(my_sheet, line, slice_, header):
+    """return the slice range of a given header
+    in a defined range {line, slice_x, slice_y}"""
+    header_i = read_header(my_sheet, line, slice_)
+    slice_range = (-1, -1)
+    if header_i != []:
+        try:
+            slice_range = next((h.colindex, header_i[i + 1].colindex)
+                               for i, h in enumerate(header_i) if header in h.header)
+        except Exception:
+            pass
+    return slice_range
+
+
+def parse_headers(my_sheet, input_headers_dict, headers, start_line, slice_in):
+    """return a dict of header_slice
+    key = column index
+    value = header name"""
+
+    for h0 in input_headers_dict:
+        slice_out = read_slice(my_sheet, start_line, slice_in, h0)
+        iteration = 1
+        while slice_out == (-1, -1) and iteration < 10:
+            # try next lines
+            slice_out = read_slice(my_sheet, start_line + iteration, slice_in, h0)
+            iteration += 1
+        if slice_out == (-1, -1):
+            if h0 in ('east', 'Node A', 'Node Z', 'City'):
+                print(f'{ansi_escapes.red}CRITICAL{ansi_escapes.reset}: missing _{h0}_ header: EXECUTION ENDS')
+                raise NetworkTopologyError(f'Missing _{h0}_ header')
+            else:
+                print(f'missing header {h0}')
+        elif not isinstance(input_headers_dict[h0], dict):
+            headers[slice_out[0]] = input_headers_dict[h0]
+        else:
+            headers = parse_headers(my_sheet, input_headers_dict[h0], headers, start_line + 1, slice_out)
+    if headers == {}:
+        print(f'{ansi_escapes.red}CRITICAL ERROR{ansi_escapes.reset}: could not find any header to read _ ABORT')
+        raise NetworkTopologyError('Could not find any header to read')
+    return headers
+
+
+def parse_row(row, headers):
+    return {f: r.value for f, r in
+            zip([label for label in headers.values()], [row[i] for i in headers])}
+
+
+def parse_sheet(my_sheet, input_headers_dict, header_line, start_line, column):
+    headers = parse_headers(my_sheet, input_headers_dict, {}, header_line, (0, column))
+    for row in all_rows(my_sheet, start=start_line):
+        yield parse_row(row[0: column], headers)
+
+
+def _format_items(items):
+    return '\n'.join(f' - {item}' for item in items)
+
+
+def sanity_check(nodes, links, nodes_by_city, links_by_city, eqpts_by_city):
+
+    duplicate_links = []
+    for l1 in links:
+        for l2 in links:
+            if l1 is not l2 and l1 == l2 and l2 not in duplicate_links:
+                print(f'\nWARNING\n \
+                    link {l1.from_city}-{l1.to_city} is duplicate \
+                    \nthe 1st duplicate link will be removed but you should check Links sheet input')
+                duplicate_links.append(l1)
+    for l in duplicate_links:
+        links.remove(l)
+        links_by_city[l.from_city].remove(l)
+        links_by_city[l.to_city].remove(l)
+
+    unreferenced_nodes = [n for n in nodes_by_city if n not in links_by_city]
+    if unreferenced_nodes:
+        raise NetworkTopologyError(f'{ansi_escapes.red}XLS error:{ansi_escapes.reset} The following nodes are not '
+                                   f'referenced from the {ansi_escapes.cyan}Links{ansi_escapes.reset} sheet. '
+                                   f'If unused, remove them from the {ansi_escapes.cyan}Nodes{ansi_escapes.reset} '
+                                   f'sheet:\n'
+                                   + _format_items(unreferenced_nodes))
+    # no need to check "Links" for invalid nodes because that's already in parse_excel()
+    wrong_eqpt_from = [n for n in eqpts_by_city if n not in nodes_by_city]
+    wrong_eqpt_to = [n.to_city for destinations in eqpts_by_city.values()
+                     for n in destinations if n.to_city not in nodes_by_city]
+    wrong_eqpt = wrong_eqpt_from + wrong_eqpt_to
+    if wrong_eqpt:
+        raise NetworkTopologyError(f'{ansi_escapes.red}XLS error:{ansi_escapes.reset} '
+                                   f'The {ansi_escapes.cyan}Eqpt{ansi_escapes.reset} sheet refers to nodes that '
+                                   f'are not defined in the {ansi_escapes.cyan}Nodes{ansi_escapes.reset} sheet:\n'
+                                   + _format_items(wrong_eqpt))
+
+    for city, link in links_by_city.items():
+        if nodes_by_city[city].node_type.lower() == 'ila' and len(link) != 2:
+            # wrong input: ILA sites can only be Degree 2
+            # => correct to make it a ROADM and remove entry in links_by_city
+            # TODO: put in log rather than print
+            print(f'invalid node type ({nodes_by_city[city].node_type})\
+                  specified in {city}, replaced by ROADM')
+            nodes_by_city[city].node_type = 'ROADM'
+            for n in nodes:
+                if n.city == city:
+                    n.node_type = 'ROADM'
+    return nodes, links
+
+
+def create_roadm_element(node, roadms_by_city):
+    """ create the json element for a roadm node, including the different cases:
+    - if there are restrictions
+    - if there are per degree target power defined on a direction
+    direction is defined by the booster name, so that booster must also be created in eqpt sheet
+    if the direction is defined in roadm
+    """
+    roadm = {'uid': f'roadm {node.city}'}
+    if node.preamp_restriction != '' or node.booster_restriction != '':
+        roadm['params'] = {
+            'restrictions': {
+               'preamp_variety_list': silent_remove(node.preamp_restriction.split(' | '), ''),
+               'booster_variety_list': silent_remove(node.booster_restriction.split(' | '), '')}
+                          }
+    if node.city in roadms_by_city.keys():
+        if 'params' not in roadm.keys():
+            roadm['params'] = {}
+        roadm['params']['per_degree_pch_out_db'] = {}
+        for elem in roadms_by_city[node.city]:
+            to_node = f'east edfa in {node.city} to {elem.to_node}'
+            if elem.target_pch_out_db is not None:
+                roadm['params']['per_degree_pch_out_db'][to_node] = elem.target_pch_out_db
+    roadm['metadata'] = {'location': {'city':      node.city,
+                                      'region':    node.region,
+                                      'latitude':  node.latitude,
+                                      'longitude': node.longitude}}
+    roadm['type'] = 'Roadm'
+    return roadm
+
+
+def create_east_eqpt_element(node):
+    """ create amplifiers json elements for the east direction.
+    this includes the case where the case of a fused element defined instead of an
+    ILA in eqpt sheet
+    """
+    eqpt = {'uid': f'east edfa in {node.from_city} to {node.to_city}',
+            'metadata': {'location': {'city':      nodes_by_city[node.from_city].city,
+                                      'region':    nodes_by_city[node.from_city].region,
+                                      'latitude':  nodes_by_city[node.from_city].latitude,
+                                      'longitude': nodes_by_city[node.from_city].longitude}}}
+    if node.east_amp_type.lower() != '' and node.east_amp_type.lower() != 'fused':
+        eqpt['type'] = 'Edfa'
+        eqpt['type_variety'] = f'{node.east_amp_type}'
+        eqpt['operational'] = {'gain_target': node.east_amp_gain,
+                               'delta_p':     node.east_amp_dp,
+                               'tilt_target': node.east_tilt,
+                               'out_voa':     node.east_att_out}
+    elif node.east_amp_type.lower() == '':
+        eqpt['type'] = 'Edfa'
+        eqpt['operational'] = {'gain_target': node.east_amp_gain,
+                               'delta_p':     node.east_amp_dp,
+                               'tilt_target': node.east_tilt,
+                               'out_voa':     node.east_att_out}
+    elif node.east_amp_type.lower() == 'fused':
+        # fused edfa variety is a hack to indicate that there should not be
+        # booster amplifier out the roadm.
+        # If user specifies ILA in Nodes sheet and fused in Eqpt sheet, then assumes that
+        # this is a fused nodes.
+        eqpt['type'] = 'Fused'
+        eqpt['params'] = {'loss': 0}
+    return eqpt
+
+
+def create_west_eqpt_element(node):
+    """ create amplifiers json elements for the west direction.
+    this includes the case where the case of a fused element defined instead of an
+    ILA in eqpt sheet
+    """
+    eqpt = {'uid': f'west edfa in {node.from_city} to {node.to_city}',
+            'metadata': {'location': {'city':      nodes_by_city[node.from_city].city,
+                                      'region':    nodes_by_city[node.from_city].region,
+                                      'latitude':  nodes_by_city[node.from_city].latitude,
+                                      'longitude': nodes_by_city[node.from_city].longitude}},
+            'type': 'Edfa'}
+    if node.west_amp_type.lower() != '' and node.west_amp_type.lower() != 'fused':
+        eqpt['type_variety'] = f'{node.west_amp_type}'
+        eqpt['operational'] = {'gain_target': node.west_amp_gain,
+                               'delta_p':     node.west_amp_dp,
+                               'tilt_target': node.west_tilt,
+                               'out_voa':     node.west_att_out}
+    elif node.west_amp_type.lower() == '':
+        eqpt['operational'] = {'gain_target': node.west_amp_gain,
+                               'delta_p':     node.west_amp_dp,
+                               'tilt_target': node.west_tilt,
+                               'out_voa':     node.west_att_out}
+    elif node.west_amp_type.lower() == 'fused':
+        eqpt['type'] = 'Fused'
+        eqpt['params'] = {'loss': 0}
+    return eqpt
+
+def xls_to_json_data(input_filename, filter_region=[]):
+    nodes, links, eqpts, roadms = parse_excel(input_filename)
+    if filter_region:
+        nodes = [n for n in nodes if n.region.lower() in filter_region]
+        cities = {n.city for n in nodes}
+        links = [lnk for lnk in links if lnk.from_city in cities and
+                 lnk.to_city in cities]
+        cities = {lnk.from_city for lnk in links} | {lnk.to_city for lnk in links}
+        nodes = [n for n in nodes if n.city in cities]
+
+    global nodes_by_city
+    nodes_by_city = {n.city: n for n in nodes}
+
+    global links_by_city
+    links_by_city = defaultdict(list)
+    for link in links:
+        links_by_city[link.from_city].append(link)
+        links_by_city[link.to_city].append(link)
+
+    global eqpts_by_city
+    eqpts_by_city = defaultdict(list)
+    for eqpt in eqpts:
+        eqpts_by_city[eqpt.from_city].append(eqpt)
+
+    roadms_by_city = defaultdict(list)
+    for roadm in roadms:
+        roadms_by_city[roadm.from_node].append(roadm)
+
+    nodes, links = sanity_check(nodes, links, nodes_by_city, links_by_city, eqpts_by_city)
+
+    return {
+        'elements':
+            [{'uid': f'trx {x.city}',
+              'metadata': {'location': {'city': x.city,
+                                        'region': x.region,
+                                        'latitude': x.latitude,
+                                        'longitude': x.longitude}},
+              'type': 'Transceiver'}
+             for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'] +
+            [create_roadm_element(x, roadms_by_city)
+             for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'] +
+            [{'uid': f'west fused spans in {x.city}',
+              'metadata': {'location': {'city': x.city,
+                                        'region': x.region,
+                                        'latitude': x.latitude,
+                                        'longitude': x.longitude}},
+              'type': 'Fused'}
+             for x in nodes_by_city.values() if x.node_type.lower() == 'fused'] +
+            [{'uid': f'east fused spans in {x.city}',
+              'metadata': {'location': {'city': x.city,
+                                        'region': x.region,
+                                        'latitude': x.latitude,
+                                        'longitude': x.longitude}},
+              'type': 'Fused'}
+             for x in nodes_by_city.values() if x.node_type.lower() == 'fused'] +
+            [{'uid': f'fiber ({x.from_city} \u2192 {x.to_city})-{x.east_cable}',
+              'metadata': {'location': midpoint(nodes_by_city[x.from_city],
+                                                nodes_by_city[x.to_city])},
+              'type': 'Fiber',
+              'type_variety': x.east_fiber,
+              'params': {'length': round(x.east_distance, 3),
+                         'length_units': x.distance_units,
+                         'loss_coef': x.east_lineic,
+                         'con_in': x.east_con_in,
+                         'con_out': x.east_con_out}
+              }
+             for x in links] +
+            [{'uid': f'fiber ({x.to_city} \u2192 {x.from_city})-{x.west_cable}',
+              'metadata': {'location': midpoint(nodes_by_city[x.from_city],
+                                                nodes_by_city[x.to_city])},
+              'type': 'Fiber',
+              'type_variety': x.west_fiber,
+              'params': {'length': round(x.west_distance, 3),
+                         'length_units': x.distance_units,
+                         'loss_coef': x.west_lineic,
+                         'con_in': x.west_con_in,
+                         'con_out': x.west_con_out}
+              } for x in links] +
+            [{'uid': f'west edfa in {x.city}',
+              'metadata': {'location': {'city': x.city,
+                                        'region': x.region,
+                                        'latitude': x.latitude,
+                                        'longitude': x.longitude}},
+              'type': 'Edfa',
+              'operational': {'gain_target': None,
+                              'tilt_target': 0}
+              } for x in nodes_by_city.values() if x.node_type.lower() == 'ila' and x.city not in eqpts_by_city] +
+            [{'uid': f'east edfa in {x.city}',
+              'metadata': {'location': {'city': x.city,
+                                        'region': x.region,
+                                        'latitude': x.latitude,
+                                        'longitude': x.longitude}},
+              'type': 'Edfa',
+              'operational': {'gain_target': None,
+                              'tilt_target': 0}
+              } for x in nodes_by_city.values() if x.node_type.lower() == 'ila' and x.city not in eqpts_by_city] +
+            [create_east_eqpt_element(e) for e in eqpts] +
+            [create_west_eqpt_element(e) for e in eqpts],
+        'connections':
+            list(chain.from_iterable([eqpt_connection_by_city(n.city)
+                                      for n in nodes]))
+            +
+            list(chain.from_iterable(zip(
+                [{'from_node': f'trx {x.city}',
+                  'to_node': f'roadm {x.city}'}
+                 for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'],
+                [{'from_node': f'roadm {x.city}',
+                  'to_node': f'trx {x.city}'}
+                 for x in nodes_by_city.values() if x.node_type.lower() == 'roadm'])))
+    }
+
+
+def convert_file(input_filename, filter_region=[], output_json_file_name=None):
+    data = xls_to_json_data(input_filename, filter_region)
+    if output_json_file_name is None:
+        output_json_file_name = input_filename.with_suffix('.json')
+    with open(output_json_file_name, 'w', encoding='utf-8') as edfa_json_file:
+        edfa_json_file.write(dumps(data, indent=2, ensure_ascii=False))
+        edfa_json_file.write('\n')   # add end of file newline because json dumps does not.
+    return output_json_file_name
+
+
+def corresp_names(input_filename, network):
+    """ a function that builds the correspondance between names given in the excel,
+        and names used in the json, and created by the autodesign.
+        All names are listed
+    """
+    nodes, links, eqpts, roadms = parse_excel(input_filename)
+    fused = [n.uid for n in network.nodes() if isinstance(n, Fused)]
+    ila = [n.uid for n in network.nodes() if isinstance(n, Edfa)]
+
+    corresp_roadm = {x.city: [f'roadm {x.city}'] for x in nodes
+                     if x.node_type.lower() == 'roadm'}
+    corresp_fused = {x.city: [f'west fused spans in {x.city}', f'east fused spans in {x.city}']
+                     for x in nodes if x.node_type.lower() == 'fused' and
+                     f'west fused spans in {x.city}' in fused and
+                     f'east fused spans in {x.city}' in fused}
+
+    # add the special cases when an ila is changed into a fused
+    for my_e in eqpts:
+        name = f'east edfa in {my_e.from_city} to {my_e.to_city}'
+        if my_e.east_amp_type.lower() == 'fused' and name in fused:
+            if my_e.from_city in corresp_fused.keys():
+                corresp_fused[my_e.from_city].append(name)
+            else:
+                corresp_fused[my_e.from_city] = [name]
+        name = f'west edfa in {my_e.from_city} to {my_e.to_city}'
+        if my_e.west_amp_type.lower() == 'fused' and name in fused:
+            if my_e.from_city in corresp_fused.keys():
+                corresp_fused[my_e.from_city].append(name)
+            else:
+                corresp_fused[my_e.from_city] = [name]
+    # build corresp ila based on eqpt sheet
+    # start with east direction
+    corresp_ila = {e.from_city: [f'east edfa in {e.from_city} to {e.to_city}']
+                   for e in eqpts if f'east edfa in {e.from_city} to {e.to_city}' in ila}
+    # west direction, append name or create a new item in dict
+    for my_e in eqpts:
+        name = f'west edfa in {my_e.from_city} to {my_e.to_city}'
+        if name in ila:
+            if my_e.from_city in corresp_ila.keys():
+                corresp_ila[my_e.from_city].append(name)
+            else:
+                corresp_ila[my_e.from_city] = [name]
+    # complete with potential autodesign names: amplifiers
+    for my_l in links:
+        name = f'Edfa0_fiber ({my_l.to_city} \u2192 {my_l.from_city})-{my_l.west_cable}'
+        if name in ila:
+            if my_l.from_city in corresp_ila.keys():
+                # "east edfa in Stbrieuc to Rennes_STA"  is equivalent name as
+                # "Edfa0_fiber (Lannion_CAS → Stbrieuc)-F056"
+                # "west edfa in Stbrieuc to Rennes_STA"  is equivalent name as
+                # "Edfa0_fiber (Rennes_STA → Stbrieuc)-F057"
+                # does not filter names: all types (except boosters) are created.
+                # in case fibers are splitted the name here is a prefix
+                corresp_ila[my_l.from_city].append(name)
+            else:
+                corresp_ila[my_l.from_city] = [name]
+        name = f'Edfa0_fiber ({my_l.from_city} \u2192 {my_l.to_city})-{my_l.east_cable}'
+        if name in ila:
+            if my_l.to_city in corresp_ila.keys():
+                corresp_ila[my_l.to_city].append(name)
+            else:
+                corresp_ila[my_l.to_city] = [name]
+    # merge fused with ila:
+    for key, val in corresp_fused.items():
+        if key in corresp_ila.keys():
+            corresp_ila[key].extend(val)
+        else:
+            corresp_ila[key] = val
+        # no need of roadm booster
+    return corresp_roadm, corresp_fused, corresp_ila
+
+
+def parse_excel(input_filename):
+    link_headers = {
+        'Node A': 'from_city',
+        'Node Z': 'to_city',
+        'east': {
+            'Distance (km)': 'east_distance',
+            'Fiber type': 'east_fiber',
+            'lineic att': 'east_lineic',
+            'Con_in': 'east_con_in',
+            'Con_out': 'east_con_out',
+            'PMD': 'east_pmd',
+            'Cable id': 'east_cable'
+        },
+        'west': {
+            'Distance (km)': 'west_distance',
+            'Fiber type': 'west_fiber',
+            'lineic att': 'west_lineic',
+            'Con_in': 'west_con_in',
+            'Con_out': 'west_con_out',
+            'PMD': 'west_pmd',
+            'Cable id': 'west_cable'
+        }
+    }
+    node_headers = {
+        'City': 'city',
+        'State': 'state',
+        'Country': 'country',
+        'Region': 'region',
+        'Latitude': 'latitude',
+        'Longitude': 'longitude',
+        'Type': 'node_type',
+        'Booster_restriction': 'booster_restriction',
+        'Preamp_restriction': 'preamp_restriction'
+    }
+    eqpt_headers = {
+        'Node A': 'from_city',
+        'Node Z': 'to_city',
+        'east': {
+            'amp type': 'east_amp_type',
+            'att_in': 'east_att_in',
+            'amp gain': 'east_amp_gain',
+            'delta p': 'east_amp_dp',
+            'tilt': 'east_tilt',
+            'att_out': 'east_att_out'
+        },
+        'west': {
+            'amp type': 'west_amp_type',
+            'att_in': 'west_att_in',
+            'amp gain': 'west_amp_gain',
+            'delta p': 'west_amp_dp',
+            'tilt': 'west_tilt',
+            'att_out': 'west_att_out'
+        }
+    }
+    roadm_headers = {'Node A': 'from_node',
+                     'Node Z': 'to_node',
+                     'per degree target power (dBm)': 'target_pch_out_db'
+                     }
+
+    with open_workbook(input_filename) as wb:
+        nodes_sheet = wb.sheet_by_name('Nodes')
+        links_sheet = wb.sheet_by_name('Links')
+        try:
+            eqpt_sheet = wb.sheet_by_name('Eqpt')
+        except Exception:
+            # eqpt_sheet is optional
+            eqpt_sheet = None
+        try:
+            roadm_sheet = wb.sheet_by_name('Roadms')
+        except Exception:
+            # roadm_sheet is optional
+            roadm_sheet = None
+
+        nodes = []
+        for node in parse_sheet(nodes_sheet, node_headers, NODES_LINE, NODES_LINE + 1, NODES_COLUMN):
+            nodes.append(Node(**node))
+        expected_node_types = {'ROADM', 'ILA', 'FUSED'}
+        for n in nodes:
+            if n.node_type not in expected_node_types:
+                n.node_type = 'ILA'
+
+        links = []
+        for link in parse_sheet(links_sheet, link_headers, LINKS_LINE, LINKS_LINE + 2, LINKS_COLUMN):
+            links.append(Link(**link))
+
+        eqpts = []
+        if eqpt_sheet is not None:
+            for eqpt in parse_sheet(eqpt_sheet, eqpt_headers, EQPTS_LINE, EQPTS_LINE + 2, EQPTS_COLUMN):
+                eqpts.append(Eqpt(**eqpt))
+
+        roadms = []
+        if roadm_sheet is not None:
+            for roadm in parse_sheet(roadm_sheet, roadm_headers, ROADMS_LINE, ROADMS_LINE+2, ROADMS_COLUMN):
+                roadms.append(Roadm(**roadm))
+
+    # sanity check
+    all_cities = Counter(n.city for n in nodes)
+    if len(all_cities) != len(nodes):
+        raise ValueError(f'Duplicate city: {all_cities}')
+    bad_links = []
+    for lnk in links:
+        if lnk.from_city not in all_cities or lnk.to_city not in all_cities:
+            bad_links.append([lnk.from_city, lnk.to_city])
+
+    if bad_links:
+        raise NetworkTopologyError(f'{ansi_escapes.red}XLS error:{ansi_escapes.reset} '
+                                   f'The {ansi_escapes.cyan}Links{ansi_escapes.reset} sheet references nodes that '
+                                   f'are not defined in the {ansi_escapes.cyan}Nodes{ansi_escapes.reset} sheet:\n'
+                                   + _format_items(f'{item[0]} -> {item[1]}' for item in bad_links))
+
+    return nodes, links, eqpts, roadms
+
+
+def eqpt_connection_by_city(city_name):
+    other_cities = fiber_dest_from_source(city_name)
+    subdata = []
+    if nodes_by_city[city_name].node_type.lower() in {'ila', 'fused'}:
+        # Then len(other_cities) == 2
+        direction = ['west', 'east']
+        for i in range(2):
+            from_ = fiber_link(other_cities[i], city_name)
+            in_ = eqpt_in_city_to_city(city_name, other_cities[0], direction[i])
+            to_ = fiber_link(city_name, other_cities[1 - i])
+            subdata += connect_eqpt(from_, in_, to_)
+    elif nodes_by_city[city_name].node_type.lower() == 'roadm':
+        for other_city in other_cities:
+            from_ = f'roadm {city_name}'
+            in_ = eqpt_in_city_to_city(city_name, other_city)
+            to_ = fiber_link(city_name, other_city)
+            subdata += connect_eqpt(from_, in_, to_)
+
+            from_ = fiber_link(other_city, city_name)
+            in_ = eqpt_in_city_to_city(city_name, other_city, "west")
+            to_ = f'roadm {city_name}'
+            subdata += connect_eqpt(from_, in_, to_)
+    return subdata
+
+
+def connect_eqpt(from_, in_, to_):
+    connections = []
+    if in_ != '':
+        connections = [{'from_node': from_, 'to_node': in_},
+                       {'from_node': in_, 'to_node': to_}]
+    else:
+        connections = [{'from_node': from_, 'to_node': to_}]
+    return connections
+
+
+def eqpt_in_city_to_city(in_city, to_city, direction='east'):
+    rev_direction = 'west' if direction == 'east' else 'east'
+    return_eqpt = ''
+    if in_city in eqpts_by_city:
+        for e in eqpts_by_city[in_city]:
+            if nodes_by_city[in_city].node_type.lower() == 'roadm':
+                if e.to_city == to_city:
+                    return_eqpt = f'{direction} edfa in {e.from_city} to {e.to_city}'
+            elif nodes_by_city[in_city].node_type.lower() == 'ila':
+                if e.to_city != to_city:
+                    direction = rev_direction
+                return_eqpt = f'{direction} edfa in {e.from_city} to {e.to_city}'
+    elif nodes_by_city[in_city].node_type.lower() == 'ila':
+        return_eqpt = f'{direction} edfa in {in_city}'
+    if nodes_by_city[in_city].node_type.lower() == 'fused':
+        return_eqpt = f'{direction} fused spans in {in_city}'
+    return return_eqpt
+
+
+def corresp_next_node(network, corresp_ila, corresp_roadm):
+    """ for each name in corresp dictionnaries find the next node in network and its name
+        given by user in excel. for meshTopology_exampleV2.xls:
+        user ILA name Stbrieuc covers the two direction. convert.py creates 2 different ILA
+        with possible names (depending on the direction and if the eqpt was defined in eqpt
+        sheet)
+        - east edfa in Stbrieuc to Rennes_STA
+        - west edfa in Stbrieuc to Rennes_STA
+        - Edfa0_fiber (Lannion_CAS → Stbrieuc)-F056
+        - Edfa0_fiber (Rennes_STA → Stbrieuc)-F057
+        next_nodes finds the user defined name of next node to be able to map the path constraints
+        - east edfa in Stbrieuc to Rennes_STA      next node = Rennes_STA
+        - west edfa in Stbrieuc to Rennes_STA      next node Lannion_CAS
+
+        Edfa0_fiber (Lannion_CAS → Stbrieuc)-F056 and Edfa0_fiber (Rennes_STA → Stbrieuc)-F057
+        do not exist
+        the function supports fiber splitting, fused nodes and shall only be called if
+        excel format is used for both network and service
+    """
+    next_node = {}
+    # consolidate tables and create next_node table
+    for ila_key, ila_list in corresp_ila.items():
+        temp = copy(ila_list)
+        for ila_elem in ila_list:
+            # find the node with ila_elem string _in_ the node uid. 'in' is used instead of
+            # '==' to find composed nodes due to fiber splitting in autodesign.
+            # eg if elem_ila is 'Edfa0_fiber (Lannion_CAS → Stbrieuc)-F056',
+            # node uid 'Edfa0_fiber (Lannion_CAS → Stbrieuc)-F056_(1/2)' is possible
+            correct_ila_name = next(n.uid for n in network.nodes() if ila_elem in n.uid)
+            temp.remove(ila_elem)
+            temp.append(correct_ila_name)
+            ila_nd = next(n for n in network.nodes() if ila_elem in n.uid)
+            next_nd = next(network.successors(ila_nd))
+            # search for the next ILA or ROADM
+            while isinstance(next_nd, (Fiber, Fused)):
+                next_nd = next(network.successors(next_nd))
+            # if next_nd is a ROADM, add the first found correspondance
+            for key, val in corresp_roadm.items():
+                # val is a list of possible names associated with key
+                if next_nd.uid in val:
+                    next_node[correct_ila_name] = key
+                    break
+            # if next_nd was not already added in the dict with the previous loop,
+            # add the first found correspondance in ila names
+            if correct_ila_name not in next_node.keys():
+                for key, val in corresp_ila.items():
+                    # in case of splitted fibers the ila name might not be exact match
+                    if [e for e in val if e in next_nd.uid]:
+                        next_node[correct_ila_name] = key
+                        break
+
+        corresp_ila[ila_key] = temp
+    return corresp_ila, next_node
+
+
+def fiber_dest_from_source(city_name):
+    destinations = []
+    links_from_city = links_by_city[city_name]
+    for l in links_from_city:
+        if l.from_city == city_name:
+            destinations.append(l.to_city)
+        else:
+            destinations.append(l.from_city)
+    return destinations
+
+
+def fiber_link(from_city, to_city):
+    source_dest = (from_city, to_city)
+    links = links_by_city[from_city]
+    link = next(l for l in links if l.from_city in source_dest and l.to_city in source_dest)
+    if link.from_city == from_city:
+        fiber = f'fiber ({link.from_city} \u2192 {link.to_city})-{link.east_cable}'
+    else:
+        fiber = f'fiber ({link.to_city} \u2192 {link.from_city})-{link.west_cable}'
+    return fiber
+
+
+def midpoint(city_a, city_b):
+    lats = city_a.latitude, city_b.latitude
+    longs = city_a.longitude, city_b.longitude
+    try:
+        result = {
+            'latitude': sum(lats) / 2,
+            'longitude': sum(longs) / 2
+        }
+    except TypeError:
+        result = {
+            'latitude': 0,
+            'longitude': 0
+        }
+    return result
+
+# TODO get column size automatically from tupple size
+
+
+NODES_COLUMN = 10
+NODES_LINE = 4
+LINKS_COLUMN = 16
+LINKS_LINE = 3
+EQPTS_LINE = 3
+EQPTS_COLUMN = 14
+ROADMS_LINE = 3
+ROADMS_COLUMN = 3
+
+
+def _do_convert():
+    parser = ArgumentParser()
+    parser.add_argument('workbook', type=Path)
+    parser.add_argument('-f', '--filter-region', action='append', default=[])
+    parser.add_argument('--output', type=Path, help='Name of the generated JSON file')
+    args = parser.parse_args()
+    res = convert_file(args.workbook, args.filter_region, args.output)
+    print(f'XLS -> JSON saved to {res}')
+
+
+if __name__ == '__main__':
+    _do_convert()

gnpy/tools/json_io.py

@@ -0,0 +1,540 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.tools.json_io
+==================
+
+Loading and saving data from JSON files in GNPy's internal data format
+'''
+
+from networkx import DiGraph
+from logging import getLogger
+from pathlib import Path
+import json
+from collections import namedtuple
+from gnpy.core import ansi_escapes, elements
+from gnpy.core.equipment import trx_mode_params
+from gnpy.core.exceptions import ConfigurationError, EquipmentConfigError, NetworkTopologyError, ServiceError
+from gnpy.core.science_utils import estimate_nf_model
+from gnpy.core.utils import automatic_nch, automatic_fmax, merge_amplifier_restrictions
+from gnpy.topology.request import PathRequest, Disjunction
+from gnpy.tools.convert import xls_to_json_data
+from gnpy.tools.service_sheet import read_service_sheet
+
+
+_logger = getLogger(__name__)
+
+
+Model_vg = namedtuple('Model_vg', 'nf1 nf2 delta_p orig_nf_min orig_nf_max')
+Model_fg = namedtuple('Model_fg', 'nf0')
+Model_openroadm_ila = namedtuple('Model_openroadm_ila', 'nf_coef')
+Model_hybrid = namedtuple('Model_hybrid', 'nf_ram gain_ram edfa_variety')
+Model_dual_stage = namedtuple('Model_dual_stage', 'preamp_variety booster_variety')
+
+
+class _JsonThing:
+    def update_attr(self, default_values, kwargs, name):
+        clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
+        for k, v in default_values.items():
+            setattr(self, k, clean_kwargs.get(k, v))
+            if k not in clean_kwargs and name != 'Amp':
+                print(ansi_escapes.red +
+                      f'\n WARNING missing {k} attribute in eqpt_config.json[{name}]' +
+                      f'\n default value is {k} = {v}' +
+                      ansi_escapes.reset)
+
+
+class SI(_JsonThing):
+    default_values = {
+        "f_min": 191.35e12,
+        "f_max": 196.1e12,
+        "baud_rate": 32e9,
+        "spacing": 50e9,
+        "power_dbm": 0,
+        "power_range_db": [0, 0, 0.5],
+        "roll_off": 0.15,
+        "tx_osnr": 45,
+        "sys_margins": 0
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'SI')
+
+
+class Span(_JsonThing):
+    default_values = {
+        'power_mode': True,
+        'delta_power_range_db': None,
+        'max_fiber_lineic_loss_for_raman': 0.25,
+        'target_extended_gain': 2.5,
+        'max_length': 150,
+        'length_units': 'km',
+        'max_loss': None,
+        'padding': 10,
+        'EOL': 0,
+        'con_in': 0,
+        'con_out': 0
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'Span')
+
+
+class Roadm(_JsonThing):
+    default_values = {
+        'target_pch_out_db': -17,
+        'add_drop_osnr': 100,
+        'pmd': 0,
+        'restrictions': {
+            'preamp_variety_list': [],
+            'booster_variety_list': []
+        }
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'Roadm')
+
+
+class Transceiver(_JsonThing):
+    default_values = {
+        'type_variety': None,
+        'frequency': None,
+        'mode': {}
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'Transceiver')
+
+
+class Fiber(_JsonThing):
+    default_values = {
+        'type_variety': '',
+        'dispersion': None,
+        'gamma': 0,
+        'pmd_coef': 0
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'Fiber')
+
+
+class RamanFiber(_JsonThing):
+    default_values = {
+        'type_variety': '',
+        'dispersion': None,
+        'gamma': 0,
+        'pmd_coef': 0,
+        'raman_efficiency': None
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'RamanFiber')
+        for param in ('cr', 'frequency_offset'):
+            if param not in self.raman_efficiency:
+                raise EquipmentConfigError(f'RamanFiber.raman_efficiency: missing "{param}" parameter')
+        if self.raman_efficiency['frequency_offset'] != sorted(self.raman_efficiency['frequency_offset']):
+            raise EquipmentConfigError(f'RamanFiber.raman_efficiency.frequency_offset is not sorted')
+
+
+class Amp(_JsonThing):
+    default_values = {
+        'f_min': 191.35e12,
+        'f_max': 196.1e12,
+        'type_variety': '',
+        'type_def': '',
+        'gain_flatmax': None,
+        'gain_min': None,
+        'p_max': None,
+        'nf_model': None,
+        'dual_stage_model': None,
+        'nf_fit_coeff': None,
+        'nf_ripple': None,
+        'dgt': None,
+        'gain_ripple': None,
+        'out_voa_auto': False,
+        'allowed_for_design': False,
+        'raman': False
+    }
+
+    def __init__(self, **kwargs):
+        self.update_attr(self.default_values, kwargs, 'Amp')
+
+    @classmethod
+    def from_json(cls, filename, **kwargs):
+        config = Path(filename).parent / 'default_edfa_config.json'
+
+        type_variety = kwargs['type_variety']
+        type_def = kwargs.get('type_def', 'variable_gain')  # default compatibility with older json eqpt files
+        nf_def = None
+        dual_stage_def = None
+
+        if type_def == 'fixed_gain':
+            try:
+                nf0 = kwargs.pop('nf0')
+            except KeyError:  # nf0 is expected for a fixed gain amp
+                raise EquipmentConfigError(f'missing nf0 value input for amplifier: {type_variety} in equipment config')
+            for k in ('nf_min', 'nf_max'):
+                try:
+                    del kwargs[k]
+                except KeyError:
+                    pass
+            nf_def = Model_fg(nf0)
+        elif type_def == 'advanced_model':
+            config = Path(filename).parent / kwargs.pop('advanced_config_from_json')
+        elif type_def == 'variable_gain':
+            gain_min, gain_max = kwargs['gain_min'], kwargs['gain_flatmax']
+            try:  # nf_min and nf_max are expected for a variable gain amp
+                nf_min = kwargs.pop('nf_min')
+                nf_max = kwargs.pop('nf_max')
+            except KeyError:
+                raise EquipmentConfigError(f'missing nf_min or nf_max value input for amplifier: {type_variety} in equipment config')
+            try:  # remove all remaining nf inputs
+                del kwargs['nf0']
+            except KeyError:
+                pass  # nf0 is not needed for variable gain amp
+            nf1, nf2, delta_p = estimate_nf_model(type_variety, gain_min, gain_max, nf_min, nf_max)
+            nf_def = Model_vg(nf1, nf2, delta_p, nf_min, nf_max)
+        elif type_def == 'openroadm':
+            try:
+                nf_coef = kwargs.pop('nf_coef')
+            except KeyError:  # nf_coef is expected for openroadm amp
+                raise EquipmentConfigError(f'missing nf_coef input for amplifier: {type_variety} in equipment config')
+            nf_def = Model_openroadm_ila(nf_coef)
+        elif type_def in ('openroadm_preamp', 'openroadm_booster'):
+            pass  # no extra parameters needed
+        elif type_def == 'dual_stage':
+            try:  # nf_ram and gain_ram are expected for a hybrid amp
+                preamp_variety = kwargs.pop('preamp_variety')
+                booster_variety = kwargs.pop('booster_variety')
+            except KeyError:
+                raise EquipmentConfigError(f'missing preamp/booster variety input for amplifier: {type_variety} in equipment config')
+            dual_stage_def = Model_dual_stage(preamp_variety, booster_variety)
+        else:
+            raise EquipmentConfigError(f'Edfa type_def {type_def} does not exist')
+
+        json_data = load_json(config)
+
+        return cls(**{**kwargs, **json_data,
+                      'nf_model': nf_def, 'dual_stage_model': dual_stage_def})
+
+
+def _automatic_spacing(baud_rate):
+    """return the min possible channel spacing for a given baud rate"""
+    # TODO : this should parametrized in a cfg file
+    # list of possible tuples [(max_baud_rate, spacing_for_this_baud_rate)]
+    spacing_list = [(33e9, 37.5e9), (38e9, 50e9), (50e9, 62.5e9), (67e9, 75e9), (92e9, 100e9)]
+    return min((s[1] for s in spacing_list if s[0] > baud_rate), default=baud_rate * 1.2)
+
+
+def load_equipment(filename):
+    json_data = load_json(filename)
+    return _equipment_from_json(json_data, filename)
+
+
+def _update_dual_stage(equipment):
+    edfa_dict = equipment['Edfa']
+    for edfa in edfa_dict.values():
+        if edfa.type_def == 'dual_stage':
+            edfa_preamp = edfa_dict[edfa.dual_stage_model.preamp_variety]
+            edfa_booster = edfa_dict[edfa.dual_stage_model.booster_variety]
+            for key, value in edfa_preamp.__dict__.items():
+                attr_k = 'preamp_' + key
+                setattr(edfa, attr_k, value)
+            for key, value in edfa_booster.__dict__.items():
+                attr_k = 'booster_' + key
+                setattr(edfa, attr_k, value)
+            edfa.p_max = edfa_booster.p_max
+            edfa.gain_flatmax = edfa_booster.gain_flatmax + edfa_preamp.gain_flatmax
+            if edfa.gain_min < edfa_preamp.gain_min:
+                raise EquipmentConfigError(f'Dual stage {edfa.type_variety} minimal gain is lower than its preamp minimal gain')
+    return equipment
+
+
+def _roadm_restrictions_sanity_check(equipment):
+    """ verifies that booster and preamp restrictions specified in roadm equipment are listed
+    in the edfa.
+    """
+    restrictions = equipment['Roadm']['default'].restrictions['booster_variety_list'] + \
+        equipment['Roadm']['default'].restrictions['preamp_variety_list']
+    for amp_name in restrictions:
+        if amp_name not in equipment['Edfa']:
+            raise EquipmentConfigError(f'ROADM restriction {amp_name} does not refer to a defined EDFA name')
+
+
+def _check_fiber_vs_raman_fiber(equipment):
+    """Ensure that Fiber and RamanFiber with the same name define common properties equally"""
+    if 'RamanFiber' not in equipment:
+        return
+    for fiber_type in set(equipment['Fiber'].keys()) & set(equipment['RamanFiber'].keys()):
+        for attr in ('dispersion', 'dispersion-slope', 'gamma', 'pmd-coefficient'):
+            fiber = equipment['Fiber'][fiber_type]
+            raman = equipment['RamanFiber'][fiber_type]
+            a = getattr(fiber, attr, None)
+            b = getattr(raman, attr, None)
+            if a != b:
+                raise EquipmentConfigError(f'WARNING: Fiber and RamanFiber definition of "{fiber_type}" '
+                                           f'disagrees for "{attr}": {a} != {b}')
+
+
+def _equipment_from_json(json_data, filename):
+    """build global dictionnary eqpt_library that stores all eqpt characteristics:
+    edfa type type_variety, fiber type_variety
+    from the eqpt_config.json (filename parameter)
+    also read advanced_config_from_json file parameters for edfa if they are available:
+    typically nf_ripple, dfg gain ripple, dgt and nf polynomial nf_fit_coeff
+    if advanced_config_from_json file parameter is not present: use nf_model:
+    requires nf_min and nf_max values boundaries of the edfa gain range
+    """
+    equipment = {}
+    for key, entries in json_data.items():
+        equipment[key] = {}
+        for entry in entries:
+            subkey = entry.get('type_variety', 'default')
+            if key == 'Edfa':
+                equipment[key][subkey] = Amp.from_json(filename, **entry)
+            elif key == 'Fiber':
+                equipment[key][subkey] = Fiber(**entry)
+            elif key == 'Span':
+                equipment[key][subkey] = Span(**entry)
+            elif key == 'Roadm':
+                equipment[key][subkey] = Roadm(**entry)
+            elif key == 'SI':
+                equipment[key][subkey] = SI(**entry)
+            elif key == 'Transceiver':
+                equipment[key][subkey] = Transceiver(**entry)
+            elif key == 'RamanFiber':
+                equipment[key][subkey] = RamanFiber(**entry)
+            else:
+                raise EquipmentConfigError(f'Unrecognized network element type "{key}"')
+    _check_fiber_vs_raman_fiber(equipment)
+    equipment = _update_dual_stage(equipment)
+    _roadm_restrictions_sanity_check(equipment)
+    return equipment
+
+
+def load_network(filename, equipment):
+    if filename.suffix.lower() in ('.xls', '.xlsx'):
+        json_data = xls_to_json_data(filename)
+    elif filename.suffix.lower() == '.json':
+        json_data = load_json(filename)
+    else:
+        raise ValueError(f'unsupported topology filename extension {filename.suffix.lower()}')
+    return network_from_json(json_data, equipment)
+
+
+def save_network(network: DiGraph, filename: str):
+    '''Dump the network into a JSON file
+
+    :param network: network to work on
+    :param filename: file to write to
+    '''
+    save_json(network_to_json(network), filename)
+
+
+def _cls_for(equipment_type):
+    if equipment_type == 'Edfa':
+        return elements.Edfa
+    if equipment_type == 'Fused':
+        return elements.Fused
+    elif equipment_type == 'Roadm':
+        return elements.Roadm
+    elif equipment_type == 'Transceiver':
+        return elements.Transceiver
+    elif equipment_type == 'Fiber':
+        return elements.Fiber
+    elif equipment_type == 'RamanFiber':
+        return elements.RamanFiber
+    else:
+        raise ConfigurationError(f'Unknown network equipment "{equipment_type}"')
+
+
+def network_from_json(json_data, equipment):
+    # NOTE|dutc: we could use the following, but it would tie our data format
+    #            too closely to the graph library
+    # from networkx import node_link_graph
+    g = DiGraph()
+    for el_config in json_data['elements']:
+        typ = el_config.pop('type')
+        variety = el_config.pop('type_variety', 'default')
+        cls = _cls_for(typ)
+        if typ == 'Fused':
+            # well, there's no variety for the 'Fused' node type
+            pass
+        elif variety in equipment[typ]:
+            extra_params = equipment[typ][variety]
+            temp = el_config.setdefault('params', {})
+            temp = merge_amplifier_restrictions(temp, extra_params.__dict__)
+            el_config['params'] = temp
+            el_config['type_variety'] = variety
+        elif (typ in ['Fiber', 'RamanFiber']) or (typ == 'Edfa' and variety not in ['default', '']):
+            raise ConfigurationError(f'The {typ} of variety type {variety} was not recognized:'
+                                     '\nplease check it is properly defined in the eqpt_config json file')
+        el = cls(**el_config)
+        g.add_node(el)
+
+    nodes = {k.uid: k for k in g.nodes()}
+
+    for cx in json_data['connections']:
+        from_node, to_node = cx['from_node'], cx['to_node']
+        try:
+            if isinstance(nodes[from_node], elements.Fiber):
+                edge_length = nodes[from_node].params.length
+            else:
+                edge_length = 0.01
+            g.add_edge(nodes[from_node], nodes[to_node], weight=edge_length)
+        except KeyError:
+            raise NetworkTopologyError(f'can not find {from_node} or {to_node} defined in {cx}')
+
+    return g
+
+
+def network_to_json(network):
+    data = {
+        'elements': [n.to_json for n in network]
+    }
+    connections = {
+        'connections': [{"from_node": n.uid,
+                         "to_node": next_n.uid}
+                        for n in network
+                        for next_n in network.successors(n) if next_n is not None]
+    }
+    data.update(connections)
+    return data
+
+
+def load_json(filename):
+    with open(filename, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    return data
+
+
+def save_json(obj, filename):
+    with open(filename, 'w', encoding='utf-8') as f:
+        json.dump(obj, f, indent=2, ensure_ascii=False)
+
+
+def load_requests(filename, eqpt, bidir, network, network_filename):
+    """ loads the requests from a json or an excel file into a data string
+    """
+    if filename.suffix.lower() in ('.xls', '.xlsx'):
+        _logger.info('Automatically converting requests from XLS to JSON')
+        try:
+            return convert_service_sheet(filename, eqpt, network, network_filename=network_filename, bidir=bidir)
+        except ServiceError as this_e:
+            print(f'{ansi_escapes.red}Service error:{ansi_escapes.reset} {this_e}')
+            exit(1)
+    else:
+        return load_json(filename)
+
+
+def requests_from_json(json_data, equipment):
+    """Extract list of requests from data parsed from JSON"""
+    requests_list = []
+
+    for req in json_data['path-request']:
+        # init all params from request
+        params = {}
+        params['request_id'] = req['request-id']
+        params['source'] = req['source']
+        params['bidir'] = req['bidirectional']
+        params['destination'] = req['destination']
+        params['trx_type'] = req['path-constraints']['te-bandwidth']['trx_type']
+        params['trx_mode'] = req['path-constraints']['te-bandwidth']['trx_mode']
+        params['format'] = params['trx_mode']
+        params['spacing'] = req['path-constraints']['te-bandwidth']['spacing']
+        try:
+            nd_list = req['explicit-route-objects']['route-object-include-exclude']
+        except KeyError:
+            nd_list = []
+        params['nodes_list'] = [n['num-unnum-hop']['node-id'] for n in nd_list]
+        params['loose_list'] = [n['num-unnum-hop']['hop-type'] for n in nd_list]
+        # recover trx physical param (baudrate, ...) from type and mode
+        # in trx_mode_params optical power is read from equipment['SI']['default'] and
+        # nb_channel is computed based on min max frequency and spacing
+        trx_params = trx_mode_params(equipment, params['trx_type'], params['trx_mode'], True)
+        params.update(trx_params)
+        # print(trx_params['min_spacing'])
+        # optical power might be set differently in the request. if it is indicated then the
+        # params['power'] is updated
+        try:
+            if req['path-constraints']['te-bandwidth']['output-power']:
+                params['power'] = req['path-constraints']['te-bandwidth']['output-power']
+        except KeyError:
+            pass
+        # same process for nb-channel
+        f_min = params['f_min']
+        f_max_from_si = params['f_max']
+        try:
+            if req['path-constraints']['te-bandwidth']['max-nb-of-channel'] is not None:
+                nch = req['path-constraints']['te-bandwidth']['max-nb-of-channel']
+                params['nb_channel'] = nch
+                spacing = params['spacing']
+                params['f_max'] = automatic_fmax(f_min, spacing, nch)
+            else:
+                params['nb_channel'] = automatic_nch(f_min, f_max_from_si, params['spacing'])
+        except KeyError:
+            params['nb_channel'] = automatic_nch(f_min, f_max_from_si, params['spacing'])
+        _check_one_request(params, f_max_from_si)
+
+        try:
+            params['path_bandwidth'] = req['path-constraints']['te-bandwidth']['path_bandwidth']
+        except KeyError:
+            pass
+        requests_list.append(PathRequest(**params))
+    return requests_list
+
+
+def _check_one_request(params, f_max_from_si):
+    """Checks that the requested parameters are consistant (spacing vs nb channel vs transponder mode...)"""
+    f_min = params['f_min']
+    f_max = params['f_max']
+    max_recommanded_nb_channels = automatic_nch(f_min, f_max, params['spacing'])
+    if params['baud_rate'] is not None:
+        # implicitly means that a mode is defined with min_spacing
+        if params['min_spacing'] > params['spacing']:
+            msg = f'Request {params["request_id"]} has spacing below transponder ' +\
+                  f'{params["trx_type"]} {params["trx_mode"]} min spacing value ' +\
+                  f'{params["min_spacing"]*1e-9}GHz.\nComputation stopped'
+            print(msg)
+            _logger.critical(msg)
+            raise ServiceError(msg)
+        if f_max > f_max_from_si:
+            msg = f'''Requested channel number {params["nb_channel"]}, baud rate {params["baud_rate"]} GHz
+            and requested spacing {params["spacing"]*1e-9}GHz is not consistent with frequency range
+            {f_min*1e-12} THz, {f_max*1e-12} THz, min recommanded spacing {params["min_spacing"]*1e-9}GHz.
+            max recommanded nb of channels is {max_recommanded_nb_channels}.'''
+            _logger.critical(msg)
+            raise ServiceError(msg)
+
+
+def disjunctions_from_json(json_data):
+    """ reads the disjunction requests from the json dict and create the list
+        of requested disjunctions for this set of requests
+    """
+    disjunctions_list = []
+    if 'synchronization' in json_data:
+        for snc in json_data['synchronization']:
+            params = {}
+            params['disjunction_id'] = snc['synchronization-id']
+            params['relaxable'] = snc['svec']['relaxable']
+            params['link_diverse'] = 'link' in snc['svec']['disjointness']
+            params['node_diverse'] = 'node' in snc['svec']['disjointness']
+            params['disjunctions_req'] = snc['svec']['request-id-number']
+            disjunctions_list.append(Disjunction(**params))
+
+    return disjunctions_list
+
+
+def convert_service_sheet(
+        input_filename,
+        eqpt,
+        network,
+        network_filename=None,
+        output_filename='',
+        bidir=False):
+    if output_filename == '':
+        output_filename = f'{str(input_filename)[0:len(str(input_filename))-len(str(input_filename.suffixes[0]))]}_services.json'
+    data = read_service_sheet(input_filename, eqpt, network, network_filename, bidir)
+    save_json(data, output_filename)
+    return data

gnpy/tools/plots.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.tools.plots
+================
+
+Graphs and plots usable from a CLI application
+'''
+
+from matplotlib.pyplot import show, axis, figure, title, text
+from networkx import draw_networkx
+from gnpy.core.elements import Transceiver
+
+
+def _try_city(node):
+    return node.location.city if node.location.city else node.uid
+
+
+def plot_baseline(network):
+    pos = {n: (n.lng, n.lat) for n in network.nodes()}
+    labels = {n: _try_city(n) for n in network.nodes() if isinstance(n, Transceiver)}
+    draw_networkx(network, pos=pos, node_size=50, node_color='#ababab', edge_color='#ababab',
+                  labels=labels, font_size=14)
+    axis('off')
+    show()
+
+
+def plot_results(network, path, source, destination):
+    path_edges = set(zip(path[:-1], path[1:]))
+    edges = set(network.edges()) - path_edges
+    nodes = [n for n in network.nodes() if n not in path]
+    pos = {n: (n.lng, n.lat) for n in network.nodes()}
+    nodes_by_pos = {}
+    for k, (x, y) in pos.items():
+        nodes_by_pos.setdefault((round(x, 1), round(y, 1)), []).append(k)
+
+    labels = {n: _try_city(n) for n in network.nodes() if isinstance(n, Transceiver)}
+
+    fig = figure()
+    draw_networkx(network, pos=pos, labels=labels, font_size=14,
+                  nodelist=nodes, node_color='#ababab', node_size=50,
+                  edgelist=edges, edge_color='#ababab')
+    draw_networkx(network, pos=pos, with_labels=False,
+                  nodelist=path, node_color='#ff0000', node_size=55,
+                  edgelist=path_edges, edge_color='#ff0000')
+    title(f'Propagating from {_try_city(source)} to {_try_city(destination)}')
+    axis('off')
+
+    heading = 'Spectral Information\n\n'
+    textbox = text(0.85, 0.20, heading, fontsize=14, fontname='Ubuntu Mono',
+                   verticalalignment='top', transform=fig.axes[0].transAxes,
+                   bbox={'boxstyle': 'round', 'facecolor': 'wheat', 'alpha': 0.5})
+
+    msgs = {(x, y): heading + '\n\n'.join(str(n) for n in ns if n in path)
+            for (x, y), ns in nodes_by_pos.items()}
+
+    def hover(event):
+        if event.xdata is None or event.ydata is None:
+            return
+        if fig.contains(event):
+            x, y = round(event.xdata, 1), round(event.ydata, 1)
+            if (x, y) in msgs:
+                textbox.set_text(msgs[x, y])
+            else:
+                textbox.set_text(heading)
+            fig.canvas.draw_idle()
+
+    fig.canvas.mpl_connect('motion_notify_event', hover)
+    show()

gnpy/tools/service_sheet.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.tools.service_sheet
+========================
+
+XLS parser that can be called to create a JSON request file in accordance with
+Yang model for requesting path computation.
+
+See: draft-ietf-teas-yang-path-computation-01.txt
+"""
+
+from xlrd import open_workbook, XL_CELL_EMPTY
+from collections import namedtuple
+from logging import getLogger
+from copy import deepcopy
+from gnpy.core.utils import db2lin
+from gnpy.core.exceptions import ServiceError
+from gnpy.core.elements import Transceiver, Roadm, Edfa, Fiber
+import gnpy.core.ansi_escapes as ansi_escapes
+from gnpy.tools.convert import corresp_names, corresp_next_node
+
+SERVICES_COLUMN = 12
+
+
+def all_rows(sheet, start=0):
+    return (sheet.row(x) for x in range(start, sheet.nrows))
+
+
+logger = getLogger(__name__)
+
+
+class Request(namedtuple('Request', 'request_id source destination trx_type mode \
+    spacing power nb_channel disjoint_from nodes_list is_loose path_bandwidth')):
+    def __new__(cls, request_id, source, destination, trx_type,  mode=None, spacing=None, power=None, nb_channel=None, disjoint_from='',  nodes_list=None, is_loose='', path_bandwidth=None):
+        return super().__new__(cls, request_id, source, destination, trx_type, mode, spacing, power, nb_channel, disjoint_from,  nodes_list, is_loose, path_bandwidth)
+
+
+class Element:
+    def __eq__(self, other):
+        return type(self) == type(other) and self.uid == other.uid
+
+    def __hash__(self):
+        return hash((type(self), self.uid))
+
+
+class Request_element(Element):
+    def __init__(self, Request, equipment, bidir):
+        # request_id is str
+        # excel has automatic number formatting that adds .0 on integer values
+        # the next lines recover the pure int value, assuming this .0 is unwanted
+        self.request_id = correct_xlrd_int_to_str_reading(Request.request_id)
+        self.source = f'trx {Request.source}'
+        self.destination = f'trx {Request.destination}'
+        # TODO: the automatic naming generated by excel parser requires that source and dest name
+        # be a string starting with 'trx' : this is manually added here.
+        self.srctpid = f'trx {Request.source}'
+        self.dsttpid = f'trx {Request.destination}'
+        self.bidir = bidir
+        # test that trx_type belongs to eqpt_config.json
+        # if not replace it with a default
+        try:
+            if equipment['Transceiver'][Request.trx_type]:
+                self.trx_type = correct_xlrd_int_to_str_reading(Request.trx_type)
+            if Request.mode is not None:
+                Requestmode = correct_xlrd_int_to_str_reading(Request.mode)
+                if [mode for mode in equipment['Transceiver'][Request.trx_type].mode if mode['format'] == Requestmode]:
+                    self.mode = Requestmode
+                else:
+                    msg = f'Request Id: {self.request_id} - could not find tsp : \'{Request.trx_type}\' with mode: \'{Requestmode}\' in eqpt library \nComputation stopped.'
+                    # print(msg)
+                    logger.critical(msg)
+                    raise ServiceError(msg)
+            else:
+                Requestmode = None
+                self.mode = Request.mode
+        except KeyError:
+            msg = f'Request Id: {self.request_id} - could not find tsp : \'{Request.trx_type}\' with mode: \'{Request.mode}\' in eqpt library \nComputation stopped.'
+            # print(msg)
+            logger.critical(msg)
+            raise ServiceError(msg)
+        # excel input are in GHz and dBm
+        if Request.spacing is not None:
+            self.spacing = Request.spacing * 1e9
+        else:
+            msg = f'Request {self.request_id} missing spacing: spacing is mandatory.\ncomputation stopped'
+            logger.critical(msg)
+            raise ServiceError(msg)
+        if Request.power is not None:
+            self.power = db2lin(Request.power) * 1e-3
+        else:
+            self.power = None
+        if Request.nb_channel is not None:
+            self.nb_channel = int(Request.nb_channel)
+        else:
+            self.nb_channel = None
+
+        value = correct_xlrd_int_to_str_reading(Request.disjoint_from)
+        self.disjoint_from = [n for n in value.split(' | ') if value]
+        self.nodes_list = []
+        if Request.nodes_list:
+            self.nodes_list = Request.nodes_list.split(' | ')
+        self.loose = 'LOOSE'
+        if Request.is_loose.lower() == 'no':
+            self.loose = 'STRICT'
+        self.path_bandwidth = None
+        if Request.path_bandwidth is not None:
+            self.path_bandwidth = Request.path_bandwidth * 1e9
+        else:
+            self.path_bandwidth = 0
+
+    uid = property(lambda self: repr(self))
+
+    @property
+    def pathrequest(self):
+        # Default assumption for bidir is False
+        req_dictionnary = {
+            'request-id': self.request_id,
+            'source': self.source,
+            'destination': self.destination,
+            'src-tp-id': self.srctpid,
+            'dst-tp-id': self.dsttpid,
+            'bidirectional': self.bidir,
+            'path-constraints': {
+                'te-bandwidth': {
+                    'technology': 'flexi-grid',
+                    'trx_type': self.trx_type,
+                    'trx_mode': self.mode,
+                    'effective-freq-slot': [{'N': 'null', 'M': 'null'}],
+                    'spacing': self.spacing,
+                    'max-nb-of-channel': self.nb_channel,
+                    'output-power': self.power
+                }
+            }
+        }
+
+        if self.nodes_list:
+            req_dictionnary['explicit-route-objects'] = {}
+            temp = {'route-object-include-exclude': [
+                {'explicit-route-usage': 'route-include-ero',
+                 'index': self.nodes_list.index(node),
+                 'num-unnum-hop': {
+                     'node-id': f'{node}',
+                     'link-tp-id': 'link-tp-id is not used',
+                     'hop-type': f'{self.loose}',
+                 }
+                 }
+                for node in self.nodes_list]
+            }
+            req_dictionnary['explicit-route-objects'] = temp
+        if self.path_bandwidth is not None:
+            req_dictionnary['path-constraints']['te-bandwidth']['path_bandwidth'] = self.path_bandwidth
+
+        return req_dictionnary
+
+    @property
+    def pathsync(self):
+        if self.disjoint_from:
+            return {'synchronization-id': self.request_id,
+                    'svec': {
+                        'relaxable': 'false',
+                        'disjointness': 'node link',
+                        'request-id-number': [self.request_id] + [n for n in self.disjoint_from]
+                    }
+                    }
+        else:
+            return None
+        # TO-DO: avoid multiple entries with same synchronisation vectors
+
+    @property
+    def json(self):
+        return self.pathrequest, self.pathsync
+
+
+def read_service_sheet(
+        input_filename,
+        eqpt,
+        network,
+        network_filename=None,
+        bidir=False):
+    """ converts a service sheet into a json structure
+    """
+    if network_filename is None:
+        network_filename = input_filename
+    service = parse_excel(input_filename)
+    req = [Request_element(n, eqpt, bidir) for n in service]
+    req = correct_xls_route_list(network_filename, network, req)
+    # if there is no sync vector , do not write any synchronization
+    synchro = [n.json[1] for n in req if n.json[1] is not None]
+    if synchro:
+        data = {
+            'path-request': [n.json[0] for n in req],
+            'synchronization': synchro
+        }
+    else:
+        data = {
+            'path-request': [n.json[0] for n in req]
+        }
+    return data
+
+
+def correct_xlrd_int_to_str_reading(v):
+    if not isinstance(v, str):
+        value = str(int(v))
+        if value.endswith('.0'):
+            value = value[:-2]
+    else:
+        value = v
+    return value
+
+
+def parse_row(row, fieldnames):
+    return {f: r.value for f, r in zip(fieldnames, row[0:SERVICES_COLUMN])
+            if r.ctype != XL_CELL_EMPTY}
+
+
+def parse_excel(input_filename):
+    with open_workbook(input_filename) as wb:
+        service_sheet = wb.sheet_by_name('Service')
+        services = list(parse_service_sheet(service_sheet))
+    return services
+
+
+def parse_service_sheet(service_sheet):
+    """ reads each column according to authorized fieldnames. order is not important.
+    """
+    logger.info(f'Validating headers on {service_sheet.name!r}')
+    # add a test on field to enable the '' field case that arises when columns on the
+    # right hand side are used as comments or drawing in the excel sheet
+    header = [x.value.strip() for x in service_sheet.row(4)[0:SERVICES_COLUMN]
+              if len(x.value.strip()) > 0]
+
+    # create a service_fieldname independant from the excel column order
+    # to be compatible with any version of the sheet
+    # the following dictionnary records the excel field names and the corresponding parameter's name
+
+    authorized_fieldnames = {
+        'route id': 'request_id', 'Source': 'source', 'Destination': 'destination',
+        'TRX type': 'trx_type', 'Mode': 'mode', 'System: spacing': 'spacing',
+        'System: input power (dBm)': 'power', 'System: nb of channels': 'nb_channel',
+        'routing: disjoint from': 'disjoint_from', 'routing: path': 'nodes_list',
+        'routing: is loose?': 'is_loose', 'path bandwidth': 'path_bandwidth'}
+    try:
+        service_fieldnames = [authorized_fieldnames[e] for e in header]
+    except KeyError:
+        msg = f'Malformed header on Service sheet: {header} field not in {authorized_fieldnames}'
+        logger.critical(msg)
+        raise ValueError(msg)
+    for row in all_rows(service_sheet, start=5):
+        yield Request(**parse_row(row[0:SERVICES_COLUMN], service_fieldnames))
+
+
+def correct_xls_route_list(network_filename, network, pathreqlist):
+    """ prepares the format of route list of nodes to be consistant with nodes names:
+        remove wrong names, find correct names for ila, roadm and fused if the entry was
+        xls.
+        if it was not xls, all names in list should be exact name in the network.
+    """
+
+    # first loads the base correspondance dict built with excel naming
+    corresp_roadm, corresp_fused, corresp_ila = corresp_names(network_filename, network)
+    # then correct dict names with names of the autodisign and find next_node name
+    # according to xls naming
+    corresp_ila, next_node = corresp_next_node(network, corresp_ila, corresp_roadm)
+    # finally correct constraints based on these dict
+    trxfibertype = [n.uid for n in network.nodes() if isinstance(n, (Transceiver, Fiber))]
+    roadmtype = [n.uid for n in network.nodes() if isinstance(n, Roadm)]
+    edfatype = [n.uid for n in network.nodes() if isinstance(n, Edfa)]
+    # TODO there is a problem of identification of fibers in case of parallel
+    # fibers between two adjacent roadms so fiber constraint is not supported
+    transponders = [n.uid for n in network.nodes() if isinstance(n, Transceiver)]
+    for pathreq in pathreqlist:
+        # first check that source and dest are transceivers
+        if pathreq.source not in transponders:
+            msg = f'{ansi_escapes.red}Request: {pathreq.request_id}: could not find' +\
+                f' transponder source : {pathreq.source}.{ansi_escapes.reset}'
+            logger.critical(msg)
+            raise ServiceError(msg)
+
+        if pathreq.destination not in transponders:
+            msg = f'{ansi_escapes.red}Request: {pathreq.request_id}: could not find' +\
+                f' transponder destination: {pathreq.destination}.{ansi_escapes.reset}'
+            logger.critical(msg)
+            raise ServiceError(msg)
+        # silently pop source and dest nodes from the list if they were added by the user as first
+        # and last elem in the constraints respectively. Other positions must lead to an error
+        # caught later on
+        if pathreq.nodes_list and pathreq.source == pathreq.nodes_list[0]:
+            pathreq.loose_list.pop(0)
+            pathreq.nodes_list.pop(0)
+        if pathreq.nodes_list and pathreq.destination == pathreq.nodes_list[-1]:
+            pathreq.loose_list.pop(-1)
+            pathreq.nodes_list.pop(-1)
+        # Then process user defined constraints with respect to automatic namings
+        temp = deepcopy(pathreq)
+        # This needs a temporary object since we may suppress/correct elements in the list
+        # during the process
+        for i, n_id in enumerate(temp.nodes_list):
+            # n_id must not be a transceiver and must not be a fiber (non supported, user
+            # can not enter fiber names in excel)
+            if n_id not in trxfibertype:
+                # check that n_id is in the node list, if not find a correspondance name
+                if n_id in roadmtype + edfatype:
+                    nodes_suggestion = [n_id]
+                else:
+                    # checks first roadm, fused, and ila in this order, because ila automatic name
+                    # contain roadm names. If it is a fused node, next ila names might be correct
+                    # suggestions, especially if following fibers were splitted and ila names
+                    # created with the name of the fused node
+                    if n_id in corresp_roadm.keys():
+                        nodes_suggestion = corresp_roadm[n_id]
+                    elif n_id in corresp_fused.keys():
+                        nodes_suggestion = corresp_fused[n_id] + corresp_ila[n_id]
+                    elif n_id in corresp_ila.keys():
+                        nodes_suggestion = corresp_ila[n_id]
+                    else:
+                        nodes_suggestion = []
+                if nodes_suggestion:
+                    try:
+                        if len(nodes_suggestion) > 1:
+                            # if there is more than one suggestion, we need to choose the direction
+                            # we rely on the next node provided by the user for this purpose
+                            new_n = next(n for n in nodes_suggestion
+                                         if n in next_node.keys() and next_node[n]
+                                         in temp.nodes_list[i:] + [pathreq.destination] and
+                                         next_node[n] not in temp.nodes_list[:i])
+                        else:
+                            new_n = nodes_suggestion[0]
+                        if new_n != n_id:
+                            # warns the user when the correct name is used only in verbose mode,
+                            # eg 'a' is a roadm and correct name is 'roadm a' or when there was
+                            # too much ambiguity, 'b' is an ila, its name can be:
+                            # Edfa0_fiber (a → b)-xx if next node is c or
+                            # Edfa0_fiber (c → b)-xx if next node is a
+                            msg = f'{ansi_escapes.yellow}Invalid route node specified:' +\
+                                f'\n\t\'{n_id}\', replaced with \'{new_n}\'{ansi_escapes.reset}'
+                            logger.info(msg)
+                            pathreq.nodes_list[pathreq.nodes_list.index(n_id)] = new_n
+                    except StopIteration:
+                        # shall not come in this case, unless requested direction does not exist
+                        msg = f'{ansi_escapes.yellow}Invalid route specified {n_id}: could' +\
+                            f' not decide on direction, skipped!.\nPlease add a valid' +\
+                            f' direction in constraints (next neighbour node){ansi_escapes.reset}'
+                        print(msg)
+                        logger.info(msg)
+                        pathreq.loose_list.pop(pathreq.nodes_list.index(n_id))
+                        pathreq.nodes_list.remove(n_id)
+                else:
+                    if temp.loose_list[i] == 'LOOSE':
+                        # if no matching can be found in the network just ignore this constraint
+                        # if it is a loose constraint
+                        # warns the user that this node is not part of the topology
+                        msg = f'{ansi_escapes.yellow}Invalid node specified:\n\t\'{n_id}\'' +\
+                            f', could not use it as constraint, skipped!{ansi_escapes.reset}'
+                        print(msg)
+                        logger.info(msg)
+                        pathreq.loose_list.pop(pathreq.nodes_list.index(n_id))
+                        pathreq.nodes_list.remove(n_id)
+                    else:
+                        msg = f'{ansi_escapes.red}Could not find node:\n\t\'{n_id}\' in network' +\
+                            f' topology. Strict constraint can not be applied.{ansi_escapes.reset}'
+                        logger.critical(msg)
+                        raise ServiceError(msg)
+            else:
+                if temp.loose_list[i] == 'LOOSE':
+                    print(f'{ansi_escapes.yellow}Invalid route node specified:\n\t\'{n_id}\'' +
+                          f' type is not supported as constraint with xls network input,' +
+                          f' skipped!{ansi_escapes.reset}')
+                    pathreq.loose_list.pop(pathreq.nodes_list.index(n_id))
+                    pathreq.nodes_list.remove(n_id)
+                else:
+                    msg = f'{ansi_escapes.red}Invalid route node specified \n\t\'{n_id}\'' +\
+                        f' type is not supported as constraint with xls network input,' +\
+                        f', Strict constraint can not be applied.{ansi_escapes.reset}'
+                    logger.critical(msg)
+                    raise ServiceError(msg)
+    return pathreqlist

gnpy/topology/__init__.py

@@ -0,0 +1,3 @@
+'''
+Tracking :py:mod:`.request` for spectrum and their :py:mod:`.spectrum_assignment`.
+'''

gnpy/topology/spectrum_assignment.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.topology.spectrum_assignment
+=================================
+
+This module contains the :class:`Oms` and :class:`Bitmap` classes and methods to
+select and assign spectrum. The :func:`spectrum_selection` function identifies the free
+slots and :func:`select_candidate` selects the candidate spectrum according to
+strategy: for example first fit
+oms records its elements, and elements are updated with an oms to have
+element/oms correspondace
+"""
+
+from collections import namedtuple
+from logging import getLogger
+from math import ceil
+from gnpy.core.elements import Roadm, Transceiver
+from gnpy.core.exceptions import ServiceError, SpectrumError
+
+LOGGER = getLogger(__name__)
+
+
+class Bitmap:
+    """ records the spectrum occupation
+    """
+
+    def __init__(self, f_min, f_max, grid, guardband=0.15e12, bitmap=None):
+        # n is the min index including guardband. Guardband is require to be sure
+        # that a channel can be assigned  with center frequency fmin (means that its
+        # slot occupation goes below freq_index_min
+        n_min = frequency_to_n(f_min - guardband, grid)
+        n_max = frequency_to_n(f_max + guardband, grid) - 1
+        self.n_min = n_min
+        self.n_max = n_max
+        self.freq_index_min = frequency_to_n(f_min)
+        self.freq_index_max = frequency_to_n(f_max)
+        self.freq_index = list(range(n_min, n_max + 1))
+        if bitmap is None:
+            self.bitmap = [1] * (n_max - n_min + 1)
+        elif len(bitmap) == len(self.freq_index):
+            self.bitmap = bitmap
+        else:
+            raise SpectrumError(f'bitmap is not consistant with f_min{f_min} - n: {n_min} and f_max{f_max}- n :{n_max}')
+
+    def getn(self, i):
+        """ converts the n (itu grid) into a local index
+        """
+        return self.freq_index[i]
+
+    def geti(self, nvalue):
+        """ converts the local index into n (itu grid)
+        """
+        return self.freq_index.index(nvalue)
+
+    def insert_left(self, newbitmap):
+        """ insert bitmap on the left to align oms bitmaps if their start frequencies are different
+        """
+        self.bitmap = newbitmap + self.bitmap
+        temp = list(range(self.n_min - len(newbitmap), self.n_min))
+        self.freq_index = temp + self.freq_index
+        self.n_min = self.freq_index[0]
+
+    def insert_right(self, newbitmap):
+        """ insert bitmap on the right to align oms bitmaps if their stop frequencies are different
+        """
+        self.bitmap = self.bitmap + newbitmap
+        self.freq_index = self.freq_index + list(range(self.n_max, self.n_max + len(newbitmap)))
+        self.n_max = self.freq_index[-1]
+
+
+#    +'grid available_slots f_min f_max services_list')
+OMSParams = namedtuple('OMSParams', 'oms_id el_id_list el_list')
+
+
+class OMS:
+    """ OMS class is the logical container that represent a link between two adjacent ROADMs and
+        records the crossed elements and the occupied spectrum
+    """
+
+    def __init__(self, *args, **params):
+        params = OMSParams(**params)
+        self.oms_id = params.oms_id
+        self.el_id_list = params.el_id_list
+        self.el_list = params.el_list
+        self.spectrum_bitmap = []
+        self.nb_channels = 0
+        self.service_list = []
+    # TODO
+
+    def __str__(self):
+        return '\n\t'.join([f'{type(self).__name__} {self.oms_id}',
+                            f'{self.el_id_list[0]} - {self.el_id_list[-1]}'])
+
+    def __repr__(self):
+        return '\n\t'.join([f'{type(self).__name__} {self.oms_id}',
+                            f'{self.el_id_list[0]} - {self.el_id_list[-1]}', '\n'])
+
+    def add_element(self, elem):
+        """ records oms elements
+        """
+        self.el_id_list.append(elem.uid)
+        self.el_list.append(elem)
+
+    def update_spectrum(self, f_min, f_max, guardband=0.15e12, existing_spectrum=None,
+                        grid=0.00625e12):
+        """ frequencies expressed in Hz
+        """
+        if existing_spectrum is None:
+            # add some 150 GHz margin to enable a center channel on f_min
+            # use ITU-T G694.1
+            # Flexible DWDM grid definition
+            # For the flexible DWDM grid, the allowed frequency slots have a nominal
+            # central frequency (in THz) defined by:
+            # 193.1 + n × 0.00625 where n is a positive or negative integer including 0
+            # and 0.00625 is the nominal central frequency granularity in THz
+            # and a slot width defined by:
+            # 12.5 × m where m is a positive integer and 12.5 is the slot width granularity in
+            # GHz.
+            # Any combination of frequency slots is allowed as long as no two frequency
+            # slots overlap.
+
+            # TODO : add explaination on that / parametrize ....
+            self.spectrum_bitmap = Bitmap(f_min, f_max, grid, guardband)
+            # print(len(self.spectrum_bitmap.bitmap))
+
+    def assign_spectrum(self, nvalue, mvalue):
+        """ change oms spectrum to mark spectrum assigned
+        """
+        if not isinstance(nvalue, int):
+            raise SpectrumError(f'N must be a signed integer, got {nvalue}')
+        if not isinstance(mvalue, int):
+            raise SpectrumError(f'M must be an integer, got {mvalue}')
+        if mvalue <= 0:
+            raise SpectrumError(f'M must be positive, got {mvalue}')
+        if nvalue > self.spectrum_bitmap.freq_index_max:
+            raise SpectrumError(f'N {nvalue} over the upper spectrum boundary')
+        if nvalue < self.spectrum_bitmap.freq_index_min:
+            raise SpectrumError(f'N {nvalue} below the lower spectrum boundary')
+        startn, stopn = mvalue_to_slots(nvalue, mvalue)
+        if stopn > self.spectrum_bitmap.n_max:
+            raise SpectrumError(f'N {nvalue}, M {mvalue} over the N spectrum bitmap bounds')
+        if startn <= self.spectrum_bitmap.n_min:
+            raise SpectrumError(f'N {nvalue}, M {mvalue} below the N spectrum bitmap bounds')
+        self.spectrum_bitmap.bitmap[self.spectrum_bitmap.geti(startn):self.spectrum_bitmap.geti(stopn) + 1] = [0] * (stopn - startn + 1)
+
+    def add_service(self, service_id, nb_wl):
+        """ record service and mark spectrum as occupied
+        """
+        self.service_list.append(service_id)
+        self.nb_channels += nb_wl
+
+
+def frequency_to_n(freq, grid=0.00625e12):
+    """ converts frequency into the n value (ITU grid)
+        reference to Recommendation G.694.1 (02/12), Figure I.3
+        https://www.itu.int/rec/T-REC-G.694.1-201202-I/en
+
+    >>> frequency_to_n(193.1375e12)
+    6
+    >>> frequency_to_n(193.225e12)
+    20
+
+    """
+    return (int)((freq - 193.1e12) / grid)
+
+
+def nvalue_to_frequency(nvalue, grid=0.00625e12):
+    """ converts n value into a frequency
+        reference to Recommendation G.694.1 (02/12), Table 1
+        https://www.itu.int/rec/T-REC-G.694.1-201202-I/en
+
+    >>> nvalue_to_frequency(6)
+    193137500000000.0
+    >>> nvalue_to_frequency(-1, 0.1e12)
+    193000000000000.0
+
+    """
+    return 193.1e12 + nvalue * grid
+
+
+def mvalue_to_slots(nvalue, mvalue):
+    """ convert center n an m into start and stop n
+    """
+    startn = nvalue - mvalue
+    stopn = nvalue + mvalue - 1
+    return startn, stopn
+
+
+def slots_to_m(startn, stopn):
+    """ converts the start and stop n values to the center n and m value
+        reference to Recommendation G.694.1 (02/12), Figure I.3
+        https://www.itu.int/rec/T-REC-G.694.1-201202-I/en
+
+    >>> nval, mval = slots_to_m(6, 20)
+    >>> nval
+    13
+    >>> mval
+    7
+
+    """
+    nvalue = (int)((startn + stopn + 1) / 2)
+    mvalue = (int)((stopn - startn + 1) / 2)
+    return nvalue, mvalue
+
+
+def m_to_freq(nvalue, mvalue, grid=0.00625e12):
+    """ converts m into frequency range
+        spectrum(13,7) is (193137500000000.0, 193225000000000.0)
+        reference to Recommendation G.694.1 (02/12), Figure I.3
+        https://www.itu.int/rec/T-REC-G.694.1-201202-I/en
+
+    >>> fstart, fstop = m_to_freq(13, 7)
+    >>> fstart
+    193137500000000.0
+    >>> fstop
+    193225000000000.0
+
+    """
+    startn, stopn = mvalue_to_slots(nvalue, mvalue)
+    fstart = nvalue_to_frequency(startn, grid)
+    fstop = nvalue_to_frequency(stopn + 1, grid)
+    return fstart, fstop
+
+
+def align_grids(oms_list):
+    """ used to apply same grid to all oms : same starting n, stop n and slot size
+        out of grid slots are set to 0
+    """
+    n_min = min([o.spectrum_bitmap.n_min for o in oms_list])
+    n_max = max([o.spectrum_bitmap.n_max for o in oms_list])
+    for this_o in oms_list:
+        if (this_o.spectrum_bitmap.n_min - n_min) > 0:
+            this_o.spectrum_bitmap.insert_left([0] * (this_o.spectrum_bitmap.n_min - n_min))
+        if (n_max - this_o.spectrum_bitmap.n_max) > 0:
+            this_o.spectrum_bitmap.insert_right([0] * (n_max - this_o.spectrum_bitmap.n_max))
+    return oms_list
+
+
+def build_oms_list(network, equipment):
+    """ initialization of OMS list in the network
+        an oms is build reading all intermediate nodes between two adjacent ROADMs
+        each element within the list is being added an oms and oms_id to record the
+        oms it belongs to.
+        the function supports different spectrum width and supposes that the whole network
+        works with the min range among OMSs
+    """
+    oms_id = 0
+    oms_list = []
+    for node in [n for n in network.nodes() if isinstance(n, Roadm)]:
+        for edge in network.edges([node]):
+            if not isinstance(edge[1], Transceiver):
+                nd_in = edge[0]  # nd_in is a Roadm
+                try:
+                    nd_in.oms_list.append(oms_id)
+                except AttributeError:
+                    nd_in.oms_list = []
+                    nd_in.oms_list.append(oms_id)
+                nd_out = edge[1]
+
+                params = {}
+                params['oms_id'] = oms_id
+                params['el_id_list'] = []
+                params['el_list'] = []
+                oms = OMS(**params)
+                oms.add_element(nd_in)
+                while not isinstance(nd_out, Roadm):
+                    oms.add_element(nd_out)
+                    # add an oms_id in the element
+                    nd_out.oms_id = oms_id
+                    nd_out.oms = oms
+                    n_temp = nd_out
+                    nd_out = next(n[1] for n in network.edges([n_temp]) if n[1].uid != nd_in.uid)
+                    nd_in = n_temp
+
+                oms.add_element(nd_out)
+                # nd_out is a Roadm
+                try:
+                    nd_out.oms_list.append(oms_id)
+                except AttributeError:
+                    nd_out.oms_list = []
+                    nd_out.oms_list.append(oms_id)
+
+                oms.update_spectrum(equipment['SI']['default'].f_min,
+                                    equipment['SI']['default'].f_max, grid=0.00625e12)
+                # oms.assign_spectrum(13,7) gives back (193137500000000.0, 193225000000000.0)
+                # as in the example in the standard
+                # oms.assign_spectrum(13,7)
+
+                oms_list.append(oms)
+                oms_id += 1
+    oms_list = align_grids(oms_list)
+    reversed_oms(oms_list)
+    return oms_list
+
+
+def reversed_oms(oms_list):
+    """ identifies reversed OMS
+        only applicable for non parallel OMS
+    """
+    for oms in oms_list:
+        has_reversed = False
+        for this_o in oms_list:
+            if (oms.el_id_list[0] == this_o.el_id_list[-1] and
+                    oms.el_id_list[-1] == this_o.el_id_list[0]):
+                oms.reversed_oms = this_o
+                has_reversed = True
+                break
+        if not has_reversed:
+            oms.reversed_oms = None
+
+
+def bitmap_sum(band1, band2):
+    """mark occupied bitmap by 0 if the slot is occupied in band1 or in band2"""
+    res = []
+    for i, elem in enumerate(band1):
+        if band2[i] * elem == 0:
+            res.append(0)
+        else:
+            res.append(1)
+    return res
+
+
+def spectrum_selection(pth, oms_list, requested_m, requested_n=None):
+    """Collects spectrum availability and call the select_candidate function"""
+
+    # use indexes instead of ITU-T n values
+    path_oms = []
+    for elem in pth:
+        if not isinstance(elem, Roadm) and not isinstance(elem, Transceiver):
+            # only edfa, fused and fibers have oms_id attribute
+            path_oms.append(elem.oms_id)
+    # remove duplicate oms_id, order is not important
+    path_oms = list(set(path_oms))
+    # assuming all oms have same freq index
+    if not path_oms:
+        candidate = (None, None, None)
+        return candidate, path_oms
+    freq_index = oms_list[path_oms[0]].spectrum_bitmap.freq_index
+    freq_index_min = oms_list[path_oms[0]].spectrum_bitmap.freq_index_min
+    freq_index_max = oms_list[path_oms[0]].spectrum_bitmap.freq_index_max
+
+    freq_availability = oms_list[path_oms[0]].spectrum_bitmap.bitmap
+    for oms in path_oms[1:]:
+        freq_availability = bitmap_sum(oms_list[oms].spectrum_bitmap.bitmap, freq_availability)
+    if requested_n is None:
+        # avoid slots reserved on the edge 0.15e-12 on both sides -> 24
+        candidates = [(freq_index[i] + requested_m, freq_index[i], freq_index[i] + 2 * requested_m - 1)
+                      for i in range(len(freq_availability))
+                      if freq_availability[i:i + 2 * requested_m] == [1] * (2 * requested_m)
+                      and freq_index[i] >= freq_index_min
+                      and freq_index[i + 2 * requested_m - 1] <= freq_index_max]
+
+        candidate = select_candidate(candidates, policy='first_fit')
+    else:
+        i = oms_list[path_oms[0]].spectrum_bitmap.geti(requested_n)
+        # print(f'N {requested_n} i {i}')
+        # print(freq_availability[i-m:i+m] )
+        # print(freq_index[i-m:i+m])
+        if (freq_availability[i - requested_m:i + requested_m] == [1] * (2 * requested_m) and
+                freq_index[i - requested_m] >= freq_index_min
+                and freq_index[i + requested_m - 1] <= freq_index_max):
+            # candidate is the triplet center_n, startn and stopn
+            candidate = (requested_n, requested_n - requested_m, requested_n + requested_m - 1)
+        else:
+            candidate = (None, None, None)
+        # print("coucou11")
+        # print(candidate)
+    # print(freq_availability[321:321+2*m])
+    # a = [i+321 for i in range(2*m)]
+    # print(a)
+    # print(candidate)
+    return candidate, path_oms
+
+
+def select_candidate(candidates, policy):
+    """ selects a candidate among all available spectrum
+    """
+    if policy == 'first_fit':
+        if candidates:
+            return candidates[0]
+        else:
+            return (None, None, None)
+    else:
+        raise ServiceError('Only first_fit spectrum assignment policy is implemented.')
+
+
+def pth_assign_spectrum(pths, rqs, oms_list, rpths):
+    """ basic first fit assignment
+        if reversed path are provided, means that occupation is bidir
+    """
+    for i, pth in enumerate(pths):
+        # computes the number of channels required
+        try:
+            if rqs[i].blocking_reason:
+                rqs[i].blocked = True
+                rqs[i].N = 0
+                rqs[i].M = 0
+        except AttributeError:
+            nb_wl = ceil(rqs[i].path_bandwidth / rqs[i].bit_rate)
+            # computes the total nb of slots according to requested spacing
+            # TODO : express superchannels
+            # assumes that all channels must be grouped
+            # TODO : enables non contiguous reservation in case of blocking
+            requested_m = ceil(rqs[i].spacing / 0.0125e12) * nb_wl
+            # concatenate all path and reversed path elements to derive slots availability
+            (center_n, startn, stopn), path_oms = spectrum_selection(pth + rpths[i], oms_list, requested_m,
+                                                                     requested_n=None)
+            # checks that requested_m is fitting startm and stopm
+            # if not None, center_n and start, stop frequencies are applicable to all oms of pth
+            # checks that spectrum is not None else indicate blocking reason
+            if center_n is not None:
+                # checks that requested_m is fitting startm and stopm
+                if 2 * requested_m > (stopn - startn + 1):
+                    msg = f'candidate: {(center_n, startn, stopn)} is not consistant ' +\
+                        f'with {requested_m}'
+                    LOGGER.critical(msg)
+                    raise ValueError(msg)
+
+                for oms_elem in path_oms:
+                    oms_list[oms_elem].assign_spectrum(center_n, requested_m)
+                    oms_list[oms_elem].add_service(rqs[i].request_id, nb_wl)
+                rqs[i].blocked = False
+                rqs[i].N = center_n
+                rqs[i].M = requested_m
+            else:
+                rqs[i].blocked = True
+                rqs[i].N = 0
+                rqs[i].M = 0
+                rqs[i].blocking_reason = 'NO_SPECTRUM'

json_structure_description.rst

@@ -7,7 +7,7 @@ Equipment and Network description definitions
 
 Equipment description defines equipment types and those parameters.
 Description is made in JSON file with predefined structure. By default
-**transmission_main_example.py** uses **eqpt_config.json** file and that
+**gnpy-transmission-example** uses **eqpt_config.json** file and that
 can be changed with **-e** or **--equipment** command line parameter.
 Parsing of JSON file is made with
 **gnpy.core.equipment.load_equipment(equipment_description)** and return
@@ -23,7 +23,7 @@ type’][‘subtype’]=object**
 Every equipment type is defined in JSON root with according name and
 array of parameters as value.
 
-.. code-block::
+.. code-block:: none
 
     {"Edfa": [...],
     "Fiber": [...]
@@ -40,7 +40,7 @@ object contains **"type_variety":”type name”** name:value combination,
 if only one subtype exists **"type_variety"** name is not mandatory and
 it will be marked with **”default”** value.
 
-.. code-block::
+.. code-block:: json
 
     {"Edfa": [{
                 "type_variety": "std_medium_gain",
@@ -82,13 +82,13 @@ it will be marked with **”default”** value.
 *******************
 
 Four types of EDFA definition are possible. Description JSON file
-location is in **transmission_main_example.py** folder:
+location is in **gnpy-transmission-example** folder:
 
 -  Advanced – with JSON file describing gain/noise figure tilt and
    gain/noise figure ripple. **"advanced_config_from_json"** value
    contains filename.
 
-.. code-block::
+.. code-block:: json-object
 
     "Edfa":[{
             "type_variety": "high_detail_model_example",
@@ -104,7 +104,7 @@ location is in **transmission_main_example.py** folder:
 -  Variable gain – with JSON file describing gain figure tilt and gain/noise
    figure ripple. **”default_edfa_config.json”** as source file.
 
-.. code-block::
+.. code-block:: json-object
 
     "Edfa":[{
             "type_variety": "std_medium_gain",
@@ -122,7 +122,7 @@ location is in **transmission_main_example.py** folder:
 -  Fixed gain – with JSON file describing gain figure tilt and gain/noise
    figure ripple. **”default_edfa_config.json”** as source file.
 
-.. code-block::
+.. code-block:: json-object
 
     "Edfa":[{
             "type_variety": "std_fixed_gain",
@@ -138,10 +138,10 @@ location is in **transmission_main_example.py** folder:
 - openroadm – with JSON file describing gain figure tilt and gain/noise
    figure ripple. **”default_edfa_config.json”** as source file. 
 
-.. code-block::
+.. code-block:: json-object
 
     "Edfa":[{
-            "type_variety": "low_noise",
+            "type_variety": "openroadm_ila_low_noise",
             "type_def": "openroadm",
             "gain_flatmax": 27,
             "gain_min": 12,
@@ -156,7 +156,7 @@ location is in **transmission_main_example.py** folder:
 
 Fiber element with its parameters:
 
-.. code-block::
+.. code-block:: json-object
 
     "Fiber":[{
             "type_variety": "SSMF",
@@ -165,12 +165,58 @@ Fiber element with its parameters:
             }
         ]
 
+RamanFiber element
+******************
+
+A special variant of the regular ``Fiber`` where the simulation engine accounts for the Raman effect.
+The newly added parameters are nested in the ``raman_efficiency`` dictionary.
+Its shape corresponds to typical properties of silica.
+More details are available from :cite:`curri_merit_2016`.
+
+The ``cr`` property is the normailzed Raman efficiency, so it is is (almost) independent of the fiber type, while the coefficient actually giving Raman gain is g_R=C_R/Aeff.
+
+The ``frequency_offset`` represents the spectral difference between the pumping photon and the one receiving energy.
+
+.. code-block:: json-object
+
+    "RamanFiber":[{
+      "type_variety": "SSMF",
+      "dispersion": 1.67e-05,
+      "gamma": 0.00127,
+      "raman_efficiency": {
+        "cr":[
+            0, 9.4E-06, 2.92E-05, 4.88E-05, 6.82E-05, 8.31E-05, 9.4E-05, 0.0001014, 0.0001069, 0.0001119,
+            0.0001217, 0.0001268, 0.0001365, 0.000149, 0.000165, 0.000181, 0.0001977, 0.0002192, 0.0002469,
+            0.0002749, 0.0002999, 0.0003206, 0.0003405, 0.0003592, 0.000374, 0.0003826, 0.0003841, 0.0003826,
+            0.0003802, 0.0003756, 0.0003549, 0.0003795, 0.000344, 0.0002933, 0.0002024, 0.0001158, 8.46E-05,
+            7.14E-05, 6.86E-05, 8.5E-05, 8.93E-05, 9.01E-05, 8.15E-05, 6.67E-05, 4.37E-05, 3.28E-05, 2.96E-05,
+            2.65E-05, 2.57E-05, 2.81E-05, 3.08E-05, 3.67E-05, 5.85E-05, 6.63E-05, 6.36E-05, 5.5E-05, 4.06E-05,
+            2.77E-05, 2.42E-05, 1.87E-05, 1.6E-05, 1.4E-05, 1.13E-05, 1.05E-05, 9.8E-06, 9.8E-06, 1.13E-05,
+            1.64E-05, 1.95E-05, 2.38E-05, 2.26E-05, 2.03E-05, 1.48E-05, 1.09E-05, 9.8E-06, 1.05E-05, 1.17E-05,
+            1.25E-05, 1.21E-05, 1.09E-05, 9.8E-06, 8.2E-06, 6.6E-06, 4.7E-06, 2.7E-06, 1.9E-06, 1.2E-06, 4E-07,
+            2E-07, 1E-07
+        ],
+        "frequency_offset":[
+          0, 0.5e12, 1e12, 1.5e12, 2e12, 2.5e12, 3e12, 3.5e12, 4e12, 4.5e12, 5e12, 5.5e12, 6e12, 6.5e12, 7e12,
+          7.5e12, 8e12, 8.5e12, 9e12, 9.5e12, 10e12, 10.5e12, 11e12, 11.5e12, 12e12, 12.5e12, 12.75e12,
+          13e12, 13.25e12, 13.5e12, 14e12, 14.5e12, 14.75e12, 15e12, 15.5e12, 16e12, 16.5e12, 17e12,
+          17.5e12, 18e12, 18.25e12, 18.5e12, 18.75e12, 19e12, 19.5e12, 20e12, 20.5e12, 21e12, 21.5e12,
+          22e12, 22.5e12, 23e12, 23.5e12, 24e12, 24.5e12, 25e12, 25.5e12, 26e12, 26.5e12, 27e12, 27.5e12, 28e12,
+          28.5e12, 29e12, 29.5e12, 30e12, 30.5e12, 31e12, 31.5e12, 32e12, 32.5e12, 33e12, 33.5e12, 34e12, 34.5e12,
+          35e12, 35.5e12, 36e12, 36.5e12, 37e12, 37.5e12, 38e12, 38.5e12, 39e12, 39.5e12, 40e12, 40.5e12, 41e12,
+          41.5e12, 42e12
+        ]
+        }
+      }
+    ]
+
+
 1.2.3 Roadm element
 *******************
 
 Roadm element with its parameters:
 
-.. code-block::
+.. code-block:: json-object
 
       "Roadms":[{
             "gain_mode_default_loss": 20,
@@ -184,7 +230,7 @@ Roadm element with its parameters:
 
 Spans element with its parameters:
 
-.. code-block::
+.. code-block:: json-object
 
     "Spans":[{
             "power_mode":true,
@@ -205,7 +251,7 @@ Spans element with its parameters:
 
 Spectral information with its parameters:
 
-.. code-block::
+.. code-block:: json-object
 
     "SI":[{
             "f_min": 191.3e12,
@@ -227,7 +273,9 @@ Spectral information with its parameters:
 Transceiver element with its parameters. **”mode”** can contain multiple
 Transceiver operation formats.
 
-.. code-block::
+Note that ``OSNR`` parameter refers to the receiver's minimal OSNR threshold for a given mode.
+
+.. code-block:: json-object
 
     "Transceiver":[{
                     "frequency":{
@@ -266,7 +314,7 @@ Transceiver operation formats.
 Network description defines network elements with additional to
 equipment description parameters, metadata and elements interconnection.
 Description is made in JSON file with predefined structure. By default
-**transmission_main_example.py** uses **edfa_example_network.json** file
+**gnpy-transmission-example** uses **edfa_example_network.json** file
 and can be changed from command line. Parsing of JSON file is made with
 **gnpy.core.network.load_network(network_description,
 equipment_description)** and return value is **DiGraph** object which
@@ -288,7 +336,7 @@ Network description JSON file root consist of three unordered parts:
 
 -  connections – contains array of unidirectional connection objects
 
-.. code-block::
+.. code-block:: none
 
     {"network_name": "Example Network",
     "elements": [{...},
@@ -317,10 +365,10 @@ obligatory.
 
 Transceiver element with its parameters.
 
-.. code-block::
+.. code-block:: json
 
     {"uid": "trx Site_A",
-    “metadata": {
+    "metadata": {
                 "location": {
                             "city": "Site_A",
                             "region": "",
@@ -339,7 +387,7 @@ Transceiver element with its parameters.
 ROADM element with its parameters. **“params”** is optional, if not used
 default loss value of 20dB is used.
 
-.. code-block::
+.. code-block:: json
 
     {"uid": "roadm Site_A",
     "metadata": {
@@ -363,12 +411,12 @@ default loss value of 20dB is used.
 Fused element with its parameters. **“params”** is optional, if not used
 default loss value of 1dB is used.
 
-.. code-block::
+.. code-block:: json
 
     {"uid": "ingress fused spans in Site_B",
     "metadata": {
                 "location": {
-                            “city": "Site_B",
+                            "city": "Site_B",
                             "region": "",
                             "latitude": 0,
                             "longitude": 0
@@ -386,7 +434,7 @@ default loss value of 1dB is used.
 
 Fiber element with its parameters.
 
-.. code-block::
+.. code-block:: json
 
     {"uid": "fiber (Site_A \\u2192 Site_B)",
     "metadata": {
@@ -406,13 +454,56 @@ Fiber element with its parameters.
                 }
     }
 
+2.2.5. RamanFiber element
+*************************
 
-2.2.5. EDFA element
+.. code-block:: json
+
+    {
+      "uid": "Span1",
+      "type": "RamanFiber",
+      "type_variety": "SSMF",
+      "operational": {
+        "temperature": 283,
+        "raman_pumps": [
+          {
+            "power": 200e-3,
+            "frequency": 205e12,
+            "propagation_direction": "counterprop"
+          },
+          {
+            "power": 206e-3,
+            "frequency": 201e12,
+            "propagation_direction": "counterprop"
+          }
+        ]
+      },
+      "params": {
+        "type_variety": "SSMF",
+        "length": 80.0,
+        "loss_coef": 0.2,
+        "length_units": "km",
+        "att_in": 0,
+        "con_in": 0.5,
+        "con_out": 0.5
+      },
+      "metadata": {
+        "location": {
+          "latitude": 1,
+          "longitude": 0,
+          "city": null,
+          "region": ""
+        }
+      }
+    }
+
+
+2.2.6. EDFA element
 ********************
 
 EDFA element with its parameters.
 
-.. code-block::
+.. code-block:: json
 
     {"uid": "Edfa1",
     "type": "Edfa",
@@ -438,8 +529,31 @@ Each unidirectional connection object in connections array consist of
 two unordered **”from_node”** and **”to_node”** name pair with values
 corresponding to element **”uid”**
 
-.. code-block::
+.. code-block:: json
 
     {"from_node": "roadm Site_C",
     "to_node": "trx Site_C"
     }
+
+************************
+3. Simulation Parameters
+************************
+
+Additional details of the simulation are controlled via ``sim_params.json``:
+
+.. code-block:: json
+
+  {
+    "raman_parameters": {
+      "flag_raman": true,
+      "space_resolution": 10e3,
+      "tolerance": 1e-8
+    },
+    "nli_parameters": {
+      "nli_method_name": "ggn_spectrally_separated",
+      "wdm_grid_size": 50e9,
+      "dispersion_tolerance": 1,
+      "phase_shift_tolerance": 0.1,
+      "computed_channels": [1, 18, 37, 56, 75]
+    }
+  }