docs: sync the author list from git history

I don't have a script for this because it requires some manual fixups.

Change-Id: I19f36b953c98d6bc0c09040c27b964b288360c0e

.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 "$@"

.editorconfig

@@ -1,21 +0,0 @@
-# http://editorconfig.org
-
-root = true
-
-[*]
-indent_style = space
-indent_size = 4
-trim_trailing_whitespace = true
-insert_final_newline = true
-charset = utf-8
-end_of_line = lf
-
-[*.bat]
-indent_style = tab
-end_of_line = crlf
-
-[LICENSE]
-insert_final_newline = false
-
-[Makefile]
-indent_style = tab

.github/ISSUE_TEMPLATE.md

@@ -1,15 +0,0 @@
-* gnpy version:
-* Python version:
-* Operating System:
-
-### Description
-
-Describe what you were trying to get done.
-Tell us what happened, what went wrong, and what you expected to happen.
-
-### What I Did
-
-```
-Paste the command(s) you ran and the output.
-If there was a crash, please include the traceback here.
-```

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment:**
+ - OS: [e.g. Windows]
+ - Python Version [e.g, 3.7]
+ - Anaconda Version [e.g. 3.7]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

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

.github/workflows/main.yml

@@ -0,0 +1,120 @@
+on:
+  push:
+  pull_request:
+    branches:
+      - master
+
+name: CI
+
+jobs:
+  build:
+    name: Tox test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: fedora-python/tox-github-action@v0.4
+        with:
+          tox_env: ${{ matrix.tox_env }}
+          dnf_install: ${{ matrix.dnf_install }}
+      - uses: codecov/codecov-action@v3.1.1
+        if: ${{ endswith(matrix.tox_env, '-cover') }}
+        with:
+          files: ${{ github.workspace }}/cover/coverage.xml
+    strategy:
+      fail-fast: false
+      matrix:
+        tox_env:
+          - py38
+          - py39
+          - py310
+          - py311-cover
+        include:
+          - tox_env: docs
+            dnf_install: graphviz
+
+  pypi:
+    needs: build
+    if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && github.repository_owner == 'Telecominfraproject' }}
+    name: PyPI packaging
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          python-version: '3.11'
+      - uses: casperdcl/deploy-pypi@bb869aafd89f657ceaafe9561d3b5584766c0f95
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          pip: wheel -w dist/ --no-deps .
+          upload: true
+
+  docker:
+    needs: build
+    if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) && github.repository_owner == 'Telecominfraproject' }}
+    name: Docker image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v1
+        with:
+          username: jktjkt
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Extract tag name
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        id: extract_pretty_git
+        run: echo ::set-output name=GIT_DESC::$(git describe --tags)
+      - name: Build and push a container
+        uses: docker/build-push-action@v2
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        with:
+          context: .
+          push: true
+          tags: |
+            telecominfraproject/oopt-gnpy:${{ steps.extract_pretty_git.outputs.GIT_DESC }}
+            telecominfraproject/oopt-gnpy:master
+      - name: Extract tag name
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+        id: extract_tag_name
+        run: echo ::set-output name=GIT_DESC::${GITHUB_REF/refs\/tags\//}
+      - name: Build and push a container
+        uses: docker/build-push-action@v2
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+        with:
+          context: .
+          push: true
+          tags: |
+            telecominfraproject/oopt-gnpy:${{ steps.extract_tag_name.outputs.GIT_DESC }}
+            telecominfraproject/oopt-gnpy:latest
+
+  other-platforms:
+    name: Tests on other platforms
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python_version }}
+      - run: |
+          pip install -r tests/requirements.txt
+          pip install --editable .
+          pytest -vv
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-2019
+            python_version: "3.10"
+          - os: windows-2022
+            python_version: "3.11"
+          - os: macos-12
+            python_version: "3.11"

.gitignore

@@ -2,6 +2,8 @@
 __pycache__/
 *.py[cod]
 *$py.class
+.ipynb_checkpoints
+.idea
 
 # C extensions
 *.so
@@ -60,3 +62,6 @@ target/
 
 # pyenv python configuration file
 .python-version
+
+# MacOS DS_store
+.DS_Store

.gitreview

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

.lgtm.yml

@@ -0,0 +1,3 @@
+queries:
+- exclude: py/clear-text-logging-sensitive-data
+- exclude: py/clear-text-storage-sensitive-data

.readthedocs.yml

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

.travis.yml

@@ -1,29 +0,0 @@
-# Config file for automatic testing at travis-ci.org
-# This file will be regenerated if you run travis_pypi_setup.py
-
-language: python
-python:
-  - 3.5
-  - 3.4
-  - 3.3
-  - 2.7
-  - 2.6
-
-# command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors
-install: pip install -U tox-travis
-
-# command to run tests, e.g. python setup.py test
-script: tox
-
-# After you create the Github repo and add it to Travis, run the
-# travis_pypi_setup.py script to finish PyPI deployment setup
-deploy:
-  provider: pypi
-  distributions: sdist bdist_wheel
-  user: <TBD>
-  password:
-    secure: PLEASE_REPLACE_ME
-  on:
-    tags: true
-    repo: <TBD>/gnpy
-    python: 2.7

.zuul.yaml

@@ -0,0 +1,54 @@
+---
+- project:
+    check:
+      jobs:
+        - tox-py38:
+            vars:
+              ensure_tox_version: '<4'
+        - tox-py39:
+            vars:
+              ensure_tox_version: '<4'
+        - tox-py310-cover:
+            vars:
+              ensure_tox_version: '<4'
+        - tox-docs-f36:
+            vars:
+              ensure_tox_version: '<4'
+        - coverage-diff:
+            voting: false
+            dependencies:
+              - tox-py310-cover-previous
+              - tox-py310-cover
+            vars:
+              coverage_job_name_previous: tox-py310-cover-previous
+              coverage_job_name_current: tox-py310-cover
+        - tox-linters-diff-n-report:
+            voting: false
+            vars:
+              ensure_tox_version: '<4'
+        - tox-py310-cover-previous:
+            vars:
+              ensure_tox_version: '<4'
+    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

@@ -1,13 +1,32 @@
-=======
-Credits
-=======
+gnpy is written and maintained by the Telecom Infra Project with work
+contributed by the following TIP members.
 
-Development Lead
-----------------
+To learn how to contribute, please see CONTRIBUTING.md
 
-* <TBD> <<TBD>@<TBD>.com>
+(*in alphabetical order*)
 
-Contributors
-------------
-
-None yet. Why not be the first?
+- 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>
+- Emmanuelle Delfour (Orange) <WEDE7391@orange.com>
+- Esther Le Rouzic (Orange) <esther.lerouzic@orange.com>
+- Gabriele Galimberti (Cisco) <ggalimbe@cisco.com>
+- Gert Grammel (Juniper Networks) <ggrammel@juniper.net>
+- Giacomo Borraccini (Politecnico di Torino) <giacomo.borraccini@polito.it>
+- Gilad Goldfarb (Facebook) <giladg@fb.com>
+- James Powell (Telecom Infra Project) <james.powell@telecominfraproject.com>
+- Jan Kundrát (Telecom Infra Project) <jkt@jankundrat.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>
+- Sami Alavi (NUST) <sami.mansooralavi1999@gmail.com>
+- 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>

CONTRIBUTING.rst

@@ -1,114 +0,0 @@
-.. highlight:: shell
-
-============
-Contributing
-============
-
-Contributions are welcome, and they are greatly appreciated! Every
-little bit helps, and credit will always be given.
-
-You can contribute in many ways:
-
-Types of Contributions
-----------------------
-
-Report Bugs
-~~~~~~~~~~~
-
-Report bugs at https://github.com/<TBD>/gnpy/issues.
-
-If you are reporting a bug, please include:
-
-* Your operating system name and version.
-* Any details about your local setup that might be helpful in troubleshooting.
-* Detailed steps to reproduce the bug.
-
-Fix Bugs
-~~~~~~~~
-
-Look through the GitHub issues for bugs. Anything tagged with "bug"
-and "help wanted" is open to whoever wants to implement it.
-
-Implement Features
-~~~~~~~~~~~~~~~~~~
-
-Look through the GitHub issues for features. Anything tagged with "enhancement"
-and "help wanted" is open to whoever wants to implement it.
-
-Write Documentation
-~~~~~~~~~~~~~~~~~~~
-
-gnpy could always use more documentation, whether as part of the
-official gnpy docs, in docstrings, or even on the web in blog posts,
-articles, and such.
-
-Submit Feedback
-~~~~~~~~~~~~~~~
-
-The best way to send feedback is to file an issue at https://github.com/<TBD>/gnpy/issues.
-
-If you are proposing a feature:
-
-* Explain in detail how it would work.
-* Keep the scope as narrow as possible, to make it easier to implement.
-* Remember that this is a volunteer-driven project, and that contributions
-  are welcome :)
-
-Get Started!
-------------
-
-Ready to contribute? Here's how to set up `gnpy` for local development.
-
-1. Fork the `gnpy` repo on GitHub.
-2. Clone your fork locally::
-
-    $ git clone git@github.com:your_name_here/gnpy.git
-
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
-
-    $ mkvirtualenv gnpy
-    $ cd gnpy/
-    $ python setup.py develop
-
-4. Create a branch for local development::
-
-    $ git checkout -b name-of-your-bugfix-or-feature
-
-   Now you can make your changes locally.
-
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
-
-    $ flake8 gnpy tests
-    $ python setup.py test or py.test
-    $ tox
-
-   To get flake8 and tox, just pip install them into your virtualenv.
-
-6. Commit your changes and push your branch to GitHub::
-
-    $ git add .
-    $ git commit -m "Your detailed description of your changes."
-    $ git push origin name-of-your-bugfix-or-feature
-
-7. Submit a pull request through the GitHub website.
-
-Pull Request Guidelines
------------------------
-
-Before you submit a pull request, check that it meets these guidelines:
-
-1. The pull request should include tests.
-2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check
-   https://travis-ci.org/<TBD>/gnpy/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-$ py.test tests.test_gnpy
-

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"]

HISTORY.rst

@@ -1,8 +0,0 @@
-=======
-History
-=======
-
-0.1.0 (2017-06-29)
-------------------
-
-* First release on PyPI.

LICENSE

@@ -1,31 +1,29 @@
+BSD 3-Clause License
 
-BSD License
-
-Copyright (c) 2017, <TBD>
+Copyright (c) 2018, Telecom Infra Project
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
 * Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice, this
-  list of conditions and the following disclaimer in the documentation and/or
-  other materials provided with the distribution.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
 
 * Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived from this
-  software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
-INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
-OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-OF THE POSSIBILITY OF SUCH DAMAGE.
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -1,11 +0,0 @@
-include AUTHORS.rst
-include CONTRIBUTING.rst
-include HISTORY.rst
-include LICENSE
-include README.rst
-
-recursive-include tests *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-
-recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif

Makefile

@@ -1,87 +0,0 @@
-.PHONY: clean clean-test clean-pyc clean-build docs help
-.DEFAULT_GOAL := help
-define BROWSER_PYSCRIPT
-import os, webbrowser, sys
-try:
-	from urllib import pathname2url
-except:
-	from urllib.request import pathname2url
-
-webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
-endef
-export BROWSER_PYSCRIPT
-
-define PRINT_HELP_PYSCRIPT
-import re, sys
-
-for line in sys.stdin:
-	match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
-	if match:
-		target, help = match.groups()
-		print("%-20s %s" % (target, help))
-endef
-export PRINT_HELP_PYSCRIPT
-BROWSER := python -c "$$BROWSER_PYSCRIPT"
-
-help:
-	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
-
-clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
-
-
-clean-build: ## remove build artifacts
-	rm -fr build/
-	rm -fr dist/
-	rm -fr .eggs/
-	find . -name '*.egg-info' -exec rm -fr {} +
-	find . -name '*.egg' -exec rm -f {} +
-
-clean-pyc: ## remove Python file artifacts
-	find . -name '*.pyc' -exec rm -f {} +
-	find . -name '*.pyo' -exec rm -f {} +
-	find . -name '*~' -exec rm -f {} +
-	find . -name '__pycache__' -exec rm -fr {} +
-
-clean-test: ## remove test and coverage artifacts
-	rm -fr .tox/
-	rm -f .coverage
-	rm -fr htmlcov/
-
-lint: ## check style with flake8
-	flake8 gnpy tests
-
-test: ## run tests quickly with the default Python
-	py.test
-	
-
-test-all: ## run tests on every Python version with tox
-	tox
-
-coverage: ## check code coverage quickly with the default Python
-	coverage run --source gnpy -m pytest
-	coverage report -m
-	coverage html
-	$(BROWSER) htmlcov/index.html
-
-docs: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/gnpy.rst
-	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ gnpy
-	$(MAKE) -C docs clean
-	$(MAKE) -C docs html
-	$(BROWSER) docs/_build/html/index.html
-
-servedocs: docs ## compile the docs watching for changes
-	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
-
-release: clean ## package and upload a release
-	python setup.py sdist upload
-	python setup.py bdist_wheel upload
-
-dist: clean ## builds source and wheel package
-	python setup.py sdist
-	python setup.py bdist_wheel
-	ls -l dist
-
-install: clean ## install the package to the active Python's site-packages
-	python setup.py install

README.md

@@ -0,0 +1,31 @@
+# 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)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Telecominfraproject/oopt-gnpy/main.yml)](https://github.com/Telecominfraproject/oopt-gnpy/actions/workflows/main.yml)
+[![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 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)
+[![Matrix chat](https://img.shields.io/matrix/oopt-gnpy:matrix.org)](https://matrix.to/#/%23oopt-gnpy%3Afoss.wtf?via=matrix.org&via=foss.wtf)
+
+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](https://gnpy.readthedocs.io/en/master/install.html#using-prebuilt-docker-images), or as a [Python package](https://gnpy.readthedocs.io/en/master/install.html#using-python-on-your-computer).
+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)
+
+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/), or give it a [try online at `gnpy.app`](https://gnpy.app/):
+
+[![Path propagation at gnpy.app](docs/images/2022-04-12-gnpy-app.png)](https://gnpy.app/)

README.rst

@@ -1,32 +0,0 @@
-====
-gnpy
-====
-
-
-.. image:: https://img.shields.io/pypi/v/gnpy.svg
-        :target: https://pypi.python.org/pypi/gnpy
-
-.. image:: https://img.shields.io/travis/<TBD>/gnpy.svg
-        :target: https://travis-ci.org/<TBD>/gnpy
-
-.. image:: https://readthedocs.org/projects/gnpy/badge/?version=latest
-        :target: https://gnpy.readthedocs.io/en/latest/?badge=latest
-        :alt: Documentation Status
-
-.. image:: https://pyup.io/repos/github/<TBD>/gnpy/shield.svg
-     :target: https://pyup.io/repos/github/<TBD>/gnpy/
-     :alt: Updates
-
-
-Gaussian Noise (GN) modeling library
-
-
-* Free software: BSD license
-* Documentation: https://gnpy.readthedocs.io.
-
-
-Features
---------
-
-* TODO
-

bindep.txt

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

docs/.gitignore

@@ -1,3 +0,0 @@
-/gnpy.rst
-/gnpy.*.rst
-/modules.rst

docs/Makefile

@@ -1,177 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = GNpy
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-clean:
-	rm -rf $(BUILDDIR)/*
+.PHONY: help Makefile
 
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/gnpy.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/gnpy.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/gnpy"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/gnpy"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/about-project.md

@@ -0,0 +1,59 @@
+(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)=
+## 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:jkt@jankundrat.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/authors.rst

@@ -1 +0,0 @@
-.. include:: ../AUTHORS.rst

docs/concepts.rst

@@ -0,0 +1,270 @@
+.. _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**.
+The topology is specified via :ref:`XLS files<excel>` or via :ref:`JSON<legacy-json>`.
+
+.. _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

@@ -1,8 +1,8 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # gnpy documentation build configuration file, created by
-# sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+# sphinx-quickstart on Mon Dec 18 14:41:01 2017.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -13,263 +13,182 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
 import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
 
-# If extensions (or modules to document with autodoc) are in another
-# directory, add these directories to sys.path here. If the directory is
-# relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
-# Get the project root dir, which is the parent dir of this
-cwd = os.getcwd()
-project_root = os.path.dirname(cwd)
-
-# Insert the project root dir as the first element in the PYTHONPATH.
-# This lets us ensure that the source package is imported, and that its
-# version is used.
-sys.path.insert(0, project_root)
-
-import gnpy
-
-# -- General configuration ---------------------------------------------
+# -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+#
+# needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+# 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.graphviz',
+              'myst_parser',
+              ]
+
+myst_enable_extensions = [
+    "deflist",
+    "dollarmath",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# The suffix of source filenames.
-source_suffix = '.rst'
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
 
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'gnpy'
-copyright = u"2017, <TBD>"
-
-# 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 = gnpy.__version__
-# The full version, including alpha/beta/rc tags.
-release = gnpy.__version__
+project = 'gnpy'
+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.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to
-# some non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built
-# documents.
-#keep_warnings = False
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
 
 
-# -- Options for HTML output -------------------------------------------
+# -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+#
+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,
+    }
 
-# 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
+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
 # documentation.
-#html_theme_options = {}
+#
+# html_theme_options = {}
 
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# 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 = []
 
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as
-# html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the
-# top of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon
-# of the docs.  This file should be a Windows icon file (.ico) being
-# 16x16 or 32x32 pixels large.
-#html_favicon = None
-
-# 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']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page
-# bottom, using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names
+# Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
-#html_additional_pages = {}
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+        'donate.html',
+    ]
+}
 
-# If false, no module index is generated.
-#html_domain_indices = True
 
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer.
-# Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer.
-# Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages
-# will contain a <link> tag referring to it.  The value of this option
-# must be the base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'gnpydoc'
 
 
-# -- Options for LaTeX output ------------------------------------------
+# -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    #
+    # 'papersize': 'letterpaper',
 
     # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
+    #
+    # 'pointsize': '10pt',
 
     # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', 'gnpy.tex',
-     u'gnpy Documentation',
-     u'<TBD>', 'manual'),
+    (master_doc, 'gnpy.tex', 'gnpy Documentation',
+     'Telecom Infra Project - OOPT PSE Group', 'manual'),
 ]
 
-# The name of an image file (relative to this directory) to place at
-# the top of the title page.
-#latex_logo = None
 
-# For "manual" documents, if this is true, then toplevel headings
-# are parts, not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ------------------------------------
+# -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'gnpy',
-     u'gnpy Documentation',
-     [u'<TBD>'], 1)
+    (master_doc, 'gnpy', 'gnpy Documentation',
+     [author], 1)
 ]
 
-# If true, show URL addresses after external links.
-#man_show_urls = False
 
-
-# -- Options for Texinfo output ----------------------------------------
+# -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'gnpy',
-     u'gnpy Documentation',
-     u'<TBD>',
-     'gnpy',
-     'One line description of project.',
+    (master_doc, 'gnpy', 'gnpy Documentation',
+     author, 'gnpy', 'One line description of project.',
      'Miscellaneous'),
 ]
 
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'private-members': True,
+    'show-inheritance': True,
+}
 
-# If false, no module index is generated.
-#texinfo_domain_indices = True
+graphviz_output_format = 'svg'
 
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+bibtex_bibfiles = ['biblio.bib']

docs/contributing.rst

@@ -1 +0,0 @@
-.. include:: ../CONTRIBUTING.rst

docs/excel.rst

@@ -0,0 +1,233 @@
+.. _excel:
+
+Excel (XLS, XLSX) input files
+=============================
+
+``gnpy-transmission-example`` gives the possibility to use an excel input file instead of a json file. The program then will generate the corresponding json file for you.
+
+The file named 'meshTopologyExampleV2.xls' is an example.
+
+In order to work the excel file MUST contain at least 2 sheets:
+
+- Nodes
+- Links
+
+(In progress) The File MAY contain an additional sheet:
+
+- Eqt
+- Service
+
+.. _excel-nodes-sheet:
+
+Nodes sheet
+-----------
+
+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
+
+- **City** is used for the name of a node of the graph. It accepts letters, numbers,underscore,dash, blank... (not exhaustive). The user may want to avoid commas for future CSV exports.
+
+   **City name MUST be unique** 
+
+- **Type** is not mandatory. 
+
+  - If not filled, it will be interpreted as an 'ILA' site if node degree is 2 and as a ROADM otherwise.
+  - 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.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
+-----------
+
+Links sheet must contain sixteen columns::
+
+                   <--           east cable from a to z                                   --> <--                  west from z to                                   -->
+   NodeA ; NodeZ ; Distance km ; Fiber type ; Lineic att ; Con_in ; Con_out ; PMD ; Cable Id ; Distance km ; Fiber type ; Lineic att ; Con_in ; Con_out ; PMD ; Cable Id
+
+
+Links sheets MUST contain all links between nodes defined in Nodes sheet.
+Each line represents a 'bidir link' between two nodes. The two directions are represented on a single line with "east cable from a to z" fields and "west from z to a" fields. Values for 'a to z' may be different from values from 'z to a'. 
+Since both direction of a bidir 'a-z' link are described on the same line (east and west), 'z to a' direction MUST NOT be repeated in a different line. If repeated, it will generate another parrallel bidir link between the same end nodes.
+
+
+Parameters for "east cable from a to z" and "west from z to a" are detailed in 2x7 columns. If not filled, "west from z to a" is copied from "east cable from a to z".
+
+For example, a line filled with::
+
+  node6 ; node3 ; 80 ; SSMF ; 0.2 ; 0.5 ; 0.5 ; 0.1 ; cableB ;  ;  ; 0.21 ; 0.2 ;  ;  ;  
+
+will generate a unidir fiber span from node6 to node3 with::
+ 
+  [node6 node3 80 SSMF 0.2 0.5 0.5 0.1 cableB] 
+
+and a fiber span from node3 to node6::
+
+ [node6 node3 80 SSMF 0.21 0.2 0.5 0.1 cableB] attributes. 
+
+- **NodeA** and **NodeZ** are Mandatory. 
+  They are the two endpoints of the link. They MUST contain a node name from the **City** names listed in Nodes sheet.
+
+- **Distance km** is not mandatory. 
+  It is the link length.
+
+  - 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 `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 <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. 
+
+  It is the lineic attenuation expressed in dB/km.
+  If filled it must contain positive numbers.
+  If not filled it takes "0.2" dB/km value
+
+- *Con_in*, *Con_out* are not mandatory. 
+
+  They are the connector loss in dB at ingress and egress of the fiber spans.
+  If filled they must contain positive numbers.
+  If not filled they take "0.5" dB default value.
+
+- *PMD* is not mandatory and and is not used yet. 
+
+  It is the PMD value of the link in ps.
+  If filled they must contain positive numbers.
+  If not filled, it takes "0.1" ps value.
+
+- *Cable Id* is not mandatory. 
+  If filled they must contain strings with the same constraint as "City" names. Its value is used to differenate links having the same end points. In this case different Id should be used. Cable Ids are not meant to be unique in general.
+
+
+
+
+(in progress)
+
+.. _excel-equipment-sheet:
+
+Eqpt sheet 
+----------
+
+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.
+
+This sheet contains twelve columns::
+
+                   <--           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
+
+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):
+
+::
+
+  A    - amp1
+  amp1 - amp2
+  Amp2 - B
+  A    - amp3
+  amp3 - C
+
+then Eqpt sheet should contain:
+  - one line for each ILAs: amp1, amp2, amp3 
+  - one line for each one-degree ROADM (B and C in this example)
+  - two lines for each two-degree ROADM (just the ROADM A)
+
+::
+
+  A    - amp1
+  amp1 - amp2
+  Amp2 - B
+  A    - amp3
+  amp3 - C
+  B    - amp2
+  C    - amp3
+
+
+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 $(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.
+
+
+- **Node A** is mandatory. It is the name of the node (as listed in Nodes sheet).
+  If Node A is a 'ROADM' (Type attribute in sheet Node), its number of occurence must be equal to its degree.
+  If Node A is an 'ILA' it should appear only once.
+
+- **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 <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 attenuator at input and output of amplifier (in dB).
+  If filled they must contain positive numbers.
+
+- **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 ``gnpy-path-request``.
+
+Service sheet must contain 11 columns::  
+
+   route id ; Source ; Destination ; TRX type ; Mode ; System: spacing ; System: input power (dBm) ; System: nb of channels ;  routing: disjoint from ; routing: path ; routing: is loose?
+
+- **route id** is mandatory. It must be unique. It is the identifier of the request. It can be an integer or a string (do not  use blank or dash or coma)
+
+- **Source** is mandatory. It is the name of the source node (as listed in Nodes sheet). Source MUST be a ROADM node. (TODO: relax this and accept trx entries)
+
+- **Destination** is mandatory. It is the name of the destination node (as listed in Nodes sheet). Source MUST be a ROADM node. (TODO: relax this and accept trx entries)
+
+- **TRX type** is mandatory. They are the variety type and selected mode of the transceiver to be used for the propagation simulation. These modes MUST be defined in the equipment library. The format of the mode is used as the name of the mode. (TODO: maybe add another  mode id on Transceiver library ?). In particular the mode selection defines the channel baudrate to be used for the propagation simulation.
+
+- **mode** is optional. If not specified, the program will search for the mode of the defined transponder with the highest baudrate fitting within the spacing value. 
+
+- **System: spacing** is mandatory. Spacing is the channel spacing defined in GHz difined for the feasibility propagation simulation, assuming system full load.
+
+- **System: input power (dBm) ; System: nb of channels** are optional input defining the system parameters for the propagation simulation.
+
+  - input power is the channel optical input power in dBm
+  - nb of channels is the number of channels to be used for the simulation.
+
+- **routing: disjoint from ; routing: path ; routing: is loose?** are optional.
+
+  - disjoint from: identifies the requests from which this request must be disjoint. If filled it must contain request ids separated by ' | ' 
+  - 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 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>`__ -- or just :ref:`get in touch with us directly<contributing>`.
+
+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 - G_\text{max})
+
+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/history.rst

@@ -1 +0,0 @@
-.. include:: ../HISTORY.rst

docs/index.rst

@@ -1,18 +1,22 @@
-Welcome to gnpy's documentation!
-======================================
+GNPy: Optical Route Planning Library
+=====================================================================
 
-Contents:
+`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
 
-   readme
-   installation
-   usage
-   modules
-   contributing
-   authors
-   history
+   intro
+   concepts
+   install
+   json
+   excel
+   extending
+   about-project
+   model
+   gnpy-api
 
 Indices and tables
 ==================
@@ -20,3 +24,4 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+

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.8
+
+   **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.8.0 :: 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/installation.rst

@@ -1,51 +0,0 @@
-.. highlight:: shell
-
-============
-Installation
-============
-
-
-Stable release
---------------
-
-To install gnpy, run this command in your terminal:
-
-.. code-block:: console
-
-    $ pip install gnpy
-
-This is the preferred method to install gnpy, as it will always install the most recent stable release. 
-
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
-
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
-
-
-From sources
-------------
-
-The sources for gnpy can be downloaded from the `Github repo`_.
-
-You can either clone the public repository:
-
-.. code-block:: console
-
-    $ git clone git://github.com/<TBD>/gnpy
-
-Or download the `tarball`_:
-
-.. code-block:: console
-
-    $ curl  -OL https://github.com/<TBD>/gnpy/tarball/master
-
-Once you have a copy of the source, you can install it with:
-
-.. code-block:: console
-
-    $ python setup.py install
-
-
-.. _Github repo: https://github.com/<TBD>/gnpy
-.. _tarball: https://github.com/<TBD>/gnpy/tarball/master

docs/intro.rst

@@ -0,0 +1,94 @@
+.. _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 <jkt@jankundrat.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
+
+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,620 @@
+.. _legacy-json:
+
+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}`                           |
++----------------------+-----------+------------------------------------------+
+| ``effective_area``   | (number)  | Effective area of the fiber (not just    |
+|                      |           | the MFD circle). This is the             |
+|                      |           | :math:`A_{eff}`, see e.g., the           |
+|                      |           | `Corning whitepaper on MFD/EA`_.         |
+|                      |           | Specified in :math:`m^{2}`.              |
++----------------------+-----------+------------------------------------------+
+| ``gamma``            | (number)  | Coefficient :math:`\gamma = 2\pi\times   |
+|                      |           | n^2/(\lambda*A_{eff})`.                  |
+|                      |           | If not provided, this will be derived    |
+|                      |           | from the ``effective_area``              |
+|                      |           | :math:`A_{eff}`.                         |
+|                      |           | In :math:`w^{-1} \times m^{-1}`.         |
++----------------------+-----------+------------------------------------------+
+| ``pmd_coef``         | (number)  | Polarization mode dispersion (PMD)       |
+|                      |           | coefficient. In                          |
+|                      |           | :math:`s\times\sqrt{m}^{-1}`.            |
++----------------------+-----------+------------------------------------------+
+| ``lumped_losses``    | (array)   | Places along the fiber length with extra |
+|                      |           | losses. Specified as a loss in dB at     |
+|                      |           | each relevant position (in km):          |
+|                      |           | ``{"position": 10, "loss": 1.5}``)       |
++----------------------+-----------+------------------------------------------+
+
+.. _Corning whitepaper on MFD/EA: https://www.corning.com/microsites/coc/oem/documents/specialty-fiber/WP7071-Mode-Field-Diam-and-Eff-Area.pdf
+
+RamanFiber
+~~~~~~~~~~
+
+The RamanFiber can be used to simulate Raman amplification through dedicated Raman pumps. The Raman pumps must be listed
+in the key ``raman_pumps`` within the RamanFiber ``operational`` dictionary. The description of each Raman pump must
+contain the following:
+
++---------------------------+-----------+------------------------------------------------------------+
+| field                     | type      | description                                                |
++===========================+===========+============================================================+
+| ``power``                 | (number)  | Total pump power in :math:`W`                              |
+|                           |           | considering a depolarized pump                             |
++---------------------------+-----------+------------------------------------------------------------+
+| ``frequency``             | (number)  | Pump central frequency in :math:`Hz`                       |
++---------------------------+-----------+------------------------------------------------------------+
+| ``propagation_direction`` | (number)  | The pumps can propagate in the same or opposite direction  |
+|                           |           | with respect the signal. Valid choices are ``coprop`` and  |
+|                           |           | ``counterprop``, respectively                              |
++---------------------------+-----------+------------------------------------------------------------+
+
+Beside the list of Raman pumps, the RamanFiber ``operational`` dictionary must include the ``temperature`` that affects
+the amplified spontaneous emission noise generated by the Raman amplification.
+As the loss coefficient significantly varies outside the C-band, where the Raman pumps are usually placed,
+it is suggested to include an estimation of the loss coefficient for the Raman pump central frequencies within
+a dictionary-like definition of the ``RamanFiber.params.loss_coef``
+(e.g. ``loss_coef = {"value": [0.18, 0.18, 0.20, 0.20], "frequency": [191e12, 196e12, 200e12, 210e12]}``).
+
+Transceiver
+~~~~~~~~~~~
+
+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)  | Default :ref:`equalization strategy<equalization>` |
+| or                            |           | for this ROADM type.                               |
+| ``target_psd_out_mWperGHz``   |           |                                                    |
+| or                            |           | Auto-design sets the ROADM egress channel          |
+| ``target_out_mWperSlotWidth`` |           | power. This reflects typical control loop          |
+| (mutually exclusive)          |           | algorithms that adjust ROADM losses to             |
+|                               |           | equalize channels (e.g., coming from               |
+|                               |           | different ingress direction or add ports).         |
+|                               |           |                                                    |
+|                               |           | These values are used as defaults when no          |
+|                               |           | overrides are set per each ``Roadm``               |
+|                               |           | element in the network topology.                   |
++-------------------------------+-----------+----------------------------------------------------+
+| ``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.
+
+The file ``sim_params.json`` contains the tuning parameters used within both the ``gnpy.science_utils.RamanSolver`` and
+the ``gnpy.science_utils.NliSolver`` for the evaluation of the Raman profile and the NLI generation, respectively.
+
+If amplifiers don't have settings, auto-design also sets amplifiers gain, output VOA and target powers according to [J. -L. Auge, V. Curri and E. Le Rouzic, Open Design for Multi-Vendor Optical Networks, OFC 2019](https://ieeexplore.ieee.org/document/8696699), equation 4.
+See ``delta_power_range_db`` for more explaination.
+
++---------------------------------------------+-----------+---------------------------------------------+
+| field                                       |   type    | description                                 |
++=============================================+===========+=============================================+
+| ``raman_params.flag``                       | (boolean) | Enable/Disable the Raman effect that        |
+|                                             |           | produces a power transfer from higher to    |
+|                                             |           | lower frequencies.                          |
+|                                             |           | In general, considering the Raman effect    |
+|                                             |           | provides more accurate results. It is       |
+|                                             |           | mandatory when Raman amplification is       |
+|                                             |           | included in the simulation                  |
++---------------------------------------------+-----------+---------------------------------------------+
+| ``raman_params.result_spatial_resolution``  | (number)  | Spatial resolution of the output            |
+|                                             |           | Raman profile along the entire fiber span.  |
+|                                             |           | This affects the accuracy and the           |
+|                                             |           | computational time of the NLI               |
+|                                             |           | calculation when the GGN method is used:    |
+|                                             |           | smaller the spatial resolution higher both  |
+|                                             |           | the accuracy and the computational time.    |
+|                                             |           | In C-band simulations, with input power per |
+|                                             |           | channel around 0 dBm, a suggested value of  |
+|                                             |           | spatial resolution is 10e3 m                |
++---------------------------------------------+-----------+---------------------------------------------+
+| ``raman_params.solver_spatial_resolution``  | (number)  | Spatial step for the iterative solution     |
+|                                             |           | of the first order differential equation    |
+|                                             |           | used to calculate the Raman profile         |
+|                                             |           | along the entire fiber span.                |
+|                                             |           | This affects the accuracy and the           |
+|                                             |           | computational time of the evaluated         |
+|                                             |           | Raman profile:                              |
+|                                             |           | smaller the spatial resolution higher both  |
+|                                             |           | the accuracy and the computational time.    |
+|                                             |           | In C-band simulations, with input power per |
+|                                             |           | channel around 0 dBm, a suggested value of  |
+|                                             |           | spatial resolution is 100 m                 |
++---------------------------------------------+-----------+---------------------------------------------+
+| ``nli_params.method``                       | (string)  | Model used for the NLI evaluation. Valid    |
+|                                             |           | choices are ``gn_model_analytic`` (see      |
+|                                             |           | eq. 120 from `arXiv:1209.0394               |
+|                                             |           | <https://arxiv.org/abs/1209.0394>`_) and    |
+|                                             |           | ``ggn_spectrally_separated`` (see eq. 21    |
+|                                             |           | from `arXiv:1710.02225                      |
+|                                             |           | <https://arxiv.org/abs/1710.02225>`_).      |
++---------------------------------------------+-----------+---------------------------------------------+
+| ``nli_params.computed_channels``            | (number)  | The channels on which the NLI is            |
+|                                             |           | explicitly evaluated.                       |
+|                                             |           | The NLI of the other channels is            |
+|                                             |           | interpolated using ``numpy.interp``.        |
+|                                             |           | In a C-band simulation with 96 channels in  |
+|                                             |           | a 50 GHz spacing fix-grid we recommend at   |
+|                                             |           | one computed channel every 20 channels.     |
++---------------------------------------------+-----------+---------------------------------------------+
+
+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**. In the gain mode,  |
+|                                     |           | only gain settings are used for             |
+|                                     |           | propagation, and ``delta_p`` is ignored.    |
+|                                     |           | If no ``gain_target`` is set in an          |
+|                                     |           | amplifier, auto-design computes one         |
+|                                     |           | according to the ``delta_power_range``      |
+|                                     |           | optimisation range.                         |
+|                                     |           | The gain mode                               |
+|                                     |           | is recommended if all the amplifiers        |
+|                                     |           | have already consistent gain settings in    |
+|                                     |           | the topology input file.                    |
+|                                     |           |                                             |
+|                                     |           | If true, **power mode**. In the power mode, |
+|                                     |           | only the ``delta_p`` is used for            |
+|                                     |           | propagation, and ``gain_target`` is         |
+|                                     |           | ignored.                                    |
+|                                     |           | The power mode is recommended for           |
+|                                     |           | auto-design and power sweep.                |
+|                                     |           | If no ``delta_p``  is set,                  |
+|                                     |           | auto-design sets an amplifier power target  |
+|                                     |           | according to delta_power_range_db.          |
++-------------------------------------+-----------+---------------------------------------------+
+| ``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
+~~~~~~~~~~~~~~~~~~~
+
+GNPy requires a description of all channels that are propagated through the network.
+Flexgrid channel partitioning is available since the 2.7 release via the extra ``--spectrum`` option.
+In the simplest case, homogeneous channel allocation can be defined via the ``SpectralInformation`` construct which defines a spectrum of N identical carriers:
+
++----------------------+-----------+-------------------------------------------+
+| 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 dBm.          |
+|                      |           | In gain mode                              |
+|                      |           | (see spans/power_mode = false), if no     |
+|                      |           | gain is set in an amplifier, auto-design  |
+|                      |           | sets gain to meet this reference          |
+|                      |           | power. If amplifiers gain is set,         |
+|                      |           | ``power_dbm`` is                          |
+|                      |           | ignored.                                  |
+|                      |           |                                           |
+|                      |           | In power mode, the ``power_dbm``          |
+|                      |           | is the reference power for                |
+|                      |           | the ``delta_p`` settings in amplifiers.   |
+|                      |           | It is also the reference power for        |
+|                      |           | auto-design power optimisation range      |
+|                      |           | 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.                   |
+|                      |           |                                           |
+|                      |           | If the ``--power`` CLI option is used,    |
+|                      |           | its value replaces this parameter.        |
++----------------------+-----------+-------------------------------------------+
+| ``power_range_db``   | (number)  | Power sweep excursion around              |
+|                      |           | ``power_dbm``.                            |
+|                      |           | This defines a list of reference powers   |
+|                      |           | to run the propagation, in the range      |
+|                      |           | power_range_db + power_dbm.               |
+|                      |           | Power sweep uses the ``delta_p`` targets  |
+|                      |           | or, if they have not been set, the ones   |
+|                      |           | computed by auto-design, regardless of    |
+|                      |           | of preceding amplifiers' power            |
+|                      |           | saturation.                               |
+|                      |           |                                           |
+|                      |           | Power sweep is an easy way to find the    |
+|                      |           | optimal reference power.                  |
+|                      |           |                                           |
+|                      |           | Power sweep excursion is ignored in case  |
+|                      |           | of gain mode.                             |
++----------------------+-----------+-------------------------------------------+
+| ``sys_margins``      | (number)  | In dB. Added margin on min required       |
+|                      |           | transceiver OSNR.                         |
++----------------------+-----------+-------------------------------------------+
+
+.. _mixed-rate:
+
+Arbitrary channel definition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Non-uniform channels are defined via a list of spectrum "partitions" which are defined in an extra JSON file via the ``--spectrum`` option.
+In this approach, each partition is internally homogeneous, but different partitions might use different channel widths, power targets, modulation rates, etc.
+
++----------------------+-----------+-------------------------------------------+
+| field                |   type    | description                               |
++======================+===========+===========================================+
+| ``f_min``,           | (number)  | In Hz. Mandatory.                         |
+| ``f_max``            |           | Define partition :math:`f_{min}` is       |
+|                      |           | the first carrier central frequency       |
+|                      |           | :math:`f_{max}` is the last one.          |
+|                      |           | :math:`f_{min}` -:math:`f_{max}`          |
+|                      |           | partitions must not overlap.              |
+|                      |           |                                           |
+|                      |           | Note that the meaning of ``f_min`` and    |
+|                      |           | ``f_max`` is different than the one in    |
+|                      |           | ``SpectralInformation``.                  |
++----------------------+-----------+-------------------------------------------+
+| ``baud_rate``        | (number)  | In Hz. Mandatory. Simulated baud rate.    |
++----------------------+-----------+-------------------------------------------+
+| ``slot_width``       | (number)  | In Hz. Carrier spectrum occupation.       |
+|                      |           | Carriers of this partition are spaced at  |
+|                      |           | ``slot_width`` offsets.                   |
++----------------------+-----------+-------------------------------------------+
+| ``roll_off``         | (number)  | Pure number between 0 and 1. Mandatory    |
+|                      |           | TX signal roll-off shape. Used by         |
+|                      |           | Raman-aware simulation code.              |
++----------------------+-----------+-------------------------------------------+
+| ``tx_osnr``          | (number)  | In dB. Optional. OSNR out from            |
+|                      |           | transponder. Default value is 40 dB.      |
++----------------------+-----------+-------------------------------------------+
+| ``delta_pdb``        | (number)  | In dB. Optional. Power offset compared to |
+|                      |           | the reference power used for design       |
+|                      |           | (SI block in equipment library) to be     |
+|                      |           | applied by ROADM to equalize the carriers |
+|                      |           | in this partition. Default value is 0 dB. |
++----------------------+-----------+-------------------------------------------+
+
+For example this example:
+
+.. code-block:: json
+
+ {
+   "SI":[
+     {
+       "f_min": 191.4e12,
+       "f_max":193.1e12,
+       "baud_rate": 32e9,
+       "slot_width": 50e9,
+       "roll_off": 0.15,
+       "tx_osnr": 40
+     },
+     {
+       "f_min": 193.1625e12,
+       "f_max":195e12,
+       "baud_rate": 64e9,
+       "delta_pdb": 3,
+       "slot_width": 75e9,
+       "roll_off": 0.15,
+       "tx_osnr": 40
+     }
+   ]
+ }
+
+...defines a spectrum split into two parts.
+Carriers with central frequencies ranging from 191.4 THz to 193.1 THz will have 32 GBaud rate and will be spaced by 50 Ghz.
+Carriers with central frequencies ranging from 193.1625 THz to 195 THz will have 64 GBaud rate and will be spaced by 75 GHz with 3 dB power offset.
+
+If the SI reference carrier is set to ``power_dbm`` = 0dBm, and the ROADM has ``target_pch_out_db`` set to -20 dBm, then all channels ranging from 191.4 THz to 193.1 THz will have their power equalized to -20 + 0 dBm (due to the 0 dB power offset).
+All channels ranging from 193.1625 THz to 195 THz will have their power equalized to -20 + 3 = -17 dBm (total power signal + noise).
+
+Note that first carrier of the second partition has center frequency 193.1625 THz (its spectrum occupation ranges from 193.125 THz to 193.2 THz).
+The last carrier of the second partition has center frequency 193.1 THz and spectrum occupation ranges from 193.075 THz to 193.125 THz.
+There is no overlap of the occupation and both share the same boundary.
+
+.. _equalization:
+
+Equalization choices
+~~~~~~~~~~~~~~~~~~~~
+
+ROADMs typically equalize the optical power across multiple channels using one of the available equalization strategies — either targeting a specific output power, or a specific power spectral density (PSD), or a spectfic power spectral density using slot_width as spectrum width reference (PSW).
+All of these strategies can be adjusted by a per-channel power offset.
+The equalization strategy can be defined globally per a ROADM model, or per each ROADM instance in the topology, and within a ROADM also on a per-degree basis.
+
+Let's consider some example for the equalization. Suppose that the types of signal to be propagated are the following:
+
+.. code-block:: json
+
+   {
+        "baud_rate": 32e9,
+        "f_min":191.3e12,
+        "f_max":192.3e12,
+        "spacing": 50e9,
+        "label": 1
+    },
+    {
+        "baud_rate": 64e9,
+        "f_min":193.3e12,
+        "f_max":194.3e12,
+        "spacing": 75e9,
+        "label": 2
+    }
+
+
+with the PSD equalization in a ROADM:
+
+.. code-block:: json
+
+    {
+      "uid": "roadm A",
+      "type": "Roadm",
+      "params": {
+        "target_psd_out_mWperGHz": 3.125e-4,
+      }
+    },
+
+
+This means that power out of the ROADM will be computed as 3.125e-4 * 32 = 0.01 mW ie -20 dBm for label 1 types of carriers
+and 3.125e4 * 64 = 0.02 mW ie -16.99 dBm for label2 channels. So a ratio of ~ 3 dB between target powers for these carriers.
+
+With the PSW equalization:
+
+.. code-block:: json
+
+    {
+      "uid": "roadm A",
+      "type": "Roadm",
+      "params": {
+        "target_out_mWperSlotWidth": 2.0e-4,
+      }
+    },
+
+the power out of the ROADM will be computed as 2.0e-4 * 50 = 0.01 mW ie -20 dBm for label 1 types of carriers
+and 2.0e4 * 75 = 0.015 mW ie -18.24 dBm for label2 channels. So a ratio of ~ 1.76 dB between target powers for these carriers.

docs/make.bat

@@ -1,242 +1,36 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html       to make standalone HTML files
-	echo.  dirhtml    to make HTML files named index.html in directories
-	echo.  singlehtml to make a single large HTML file
-	echo.  pickle     to make pickle files
-	echo.  json       to make JSON files
-	echo.  htmlhelp   to make HTML files and a HTML help project
-	echo.  qthelp     to make HTML files and a qthelp project
-	echo.  devhelp    to make HTML files and a Devhelp project
-	echo.  epub       to make an epub
-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  text       to make text files
-	echo.  man        to make manual pages
-	echo.  texinfo    to make Texinfo files
-	echo.  gettext    to make PO message catalogs
-	echo.  changes    to make an overview over all changed/added/deprecated items
-	echo.  xml        to make Docutils-native XML files
-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
-	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\gnpy.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\gnpy.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdf" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf
-	cd %BUILDDIR%/..
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %BUILDDIR%/..
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "text" (
-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
-
-if "%1" == "texinfo" (
-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
-	goto end
-)
-
-if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-if "%1" == "xml" (
-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The XML files are in %BUILDDIR%/xml.
-	goto end
-)
-
-if "%1" == "pseudoxml" (
-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
-	goto end
-)
-
-:end
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=GNpy
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/model.rst

@@ -0,0 +1,148 @@
+.. _physical-model:
+
+Physical Model used in GNPy
+===========================
+
+QoT-E including ASE noise and NLI accumulation 
+----------------------------------------------
+
+The operations of PSE simulative framework are based on the capability to
+estimate the QoT of one or more channels operating lightpaths over a given
+network route. For backbone transport networks, we can suppose that
+transceivers are operating polarization-division-multiplexed multilevel
+modulation formats with DSP-based coherent receivers, including equalization.
+For the optical links, we focus on state-of-the-art amplified and uncompensated
+fiber links, connecting network nodes including ROADMs, where add and drop
+operations on data traffic are performed. In such a transmission scenario, it
+is well accepted
+:cite:`vacondio_nonlinear_2012,bononi_modeling_2012,carena_modeling_2012,mecozzi_nonlinear_2012,secondini_analytical_2012,johannisson_perturbation_2013,dar_properties_2013,serena_alternative_2013,secondini_achievable_2013,poggiolini_gn-model_2014,dar_accumulation_2014,poggiolini_analytical_2011,savory_approximations_2013,bononi_single-_2013,johannisson_modeling_2014`
+to assume that transmission performances are limited by the amplified
+spontaneous emission (ASE) noise generated by optical amplifiers and and
+by nonlinear propagation effects: accumulation of a Gaussian disturbance
+defined as nonlinear interference (NLI) and generation of phase noise.
+State-of-the-art DSP in commercial transceivers are typically able to
+compensate for most of the phase noise through carrier-phase estimator
+(CPE) algorithms, for modulation formats with cardinality up to 16, per
+polarization state
+:cite:`poggiolini_recent_2017,schmidt_experimental_2015,fehenberger_experimental_2016`.
+So, for backbone networks covering medium-to-wide geographical areas, we
+can suppose that propagation is limited by the accumulation of two
+Gaussian disturbances: the ASE noise and the NLI. Additional impairments
+such as filtering effects introduced by ROADMs can be considered as
+additional equivalent power penalties depending on the ratio between the
+channel bandwidth and the ROADMs filters and the number of traversed
+ROADMs (hops) of the route under analysis. Modeling the two major
+sources of impairments as Gaussian disturbances, and being the receivers
+*coherent*, the unique QoT parameter determining the bit error rate
+(BER) for the considered transmission scenario is the generalized
+signal-to-noise ratio (SNR) defined as
+
+.. math::
+
+   {\text{SNR}}= L_F \frac{P_{\text{ch}}}{P_{\text{ASE}}+P_{\text{NLI}}} = L_F \left(\frac{1}{{\text{SNR}}_{\text{LIN}}}+\frac{1}{{\text{SNR}}_{\text{NL}}}\right)^{-1}
+
+
+where :math:`P_{\text{ch}}` is the channel power,
+:math:`P_{\text{ASE}}` and :math:`P_{\text{NLI}}` are the power levels of the disturbances 
+in the channel bandwidth for ASE noise and NLI, respectively.
+:math:`L_F` is a parameter assuming values smaller or equal than one
+that summarizes the equivalent power penalty loss such as 
+filtering effects. Note that for state-of-the art equipment, filtering
+effects can be typically neglected over routes with few hops
+:cite:`rahman_mitigation_2014,foggi_overcoming_2015`.
+
+To properly estimate :math:`P_{\text{ch}}` and :math:`P_{\text{ASE}}`
+the transmitted power at the beginning of the considered route must be
+known, and losses and amplifiers gain and noise figure, including their
+variation with frequency, must be characterized. So, the evaluation of
+:math:`{\text{SNR}}_{\text{LIN}}` *just* requires an accurate
+knowledge of equipment, which is not a trivial aspect, but it is not
+related to physical-model issues. For the evaluation of the NLI, several
+models have been proposed and validated in the technical literature
+:cite:`vacondio_nonlinear_2012,bononi_modeling_2012,carena_modeling_2012,mecozzi_nonlinear_2012,secondini_analytical_2012,johannisson_perturbation_2013,dar_properties_2013,serena_alternative_2013,secondini_achievable_2013,poggiolini_gn-model_2014,dar_accumulation_2014,poggiolini_analytical_2011,savory_approximations_2013,bononi_single-_2013,johannisson_modeling_2014`.
+The decision about which model to test within the PSE activities was
+driven by requirements of the entire PSE framework:
+
+i. the model must be *local*, i.e., related individually to each network
+element (i.e. fiber span) generating NLI, independently of preceding and
+subsequent elements; and ii. the related computational time must be compatible
+with interactive operations. 
+
+So, the choice fell on the Gaussian Noise
+(GN) model with incoherent accumulation of NLI over fiber spans
+:cite:`poggiolini_gn-model_2014`. We implemented both the
+exact GN-model evaluation of NLI based on a double integral (Eq. (11) of
+:cite:`poggiolini_gn-model_2014`) and its analytical
+approximation (Eq. (120-121) of
+:cite:`poggiolini_analytical_2011`). We performed several
+validation analyses comparing results of the two implementations with
+split-step simulations over wide bandwidths
+:cite:`pilori_ffss_2017`, and results clearly showed that
+for fiber types with chromatic dispersion roughly larger than 4
+ps/nm/km, the analytical approximation ensures an excellent accuracy
+with a computational time compatible with real-time operations.
+
+The Gaussian Noise Model to evaluate the NLI
+--------------------------------------------
+
+As previously stated, fiber propagation of multilevel modulation formats
+relying on the polarization-division-multiplexing  generates impairments that
+can be summarized as  a disturbance called nonlinear interference (NLI), when
+exploiting a DSP-based coherent receiver, as in all state-of-the-art equipment.
+From a practical point of view, the NLI can be modeled as an additive Gaussian
+random process added by each fiber span, and whose strength depends on the cube
+of the input power spectral density and on the fiber-span parameters. 
+
+Since the introduction in the market in 2007 of the first transponder based on
+such a transmission technique, the scientific community has intensively worked
+to define the propagation behavior of such a trasnmission technique.  First,
+the role of in-line chromatic dispersion compensation has been investigated,
+deducing that besides being not essential, it is indeed detrimental for
+performances :cite:`curri_dispersion_2008`.  Then, it has been observed that
+the fiber propagation impairments are practically summarized by the sole NLI,
+being all the other phenomena compensated for by the blind equalizer
+implemented in the receiver DSP :cite:`carena_statistical_2010`.  Once these
+assessments have been accepted by the community, several prestigious research
+groups have started to work on deriving analytical models able to estimating
+the NLI accumulation, and consequentially the generalized SNR that sets the
+BER, according to the transponder BER vs. SNR performance.  Many models
+delivering different levels of accuracy have been developed and validated. As
+previously clarified, for the purposes of the PSE framework, the  GN-model with
+incoherent accumulation of NLI over fiber spans has been selected as adequate.
+The reason for such a choice is first such a model being a "local" model, so
+related to each fiber spans, independently of the preceding and succeeding
+network elements. The other model characteristic driving the choice is the
+availability of a closed form for the model, so permitting a real-time
+evaluation, as required by the PSE framework.  For a detailed derivation of the
+model, please refer to :cite:`poggiolini_analytical_2011`, while a qualitative
+description can be summarized as in the following.  The GN-model assumes that
+the channel comb propagating in the fiber is well approximated by unpolarized
+spectrally shaped Gaussian noise. In such a scenario, supposing to rely - as in
+state-of-the-art equipment - on a receiver entirely compensating for linear
+propagation effects, propagation in the fiber only excites the four-wave mixing
+(FWM) process among the continuity of the tones occupying the bandwidth. Such a
+FWM generates an unpolarized complex Gaussian disturbance in each spectral slot
+that can be easily evaluated extending the FWM theory from a set of discrete
+tones - the standard FWM theory introduced back in the 90s by Inoue
+:cite:`Innoue-FWM`- to a continuity of tones, possibly spectrally shaped.
+Signals propagating in the fiber are not equivalent to Gaussian noise, but
+thanks to the absence of in-line compensation for choromatic dispersion, the
+become so, over short distances.  So, the Gaussian noise model with incoherent
+accumulation of NLI has estensively proved to be a quick yet accurate and
+conservative tool to estimate propagation impairments of fiber propagation.
+Note that the GN-model has not been derived with the aim of an *exact*
+performance estimation, but to pursue a conservative performance prediction.
+So, considering these characteristics, and the fact that the NLI is always a
+secondary effect with respect to the ASE noise accumulation, and - most
+importantly - that typically linear propagation parameters (losses, gains and
+noise figures) are known within a variation range, a QoT estimator based on the
+GN model is adequate to deliver performance predictions in terms of a
+reasonable SNR range, rather than an exact value.  As final remark, it must be
+clarified that the GN-model is adequate to be used when relying on a relatively
+narrow bandwidth up to few THz. When exceeding such a bandwidth occupation, the
+GN-model must be generalized introducing the interaction with the Stimulated
+Raman Scattering in order to give a proper estimation for all channels
+:cite:`cantono2018modeling`.  This will be the main upgrade required within the
+PSE framework.
+
+.. bibliography::

docs/readme.rst

@@ -1 +0,0 @@
-.. include:: ../README.rst

docs/requirements.txt

@@ -0,0 +1,7 @@
+alabaster>=0.7.12,<1
+docutils>=0.17.1,<1
+myst-parser>=0.16.1,<1
+Pygments>=2.11.2,<3
+rstcheck
+Sphinx>=4.4.0,<5
+sphinxcontrib-bibtex>=2.4.1,<3

docs/usage.rst

@@ -1,7 +0,0 @@
-=====
-Usage
-=====
-
-To use gnpy in a project::
-
-    import gnpy

gnpy/__init__.py

@@ -1,7 +1,8 @@
-# -*- coding: utf-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.
 
-from .gnpy import (raised_cosine_comb, analytic_formula, compute_psi, fwm_eff,
-                   get_f_computed_interp, get_freqarray, gn_analytic, gn_model,
-                   interpolate_in_range, GN_integral)
-
-__all__ = ['gnpy']
+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/__main__.py

@@ -1,75 +0,0 @@
-import gnpy as gn
-import numpy as np
-import matplotlib.pyplot as plt
-import time
-
-
-def main():
-
-    # Accuracy parameters
-    flag_analytic = True
-    num_computed_values = 2
-    interp_method = 'linear'
-    threshold_fwm = 50
-    n_points = 500
-    n_points_min = 4
-    accuracy_param = {'is_analytic': flag_analytic, 'points_not_interp': num_computed_values, 'kind_interp': interp_method,
-                      'th_fwm': threshold_fwm, 'n_points': n_points, 'n_points_min': n_points_min}
-
-    # Parallelization Parameters
-    n_cores = 1
-
-    # Spectrum parameters
-    num_ch = 95
-    rs = np.ones(num_ch) * 0.032
-    b_ch = rs            # For root raised cosine shapes, the -3 dB band is equal to the symbol rate
-    roll_off = np.ones(num_ch) * 0.05
-    power = np.ones(num_ch) * 0.001
-    central_freq = 193.5
-    if num_ch % 2 == 1:  # odd number of channels
-        fch = np.arange(-(num_ch // 2), (num_ch // 2) + 1, 1) * 0.05  # noqa: E501
-    else:
-        fch = (np.arange(0, num_ch) - (num_ch / 2.0) + 0.5) * 0.05
-    spectrum_param = {'num_ch': num_ch, 'f_ch': fch, 'b_ch': b_ch, 'roll_off': roll_off, 'power': power}
-
-    # Fiber Parameters
-    beta2 = 21.27
-    l_span = 100.0
-    loss = 0.2
-    gam = 1.27
-    fiber_param = {'alpha': loss, 'span_length': l_span, 'beta_2': beta2, 'gamma': gam}
-
-    # EDFA Parameters
-    noise_fig = 5.5
-    gain_zero = 25.0
-    gain_tilting = 0.5
-
-    # Compute the GN model
-    t = time.time()
-    nli_cmp, f_nli_cmp, nli_int, f_nli_int = gn.gn_model(spectrum_param, fiber_param, accuracy_param, n_cores)  # noqa: E501
-    print('Elapsed: %s' % (time.time() - t))
-
-    # Compute the EDFA profile
-    gain, g_ase = gn.compute_edfa_profile(gain_zero, gain_tilting, noise_fig, central_freq, fch)
-
-    # Compute the raised cosine comb
-    f1_array = np.linspace(np.amin(fch), np.amax(fch), 1e3)
-    gtx = gn.raised_cosine_comb(f1_array, rs, roll_off, fch, power)
-    gtx = gtx + 10 ** -6  # To avoid log10 issues.
-
-    # Plot the results
-    plt.figure(1)
-    plt.plot(f1_array, 10 * np.log10(gtx), '-b', label='WDM comb')
-    plt.plot(f_nli_cmp, 10 * np.log10(nli_cmp), 'ro', label='GNLI computed')
-    plt.plot(f_nli_int, 10 * np.log10(nli_int), 'g+', label='GNLI interpolated')
-    plt.plot(fch, 10 * np.log10(g_ase), 'yo', label='GASE')
-    plt.ylabel('PSD [dB(W/THz)]')
-    plt.xlabel('f [THz]')
-    plt.legend(loc='upper left')
-    plt.grid()
-    plt.draw()
-    plt.show()
-
-
-if __name__ == '__main__':
-    main()

gnpy/__main_ole__.py

@@ -1,84 +0,0 @@
-import os
-import gnpy as gn
-import numpy as np
-import matplotlib.pyplot as plt
-import time
-
-
-def main_ole():
-
-    # String indicating the folder in which outputs will be saved
-    string_date_time = time.strftime("%Y-%m-%d") + '_' + time.strftime("%H-%M-%S")
-    output_path = './output/' + string_date_time + '/'
-
-    # Creates the directory if it doesn't exist
-    if not os.path.isdir(output_path):
-        os.makedirs(output_path)
-
-    from configuration.fiber_parameters import fibers
-    from configuration.general_parameters import sys_param, control_param
-    from configuration.link_description import link
-    from input.spectrum_in import spectrum
-
-    # adapt the laser position to the grid
-    if len(spectrum['laser_position']) < sys_param['ns']:
-        n = sys_param['ns'] - len(spectrum['laser_position'])
-        missing_zeros = [0 for _ in range(n)]
-        spectrum['laser_position'] += missing_zeros
-    elif len(spectrum['laser_position']) > sys_param['ns']:
-        print('Error: the spectrum definition requires a larger number of slots ns in the spectrum grid')
-
-    delta_f = 6.25E-3
-    f_0 = sys_param['f0']
-    f_cent = f_0 + ((sys_param['ns'] // 2.0) * delta_f)
-
-    n_ch = spectrum['laser_position'].count(1)
-    # Get comb parameters
-    f_ch = np.zeros(n_ch)
-    count = 0
-    for index, bool_laser in enumerate(spectrum['laser_position']):
-        if bool_laser:
-            f_ch[count] = delta_f * index + (f_0 - f_cent)
-            count += 1
-
-    t = time.time()
-    # It runs the OLE
-    osnr_nl_db, osnr_lin_db = gn.ole(spectrum, link, fibers, sys_param, control_param, output_path=output_path)
-    print('Elapsed: %s' % (time.time() - t))
-
-    # Compute the raised cosine comb
-    power, rs, roll_off, p_ase, p_nli, n_ch = gn.get_spectrum_param(spectrum)
-    f1_array = np.linspace(np.amin(f_ch), np.amax(f_ch), 1e3)
-    gtx = gn.raised_cosine_comb(f1_array, rs, roll_off, f_ch, power)
-    gtx = gtx + 10 ** -6  # To avoid log10 issues.
-
-    # OSNR at in the central channel
-    ind_c = n_ch // 2
-    osnr_lin_central_db = osnr_lin_db[ind_c]
-    osnr_nl_central_db = osnr_nl_db[ind_c]
-    print('The linear OSNR in the central channel is: ' + str(osnr_lin_central_db) + ' dB')
-    print('The non linear OSNR in the central channel is: ' + str(osnr_nl_central_db) + ' dB')
-
-    # Plot the results
-    plt.figure(1)
-    plt.plot(f1_array, 10 * np.log10(gtx), '-b', label='WDM comb PSD [dB(W/THz)]')
-    plt.plot(f_ch, 10 * np.log10(p_nli), 'ro', label='NLI [dBw]')
-    plt.plot(f_ch, 10 * np.log10(p_ase), 'g+', label='ASE noise [dBw]')
-    plt.ylabel('')
-    plt.xlabel('f [THz]')
-    plt.legend(loc='upper right')
-    plt.grid()
-    plt.draw()
-
-    plt.figure(2)
-    plt.plot(f_ch, osnr_nl_db, 'ro', label='non-linear OSNR')
-    plt.plot(f_ch, osnr_lin_db, 'g+', label='linear OSNR')
-    plt.ylabel('OSNR [dB]')
-    plt.xlabel('f [THz]')
-    plt.legend(loc='lower left')
-    plt.grid()
-    plt.show()
-
-
-if __name__ == '__main__':
-    main_ole()

gnpy/cli.py

@@ -1,17 +0,0 @@
-# -*- coding: utf-8 -*-
-
-"""Console script for gnpy."""
-
-import click
-
-
-@click.command()
-def main(args=None):
-    """Console script for gnpy."""
-    click.echo("Replace this message by putting your code into "
-               "gnpy.cli.main")
-    click.echo("See click documentation at http://click.pocoo.org/")
-
-
-if __name__ == "__main__":
-    main()

gnpy/configuration/__init__.py

@@ -1 +0,0 @@
- 

gnpy/configuration/fiber_parameters.py

@@ -1,32 +0,0 @@
-# coding=utf-8
-""" fiber_parameters.py describes the fiber parameters.
-    fibers is a dictionary containing a dictionary for each kind of fiber
-    each dictionary has to report:
-        reference_frequency: the frequency at which the parameters are evaluated [THz]
-        alpha: the attenuation coefficient [dB/km]
-        alpha_1st: the first derivative of alpha indicating the alpha slope [dB/km/THz]
-                if you assume a flat attenuation with respect to the frequency you put it as zero
-        beta_2: the dispersion coefficient [ps^2/km]
-        n_2: second-order nonlinear refractive index [m^2/W]
-            a typical value is 2.5E-20 m^2/W
-        a_eff: the effective area of the fiber [um^2]
-"""
-
-fibers = {
-    'SMF': {
-        'reference_frequency': 193.5,
-        'alpha': 0.2,
-        'alpha_1st': 0,
-        'beta_2': 21.27,
-        'n_2': 2.5E-20,
-        'a_eff': 77.77,
-    },
-    'NZDF': {
-        'reference_frequency': 193.5,
-        'alpha': 0.22,
-        'alpha_1st': 0,
-        'beta_2': 21,
-        'n_2': 2.5E-20,
-        'a_eff': 70,
-    }
-}

gnpy/configuration/general_parameters.py

@@ -1,40 +0,0 @@
-# -*- coding: utf-8 -*
-"""general_parameters.py contains the general configuration settings
-
-    The sectings are subdivided in two dictionaries:
-        sys_param: a dictionary containing the general system parameters:
-            f0: the starting frequency of the laser grid used to describe the WDM system [THz]
-            ns: the number of 6.25 GHz slots in the grid
-
-        control_param:
-            save_each_comp: a boolean flag. If true, it saves in output folder one spectrum file at the output of each
-                            component, otherwise it saves just the last spectrum
-            is_linear: a bool flag. If true, is doesn't compute NLI, if false, OLE will consider NLI
-            is_analytic: a boolean flag. If true, the NLI is computed through the analytic formula, otherwise it uses
-                the double integral. Warning: the double integral is very slow.
-            points_not_interp: if the double integral is used, it indicates how much points are calculated, others will
-                be interpolated
-            kind_interp: a string indicating the interpolation method for the double integral
-            th_fwm: the threshold of the four wave mixing efficiency for the double integral
-            n_points: number of points in which the double integral is computed in the high FWM efficiency region
-            n_points_min: number of points in which the double integral is computed in the low FWM efficiency region
-            n_cores: number of cores for parallel computation [not yet implemented]
-"""
-# System parameters
-sys_param = {
-    'f0': 192.075,
-    'ns': 328
-}
-
-# control parameters
-control_param = {
-    'save_each_comp': True,
-    'is_linear': False,
-    'is_analytic': True,
-    'points_not_interp': 2,
-    'kind_interp': 'linear',
-    'th_fwm': 50,
-    'n_points': 500,
-    'n_points_min': 4,
-    'n_cores': 1
-}

gnpy/configuration/link_description.py

@@ -1,59 +0,0 @@
-# coding=utf-8
-""" link_description.py contains the full description of that OLE has to emulate.
-    It contains a list of dictionaries, following the structure of the link and each element of the list describes one
-    component.
-
-    'comp_cat': the kind of link component:
-        PC: a passive component defined by a loss at a certain frequency and a loss tilt
-        OA: an optical amplifier defined by a gain at a certain frequency, a gain tilt and a noise figure
-        fiber: a span of fiber described by the type and the length
-    'comp_id': is an id identifying the component. It has to be unique for each component!
-
-    extra fields for PC:
-        'ref_freq': the frequency at which the 'loss' parameter is evaluated [THz]
-        'loss': the loss at the frequency 'ref_freq' [dB]
-        'loss_tlt': the frequency dependent loss [dB/THz]
-    extra fields for OA:
-        'ref_freq': the frequency at which the 'gain' parameter is evaluated [THz]
-        'gain': the gain at the frequency 'ref_freq' [dB]
-        'gain_tlt': the frequency dependent gain [dB/THz]
-        'noise_figure': the noise figure of the optical amplifier [dB]
-    extra fields for fiber:
-        'fiber_type': a string calling the type of fiber described in the file fiber_parameters.py
-        'length': the fiber length [km]
-
-"""
-smf = {
-    'comp_cat': 'fiber',
-    'comp_id': '',
-    'fiber_type': 'SMF',
-    'length': 100
-    }
-
-oa = {
-    'comp_cat': 'OA',
-    'comp_id': '',
-    'ref_freq': 193.5,
-    'gain': 20,
-    'gain_tlt': 0.0,
-    'noise_figure': 5
-    }
-
-pc = {
-    'comp_cat': 'PC',
-    'comp_id': '04',
-    'ref_freq': 193.,
-    'loss': 2.0,
-    'loss_tlt': 0.0
-    }
-
-link = []
-
-for index in range(20):
-    smf['comp_id'] = '%03d' % (2 * index)
-    oa['comp_id'] = '%03d' % (2 * index + 1)
-    link += [dict(smf)]
-    link += [dict(oa)]
-
-pc['comp_id'] = '%03d' % 40
-link += [dict(pc)]

gnpy/core/__init__.py

@@ -0,0 +1,9 @@
+'''
+Simulation of signal propagation in the DWDM network
+
+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`.
+'''

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/equipment.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.core.equipment
+===================
+
+This module contains functionality for specifying equipment.
+'''
+
+from gnpy.core.utils import automatic_nch, db2lin
+from gnpy.core.exceptions import EquipmentConfigError
+
+
+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 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)
+            trx_params = {**mode_params}
+            # sanity check: spacing baudrate must be smaller than min spacing
+            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,
+                           "penalties": 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'])
+        # temp = trx_params['spacing']
+        # print(f'spacing {temp}')
+    except StopIteration:
+        if error_message:
+            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
+            trx_params['f_min'] = default_si_data.f_min
+            trx_params['f_max'] = default_si_data.f_max
+            trx_params['baud_rate'] = default_si_data.baud_rate
+            trx_params['spacing'] = default_si_data.spacing
+            trx_params['OSNR'] = None
+            trx_params['penalties'] = {}
+            trx_params['bit_rate'] = None
+            trx_params['cost'] = None
+            trx_params['roll_off'] = default_si_data.roll_off
+            trx_params['tx_osnr'] = default_si_data.tx_osnr
+            trx_params['min_spacing'] = None
+
+    trx_params['power'] = db2lin(default_si_data.power_dbm) * 1e-3
+
+    return trx_params

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/info.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.core.info
+==============
+
+This module contains classes for modelling :class:`SpectralInformation`.
+"""
+
+from __future__ import annotations
+from collections import namedtuple
+from collections.abc import Iterable
+from typing import Union
+from dataclasses import dataclass
+from numpy import argsort, mean, array, append, ones, ceil, any, zeros, outer, full, ndarray, asarray
+
+from gnpy.core.utils import automatic_nch, db2lin, watt2dbm
+from gnpy.core.exceptions import SpectrumError
+
+DEFAULT_SLOT_WIDTH_STEP = 12.5e9  # Hz
+"""Channels with unspecified slot width will have their slot width evaluated as the baud rate rounded up to the minimum
+multiple of the DEFAULT_SLOT_WIDTH_STEP (the baud rate is extended including the roll off in this evaluation)"""
+
+
+class Power(namedtuple('Power', 'signal nli ase')):
+    """carriers power in W"""
+
+
+class Channel(namedtuple('Channel',
+                         'channel_number frequency baud_rate slot_width roll_off power chromatic_dispersion pmd pdl')):
+    """ Class containing the parameters of a WDM signal.
+        :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 slot_width: the slot width (Hz)
+        :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)
+        :param pdl: polarization dependent loss (dB)
+    """
+
+
+class Pref(namedtuple('Pref', 'p_span0, p_spani, ref_carrier')):
+    """noiseless reference power in dBm:
+    p_span0: inital target carrier power for a reference channel defined by user
+    p_spani: carrier power after element i for a reference channel defined by user
+    ref_carrier records the baud rate of the reference channel
+    """
+
+
+class SpectralInformation(object):
+    """ Class containing the parameters of the entire WDM comb.
+    delta_pdb_per_channel: (per frequency) per channel delta power in dbm for the actual mix of channels"""
+
+    def __init__(self, frequency: array, baud_rate: array, slot_width: array, signal: array, nli: array, ase: array,
+                 roll_off: array, chromatic_dispersion: array, pmd: array, pdl: array, delta_pdb_per_channel: array,
+                 tx_osnr: array, ref_power: Pref, label: array):
+        indices = argsort(frequency)
+        self._frequency = frequency[indices]
+        self._df = outer(ones(frequency.shape), frequency) - outer(frequency, ones(frequency.shape))
+        self._number_of_channels = len(self._frequency)
+        self._channel_number = [*range(1, self._number_of_channels + 1)]
+        self._slot_width = slot_width[indices]
+        self._baud_rate = baud_rate[indices]
+        overlap = self._frequency[:-1] + self._slot_width[:-1] / 2 > self._frequency[1:] - self._slot_width[1:] / 2
+        if any(overlap):
+            overlap = [pair for pair in zip(overlap * self._channel_number[:-1], overlap * self._channel_number[1:])
+                       if pair != (0, 0)]
+            raise SpectrumError(f'Spectrum required slot widths larger than the frequency spectral distances '
+                                f'between channels: {overlap}.')
+        exceed = self._baud_rate > self._slot_width
+        if any(exceed):
+            raise SpectrumError(f'Spectrum baud rate, including the roll off, larger than the slot width for channels: '
+                                f'{[ch for ch in exceed * self._channel_number if ch]}.')
+        self._signal = signal[indices]
+        self._nli = nli[indices]
+        self._ase = ase[indices]
+        self._roll_off = roll_off[indices]
+        self._chromatic_dispersion = chromatic_dispersion[indices]
+        self._pmd = pmd[indices]
+        self._pdl = pdl[indices]
+        self._delta_pdb_per_channel = delta_pdb_per_channel[indices]
+        self._tx_osnr = tx_osnr[indices]
+        self._pref = ref_power
+        self._label = label[indices]
+
+    @property
+    def pref(self):
+        """Instance of gnpy.info.Pref"""
+        return self._pref
+
+    @pref.setter
+    def pref(self, pref: Pref):
+        self._pref = pref
+
+    @property
+    def frequency(self):
+        return self._frequency
+
+    @property
+    def df(self):
+        """Matrix of relative frequency distances between all channels. Positive elements in the upper right side."""
+        return self._df
+
+    @property
+    def slot_width(self):
+        return self._slot_width
+
+    @property
+    def baud_rate(self):
+        return self._baud_rate
+
+    @property
+    def number_of_channels(self):
+        return self._number_of_channels
+
+    @property
+    def powers(self):
+        powers = zip(self.signal, self.nli, self.ase)
+        return [Power(*p) for p in powers]
+
+    @property
+    def signal(self):
+        return self._signal
+
+    @signal.setter
+    def signal(self, signal):
+        self._signal = signal
+
+    @property
+    def nli(self):
+        return self._nli
+
+    @nli.setter
+    def nli(self, nli):
+        self._nli = nli
+
+    @property
+    def ase(self):
+        return self._ase
+
+    @ase.setter
+    def ase(self, ase):
+        self._ase = ase
+
+    @property
+    def roll_off(self):
+        return self._roll_off
+
+    @property
+    def chromatic_dispersion(self):
+        return self._chromatic_dispersion
+
+    @chromatic_dispersion.setter
+    def chromatic_dispersion(self, chromatic_dispersion):
+        self._chromatic_dispersion = chromatic_dispersion
+
+    @property
+    def pmd(self):
+        return self._pmd
+
+    @property
+    def label(self):
+        return self._label
+
+    @pmd.setter
+    def pmd(self, pmd):
+        self._pmd = pmd
+
+    @property
+    def pdl(self):
+        return self._pdl
+
+    @pdl.setter
+    def pdl(self, pdl):
+        self._pdl = pdl
+
+    @property
+    def delta_pdb_per_channel(self):
+        return self._delta_pdb_per_channel
+
+    @delta_pdb_per_channel.setter
+    def delta_pdb_per_channel(self, delta_pdb_per_channel):
+        self._delta_pdb_per_channel = delta_pdb_per_channel
+
+    @property
+    def tx_osnr(self):
+        return self._tx_osnr
+
+    @tx_osnr.setter
+    def tx_osnr(self, tx_osnr):
+        self._tx_osnr = tx_osnr
+
+    @property
+    def channel_number(self):
+        return self._channel_number
+
+    @property
+    def carriers(self):
+        entries = zip(self.channel_number, self.frequency, self.baud_rate, self.slot_width,
+                      self.roll_off, self.powers, self.chromatic_dispersion, self.pmd, self.pdl)
+        return [Channel(*entry) for entry in entries]
+
+    def apply_attenuation_lin(self, attenuation_lin):
+        self.signal *= attenuation_lin
+        self.nli *= attenuation_lin
+        self.ase *= attenuation_lin
+
+    def apply_attenuation_db(self, attenuation_db):
+        attenuation_lin = 1 / db2lin(attenuation_db)
+        self.apply_attenuation_lin(attenuation_lin)
+
+    def apply_gain_lin(self, gain_lin):
+        self.signal *= gain_lin
+        self.nli *= gain_lin
+        self.ase *= gain_lin
+
+    def apply_gain_db(self, gain_db):
+        gain_lin = db2lin(gain_db)
+        self.apply_gain_lin(gain_lin)
+
+    def __add__(self, other: SpectralInformation):
+        try:
+            # Note that pref.p_spanx from "self" and "other" must be identical for a given simulation (correspond to the
+            # the simulation setup):
+            # - for a given simulation there is only one design (one p_span0),
+            # - and p_spani is the propagation result of p_span0 so there should not be different p_spani either.
+            if (self.pref.p_span0 != other.pref.p_span0) or (self.pref.p_spani != other.pref.p_spani):
+                raise SpectrumError('reference powers of the spectrum are not identical')
+            return SpectralInformation(frequency=append(self.frequency, other.frequency),
+                                       slot_width=append(self.slot_width, other.slot_width),
+                                       signal=append(self.signal, other.signal), nli=append(self.nli, other.nli),
+                                       ase=append(self.ase, other.ase),
+                                       baud_rate=append(self.baud_rate, other.baud_rate),
+                                       roll_off=append(self.roll_off, other.roll_off),
+                                       chromatic_dispersion=append(self.chromatic_dispersion,
+                                                                   other.chromatic_dispersion),
+                                       pmd=append(self.pmd, other.pmd),
+                                       pdl=append(self.pdl, other.pdl),
+                                       delta_pdb_per_channel=append(self.delta_pdb_per_channel,
+                                                                    other.delta_pdb_per_channel),
+                                       tx_osnr=append(self.tx_osnr, other.tx_osnr),
+                                       ref_power=Pref(self.pref.p_span0, self.pref.p_spani, self.pref.ref_carrier),
+                                       label=append(self.label, other.label))
+        except SpectrumError:
+            raise SpectrumError('Spectra cannot be summed: channels overlapping.')
+
+
+    def _replace(self, carriers, pref):
+        self.chromatic_dispersion = array([c.chromatic_dispersion for c in carriers])
+        self.pmd = array([c.pmd for c in carriers])
+        self.pdl = array([c.pdl for c in carriers])
+        self.signal = array([c.power.signal for c in carriers])
+        self.nli = array([c.power.nli for c in carriers])
+        self.ase = array([c.power.ase for c in carriers])
+        self.pref = pref
+        return self
+
+
+def create_arbitrary_spectral_information(frequency: Union[ndarray, Iterable, float],
+                                          signal: Union[float, ndarray, Iterable],
+                                          baud_rate: Union[float, ndarray, Iterable],
+                                          tx_osnr: Union[float, ndarray, Iterable],
+                                          delta_pdb_per_channel: Union[float, ndarray, Iterable] = 0.,
+                                          slot_width: Union[float, ndarray, Iterable] = None,
+                                          roll_off: Union[float, ndarray, Iterable] = 0.,
+                                          chromatic_dispersion: Union[float, ndarray, Iterable] = 0.,
+                                          pmd: Union[float, ndarray, Iterable] = 0.,
+                                          pdl: Union[float, ndarray, Iterable] = 0.,
+                                          ref_power: Pref = None,
+                                          label: Union[str, ndarray, Iterable] = None):
+    """This is just a wrapper around the SpectralInformation.__init__() that simplifies the creation of
+    a non-uniform spectral information with NLI and ASE powers set to zero."""
+    frequency = asarray(frequency)
+    number_of_channels = frequency.size
+    try:
+        signal = full(number_of_channels, signal)
+        baud_rate = full(number_of_channels, baud_rate)
+        roll_off = full(number_of_channels, roll_off)
+        slot_width = full(number_of_channels, slot_width) if slot_width is not None else \
+            ceil((1 + roll_off) * baud_rate / DEFAULT_SLOT_WIDTH_STEP) * DEFAULT_SLOT_WIDTH_STEP
+        chromatic_dispersion = full(number_of_channels, chromatic_dispersion)
+        pmd = full(number_of_channels, pmd)
+        pdl = full(number_of_channels, pdl)
+        nli = zeros(number_of_channels)
+        ase = zeros(number_of_channels)
+        delta_pdb_per_channel = full(number_of_channels, delta_pdb_per_channel)
+        tx_osnr = full(number_of_channels, tx_osnr)
+        label = full(number_of_channels, label)
+        return SpectralInformation(frequency=frequency, slot_width=slot_width,
+                                   signal=signal, nli=nli, ase=ase,
+                                   baud_rate=baud_rate, roll_off=roll_off,
+                                   chromatic_dispersion=chromatic_dispersion,
+                                   pmd=pmd, pdl=pdl,
+                                   delta_pdb_per_channel=delta_pdb_per_channel,
+                                   tx_osnr=tx_osnr,
+                                   ref_power=ref_power, label=label)
+    except ValueError as e:
+        if 'could not broadcast' in str(e):
+            raise SpectrumError('Dimension mismatch in input fields.')
+        else:
+            raise
+
+
+def create_input_spectral_information(f_min, f_max, roll_off, baud_rate, power, spacing, tx_osnr, ref_carrier=None):
+    """ Creates a fixed slot width spectral information with flat power.
+    all arguments are scalar values"""
+    number_of_channels = automatic_nch(f_min, f_max, spacing)
+    frequency = [(f_min + spacing * i) for i in range(1, number_of_channels + 1)]
+    p_span0 = watt2dbm(power)
+    p_spani = watt2dbm(power)
+    delta_pdb_per_channel = zeros(number_of_channels)
+    label = [f'{baud_rate * 1e-9 :.2f}G' for i in range(number_of_channels)]
+    return create_arbitrary_spectral_information(frequency, slot_width=spacing, signal=power, baud_rate=baud_rate,
+                                                 roll_off=roll_off, delta_pdb_per_channel=delta_pdb_per_channel,
+                                                 tx_osnr=tx_osnr,
+                                                 ref_power=Pref(p_span0=p_span0, p_spani=p_spani,
+                                                                ref_carrier=ref_carrier),
+                                                 label=label)
+
+
+def carriers_to_spectral_information(initial_spectrum: dict[float, Carrier], power: float,
+                                     ref_carrier: ReferenceCarrier) -> SpectralInformation:
+    """Initial spectrum is a dict with key = carrier frequency, and value a Carrier object.
+    :param initial_spectrum: indexed by frequency in Hz, with power offset (delta_pdb), baudrate, slot width,
+    tx_osnr and roll off.
+    :param power: power of the request
+    :param ref_carrier: reference carrier (baudrate) used for the reference channel
+    """
+    frequency = list(initial_spectrum.keys())
+    signal = [power * db2lin(c.delta_pdb) for c in initial_spectrum.values()]
+    roll_off = [c.roll_off for c in initial_spectrum.values()]
+    baud_rate = [c.baud_rate for c in initial_spectrum.values()]
+    delta_pdb_per_channel = [c.delta_pdb for c in initial_spectrum.values()]
+    slot_width = [c.slot_width for c in initial_spectrum.values()]
+    tx_osnr = [c.tx_osnr for c in initial_spectrum.values()]
+    label = [c.label for c in initial_spectrum.values()]
+    p_span0 = watt2dbm(power)
+    p_spani = watt2dbm(power)
+    return create_arbitrary_spectral_information(frequency=frequency, signal=signal, baud_rate=baud_rate,
+                                                 slot_width=slot_width, roll_off=roll_off,
+                                                 delta_pdb_per_channel=delta_pdb_per_channel, tx_osnr=tx_osnr,
+                                                 ref_power=Pref(p_span0=p_span0, p_spani=p_spani,
+                                                                ref_carrier=ref_carrier),
+                                                 label=label)
+
+
+@dataclass
+class Carrier:
+    """One channel in the initial mixed-type spectrum definition, each type being defined by
+    its delta_pdb (power offset with respect to reference power), baud rate, slot_width, roll_off
+    and tx_osnr. delta_pdb offset is applied to target power out of Roadm.
+    Label is used to group carriers which belong to the same partition when printing results.
+    """
+    delta_pdb: float
+    baud_rate: float
+    slot_width: float
+    roll_off: float
+    tx_osnr: float
+    label: str
+
+
+@dataclass
+class ReferenceCarrier:
+    """Reference channel type is used to determine target power out of ROADM for the reference channel when
+    constant power spectral density (PSD) equalization is set. Reference channel is the type that has been defined
+    in SI block and used for the initial design of the network.
+    Computing the power out of ROADM for the reference channel is required to correctly compute the loss
+    experienced by p_span_i in Roadm element.
+
+    Baud rate is required to find the target power in constant PSD: power = PSD_target * baud_rate.
+    For example, if target PSD is 3.125e4mW/GHz and reference carrier type a 32 GBaud channel then
+    output power should be -20 dBm and for a 64 GBaud channel power target would need 3 dB more: -17 dBm.
+
+    Slot width is required to find the target power in constant PSW (constant power per slot width equalization):
+    power = PSW_target * slot_width.
+    For example, if target PSW is 2e4mW/GHz and reference carrier type a 32 GBaud channel in a 50GHz slot width then
+    output power should be -20 dBm and for a 64 GBaud channel  in a 75 GHz slot width, power target would be -18.24 dBm.
+
+    Other attributes (like slot_width or roll-off) may be added there for future equalization purpose.
+    """
+    baud_rate: float
+    slot_width: float

gnpy/core/network.py

@@ -0,0 +1,574 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+'''
+gnpy.core.network
+=================
+
+Working with networks which consist of network elements
+'''
+
+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 gnpy.core.info import ReferenceCarrier
+from collections import namedtuple
+
+
+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
+        }
+    )
+    amp.pin_db = 0
+    amp.nch = 88
+    amp.slot_width = 50e9
+    return amp._calc_nf(True)
+
+
+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_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
+
+    # create 2 list of available amplifiers with relevant attributes for their selection
+
+    # 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(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:
+    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 target_power(network, node, equipment):  # get_fiber_dp
+    if isinstance(node, elements.Roadm):
+        return 0
+
+    SPAN_LOSS_REF = 20
+    POWER_SLOPE = 0.3
+    dp_range = list(equipment['Span']['default'].delta_power_range_db)
+    node_loss = span_loss(network, node)
+
+    try:
+        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 either Fused or Fibers succeeded by Fused"""
+    try:
+        prev_node = next(network.predecessors(node))
+    except StopIteration:
+        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)
+
+
+def next_node_generator(network, node):
+    """fused spans interest:
+    iterate over all predecessors while they are either Fused or Fibers preceded by Fused"""
+    try:
+        next_node = next(network.successors(node))
+    except StopIteration:
+        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)
+
+
+def span_loss(network, node):
+    """Total loss of a span (Fiber and Fused nodes) which contains the given node"""
+    loss = node.loss if node.passive else 0
+    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
+    (aka no amp in between)"""
+    this_node = node
+    for this_node in prev_node_generator(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
+    (aka no amp in between)"""
+    this_node = node
+    for this_node in next_node_generator(network, node):
+        pass
+    return this_node
+
+
+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
+    ref_carrier = ReferenceCarrier(baud_rate=equipment['SI']['default'].baud_rate,
+                                   slot_width=equipment['SI']['default'].spacing)
+    next_oms = (n for n in network.successors(this_node) if not isinstance(n, elements.Transceiver))
+    for oms in next_oms:
+        # go through all the OMS departing from the ROADM
+        prev_node = this_node
+        node = oms
+        if isinstance(this_node, elements.Transceiver):
+            this_node_out_power = 0.0     # default value if this_node is a transceiver
+        if isinstance(this_node, elements.Roadm):
+            # get target power out from ROADM for the reference carrier based on equalization settings
+            this_node_out_power = this_node.get_per_degree_ref_power(degree=node.uid, ref_carrier=ref_carrier)
+        # use the target power on this degree
+        prev_dp = this_node_out_power - 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)
+                voa = node.out_voa if node.out_voa else 0
+                if node.delta_p is None:
+                    dp = target_power(network, next_node, equipment) + voa
+                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
+
+                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 * 1e-3  # dB/m
+                    raman_allowed = prev_node.params.loss_coef < max_fiber_lineic_loss_for_raman
+                else:
+                    raman_allowed = False
+
+                if node.params.type_variety == '':
+                    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.__dict__)
+                    dp += power_reduction
+                    gain_target += power_reduction
+                else:
+                    if node.params.raman and not raman_allowed:
+                        if isinstance(prev_node, elements.Fiber):
+                            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:
+                            print(f'{ansi_escapes.red}WARNING{ansi_escapes.reset}: raman is used in node {node.uid}\n '
+                                  'but previous node is not a fiber\n')
+                    # 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
+
+
+def set_roadm_per_degree_targets(roadm, network):
+    """Set target powers/PSD on all degrees
+    This is needed to populate per_degree_pch_out_dbm or per_degree_pch_psd or per_degree_pch_psw dicts when
+    they are not initialized by users.
+    """
+    next_oms = (n for n in network.successors(roadm) if not isinstance(n, elements.Transceiver))
+
+    for node in next_oms:
+        # go through all the OMS departing from the ROADM
+        if node.uid not in roadm.per_degree_pch_out_dbm and node.uid not in roadm.per_degree_pch_psd and \
+                node.uid not in roadm.per_degree_pch_psw:
+            # if no target power is defined on this degree or no per degree target power is given use the global one
+            if roadm.params.target_pch_out_db:
+                roadm.per_degree_pch_out_dbm[node.uid] = roadm.params.target_pch_out_db
+            elif roadm.params.target_psd_out_mWperGHz:
+                roadm.per_degree_pch_psd[node.uid] = roadm.params.target_psd_out_mWperGHz
+            elif roadm.params.target_out_mWperSlotWidth:
+                roadm.per_degree_pch_psw[node.uid] = roadm.params.target_out_mWperSlotWidth
+            else:
+                raise ConfigurationError(roadm.uid, 'needs an equalization target')
+
+
+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(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_spans2 = int(fiber_length // target_length)
+    n_spans1 = n_spans2 + 1
+
+    length1 = fiber_length / n_spans1
+    length2 = fiber_length / n_spans2
+
+    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 length2 - target_length <= target_length - length1 and length2 <= bounds.stop:
+        return (length2, n_spans2)
+    else:
+        return (length1, n_spans1)
+
+
+def split_fiber(network, fiber, bounds, target_length, equipment):
+    new_length, n_spans = calculate_new_length(fiber.params.length, bounds, target_length)
+    if n_spans == 1:
+        return
+
+    try:
+        next_node = next(network.successors(fiber))
+        prev_node = next(network.predecessors(fiber))
+    except StopIteration:
+        raise NetworkTopologyError(f'Fiber {fiber.uid} is not properly connected, please check network topology')
+
+    network.remove_node(fiber)
+
+    fiber.params.length = new_length
+
+    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 = 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:
+            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_connector_loss(network, fibers, default_con_in, default_con_out, EOL):
+    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 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)
+            # 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, no_insert_edfas=False):
+    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, min(max_length, 90_000))
+
+    # 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)
+    # don't group split fiber and add amp in the same loop
+    # =>for code clarity (at the expense of speed):
+
+    roadms = [r for r in network.nodes() if isinstance(r, elements.Roadm)]
+
+    if not no_insert_edfas:
+        for fiber in fibers:
+            split_fiber(network, fiber, bounds, target_length, equipment)
+
+        for roadm in roadms:
+            add_roadm_preamp(network, roadm)
+            add_roadm_booster(network, roadm)
+
+        fibers = [f for f in network.nodes() if isinstance(f, elements.Fiber)]
+        for fiber in fibers:
+            add_inline_amplifier(network, fiber)
+
+    add_fiber_padding(network, fibers, default_span_data.padding)
+
+    for roadm in roadms:
+        set_roadm_per_degree_targets(roadm, network)
+        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/parameters.py

@@ -0,0 +1,323 @@
+#!/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 asarray, array
+
+from gnpy.core.utils import 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.lower()
+
+
+class RamanParams(Parameters):
+    def __init__(self, flag=False, result_spatial_resolution=10e3, solver_spatial_resolution=50):
+        """ Simulation parameters used within the Raman Solver
+        :params flag: boolean for enabling/disable the evaluation of the Raman power profile in frequency and position
+        :params result_spatial_resolution: spatial resolution of the evaluated Raman power profile
+        :params solver_spatial_resolution: spatial step for the iterative solution of the first order ode
+        """
+        self.flag = flag
+        self.result_spatial_resolution = result_spatial_resolution  # [m]
+        self.solver_spatial_resolution = solver_spatial_resolution  # [m]
+
+
+class NLIParams(Parameters):
+    def __init__(self, method='gn_model_analytic', dispersion_tolerance=1, phase_shift_tolerance=0.1,
+                 computed_channels=None):
+        """ Simulation parameters used within the Nli Solver
+        :params method: formula for NLI calculation
+        :params dispersion_tolerance: tuning parameter for ggn model solution
+        :params phase_shift_tolerance: tuning parameter for ggn model solution
+        :params computed_channels: the NLI is evaluated for these channels and extrapolated for the others
+        """
+        self.method = method.lower()
+        self.dispersion_tolerance = dispersion_tolerance
+        self.phase_shift_tolerance = phase_shift_tolerance
+        self.computed_channels = computed_channels
+
+
+class SimParams(Parameters):
+    _shared_dict = {'nli_params': NLIParams(), 'raman_params': RamanParams()}
+
+    def __init__(self):
+        if type(self) == SimParams:
+            raise NotImplementedError('Instances of SimParams cannot be generated')
+
+    @classmethod
+    def set_params(cls, sim_params):
+        cls._shared_dict['nli_params'] = NLIParams(**sim_params.get('nli_params', {}))
+        cls._shared_dict['raman_params'] = RamanParams(**sim_params.get('raman_params', {}))
+
+    @classmethod
+    def get(cls):
+        self = cls.__new__(cls)
+        return self
+
+    @property
+    def nli_params(self):
+        return self._shared_dict['nli_params']
+
+    @property
+    def raman_params(self):
+        return self._shared_dict['raman_params']
+
+
+class RoadmParams(Parameters):
+    def __init__(self, **kwargs):
+        self.target_pch_out_db = kwargs.get('target_pch_out_db')
+        self.target_psd_out_mWperGHz = kwargs.get('target_psd_out_mWperGHz')
+        self.target_out_mWperSlotWidth = kwargs.get('target_out_mWperSlotWidth')
+        equalisation_type = ['target_pch_out_db', 'target_psd_out_mWperGHz', 'target_out_mWperSlotWidth']
+        temp = [kwargs.get(k) is not None for k in equalisation_type]
+        if sum(temp) > 1:
+            raise ParametersError('ROADM config contains more than one equalisation type.'
+                                  + 'Please choose only one', kwargs)
+        self.per_degree_pch_out_db = kwargs.get('per_degree_pch_out_db', {})
+        self.per_degree_pch_psd = kwargs.get('per_degree_psd_out_mWperGHz', {})
+        self.per_degree_pch_psw = kwargs.get('per_degree_psd_out_mWperSlotWidth', {})
+        try:
+            self.add_drop_osnr = kwargs['add_drop_osnr']
+            self.pmd = kwargs['pmd']
+            self.pdl = kwargs['pdl']
+            self.restrictions = kwargs['restrictions']
+        except KeyError as e:
+            raise ParametersError(f'ROADM configurations must include {e}. Configuration: {kwargs}')
+
+
+class FusedParams(Parameters):
+    def __init__(self, **kwargs):
+        self.loss = kwargs['loss'] if 'loss' in kwargs else 1
+
+
+# SSMF Raman coefficient profile normalized with respect to the effective area (Cr * A_eff)
+CR_NORM = array([
+    0., 7.802e-16, 2.4236e-15, 4.0504e-15, 5.6606e-15, 6.8973e-15, 7.802e-15, 8.4162e-15, 8.8727e-15, 9.2877e-15,
+    1.01011e-14, 1.05244e-14, 1.13295e-14, 1.2367e-14, 1.3695e-14, 1.5023e-14, 1.64091e-14, 1.81936e-14, 2.04927e-14,
+    2.28167e-14, 2.48917e-14, 2.66098e-14, 2.82615e-14, 2.98136e-14, 3.1042e-14, 3.17558e-14, 3.18803e-14, 3.17558e-14,
+    3.15566e-14, 3.11748e-14, 2.94567e-14, 3.14985e-14, 2.8552e-14, 2.43439e-14, 1.67992e-14, 9.6114e-15, 7.02180e-15,
+    5.9262e-15, 5.6938e-15, 7.055e-15, 7.4119e-15, 7.4783e-15, 6.7645e-15, 5.5361e-15, 3.6271e-15, 2.7224e-15,
+    2.4568e-15, 2.1995e-15, 2.1331e-15, 2.3323e-15, 2.5564e-15, 3.0461e-15, 4.8555e-15, 5.5029e-15, 5.2788e-15,
+    4.565e-15, 3.3698e-15, 2.2991e-15, 2.0086e-15, 1.5521e-15, 1.328e-15, 1.162e-15, 9.379e-16, 8.715e-16, 8.134e-16,
+    8.134e-16, 9.379e-16, 1.3612e-15, 1.6185e-15, 1.9754e-15, 1.8758e-15, 1.6849e-15, 1.2284e-15, 9.047e-16, 8.134e-16,
+    8.715e-16, 9.711e-16, 1.0375e-15, 1.0043e-15, 9.047e-16, 8.134e-16, 6.806e-16, 5.478e-16, 3.901e-16, 2.241e-16,
+    1.577e-16, 9.96e-17, 3.32e-17, 1.66e-17, 8.3e-18])
+
+# Note the non-uniform spacing of this range; this is required for properly capturing the Raman peak shape.
+FREQ_OFFSET = array([
+    0., 0.5, 1., 1.5, 2., 2.5, 3., 3.5, 4., 4.5, 5., 5.5, 6., 6.5, 7., 7.5, 8., 8.5, 9., 9.5, 10., 10.5, 11., 11.5, 12.,
+    12.5, 12.75, 13., 13.25, 13.5, 14., 14.5, 14.75, 15., 15.5, 16., 16.5, 17., 17.5, 18., 18.25, 18.5, 18.75, 19.,
+    19.5, 20., 20.5, 21., 21.5, 22., 22.5, 23., 23.5, 24., 24.5, 25., 25.5, 26., 26.5, 27., 27.5, 28., 28.5, 29., 29.5,
+    30., 30.5, 31., 31.5, 32., 32.5, 33., 33.5, 34., 34.5, 35., 35.5, 36., 36.5, 37., 37.5, 38., 38.5, 39., 39.5, 40.,
+    40.5, 41., 41.5, 42.]) * 1e12
+
+
+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.get('att_in', 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.get('con_in')
+            self._con_out = kwargs.get('con_out')
+            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  # conventional central C band wavelength [m]
+                self._ref_frequency = c / self._ref_wavelength
+            self._dispersion = kwargs['dispersion']  # s/m/m
+            self._dispersion_slope = \
+                kwargs.get('dispersion_slope', -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._effective_area = kwargs.get('effective_area')  # m^2
+            n2 = 2.6e-20  # m^2/W
+            if self._effective_area:
+                self._gamma = kwargs.get('gamma', 2 * pi * n2 / (self.ref_wavelength * self._effective_area))  # 1/W/m
+            elif 'gamma' in kwargs:
+                self._gamma = kwargs['gamma']  # 1/W/m
+                self._effective_area = 2 * pi * n2 / (self.ref_wavelength * self._gamma)  # m^2
+            else:
+                self._gamma = 0  # 1/W/m
+                self._effective_area = 83e-12  # m^2
+            default_raman_efficiency = {'cr': CR_NORM / self._effective_area, 'frequency_offset': FREQ_OFFSET}
+            self._raman_efficiency = kwargs.get('raman_efficiency', default_raman_efficiency)
+            self._pmd_coef = kwargs['pmd_coef']  # s/sqrt(m)
+            if type(kwargs['loss_coef']) == dict:
+                self._loss_coef = asarray(kwargs['loss_coef']['value']) * 1e-3  # lineic loss dB/m
+                self._f_loss_ref = asarray(kwargs['loss_coef']['frequency'])  # Hz
+            else:
+                self._loss_coef = asarray(kwargs['loss_coef']) * 1e-3  # lineic loss dB/m
+                self._f_loss_ref = asarray(self._ref_frequency)  # Hz
+            self._lumped_losses = kwargs['lumped_losses'] if 'lumped_losses' in kwargs else []
+        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
+
+    @property
+    def lumped_losses(self):
+        return self._lumped_losses
+
+    @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 raman_efficiency(self):
+        return self._raman_efficiency
+
+    def asdict(self):
+        dictionary = super().asdict()
+        dictionary['loss_coef'] = self.loss_coef * 1e3
+        dictionary['length_units'] = 'm'
+        if not self.lumped_losses:
+            dictionary.pop('lumped_losses')
+        if not self.raman_efficiency:
+            dictionary.pop('raman_efficiency')
+        return dictionary
+
+
+class EdfaParams:
+    def __init__(self, **params):
+        self.update_params(params)
+        if params == {}:
+            self.type_variety = ''
+            self.type_def = ''
+            # self.gain_flatmax = 0
+            # self.gain_min = 0
+            # self.p_max = 0
+            # self.nf_model = None
+            # self.nf_fit_coeff = None
+            # self.nf_ripple = None
+            # self.dgt = None
+            # self.gain_ripple = None
+            # self.out_voa_auto = False
+            # self.allowed_for_design = None
+
+    def update_params(self, kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, self.update_params(**v) if isinstance(v, dict) else v)
+
+
+class EdfaOperational:
+    default_values = {
+        'gain_target': None,
+        'delta_p': None,
+        'out_voa': None,
+        'tilt_target': 0
+    }
+
+    def __init__(self, **operational):
+        self.update_attr(operational)
+
+    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():
+            setattr(self, k, clean_kwargs.get(k, v))
+
+    def __repr__(self):
+        return (f'{type(self).__name__}('
+                f'gain_target={self.gain_target!r}, '
+                f'tilt_target={self.tilt_target!r})')

gnpy/core/science_utils.py

@@ -0,0 +1,522 @@
+#!/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, array, append, ones, exp, arange, sqrt, trapz, arcsinh, \
+    clip, abs, sum, concatenate, flip, outer, inner, transpose, max, format_float_scientific, diag, prod, argwhere, \
+    unique, argsort, cumprod
+from logging import getLogger
+from scipy.constants import k, h
+from scipy.interpolate import interp1d
+from math import isclose
+
+from gnpy.core.utils import db2lin, lin2db
+from gnpy.core.exceptions import EquipmentConfigError
+from gnpy.core.parameters import SimParams
+from gnpy.core.info import SpectralInformation
+
+logger = getLogger(__name__)
+sim_params = SimParams.get()
+
+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 StimulatedRamanScattering:
+    def __init__(self, power_profile, loss_profile, frequency, z):
+        """
+        :params power_profile: power profile matrix along frequency and z [W]
+        :params loss_profile: power profile matrix along frequency and z [linear units]
+        :params frequency: channels frequencies array [Hz]
+        :params z: positions array [m]
+        """
+        self.power_profile = power_profile
+        self.loss_profile = loss_profile
+        # Field loss profile matrix along frequency and z
+        self.rho = sqrt(loss_profile)
+        self.frequency = frequency
+        self.z = z
+
+
+class RamanSolver:
+    """This class contains the methods to calculate the Raman scattering effect."""
+
+    @staticmethod
+    def _create_lumped_losses(z, lumped_losses, z_lumped_losses):
+        lumped_losses = concatenate((lumped_losses, ones(z.size)))
+        z, unique_indices = unique(concatenate((z_lumped_losses, z)), return_index=True)
+        order = argsort(z)
+        lumped_losses = (lumped_losses[unique_indices])[order]
+        z = z[order]
+        return z, lumped_losses
+
+    @staticmethod
+    def calculate_attenuation_profile(spectral_info: SpectralInformation, fiber):
+        """Evaluates the attenuation profile along the z axis for all the frequency propagating in the
+        fiber without considering the stimulated Raman scattering.
+        """
+        # z array definition
+        z = array([0, fiber.params.length])
+
+        # Lumped losses array definition
+        z, lumped_losses = RamanSolver._create_lumped_losses(z, fiber.lumped_losses, fiber.z_lumped_losses)
+
+        lumped_loss_acc = cumprod(lumped_losses)
+        frequency = spectral_info.frequency
+        alpha = fiber.alpha(frequency)
+        loss_profile = exp(- outer(alpha, z)) * lumped_loss_acc
+        power_profile = outer(spectral_info.signal, ones(z.size)) * loss_profile
+        return StimulatedRamanScattering(power_profile, loss_profile, spectral_info.frequency, z)
+
+    @staticmethod
+    def calculate_stimulated_raman_scattering(spectral_info: SpectralInformation, fiber):
+        """Evaluates the Raman profile along the z axis for all the frequency propagated in the fiber
+        including the Raman pumps co- and counter-propagating
+        """
+        logger.debug('Start computing fiber Stimulated Raman Scattering')
+
+        if sim_params.raman_params.flag:
+            # Raman parameters
+            z_resolution = sim_params.raman_params.result_spatial_resolution
+            z_step = sim_params.raman_params.solver_spatial_resolution
+            z = append(arange(0, fiber.params.length, z_step), fiber.params.length)
+            z_final = append(arange(0, fiber.params.length, z_resolution), fiber.params.length)
+
+            # Lumped losses array definition
+            z, lumped_losses = RamanSolver._create_lumped_losses(z, fiber.lumped_losses, fiber.z_lumped_losses)
+
+            if hasattr(fiber, 'raman_pumps'):
+                # TODO: verify co-propagating pumps computation and in general unsorted frequency
+                # Co-propagating spectrum definition
+                co_raman_pump_power = array([pump.power for pump in fiber.raman_pumps
+                                             if pump.propagation_direction == 'coprop'])
+                co_raman_pump_frequency = array([pump.frequency for pump in fiber.raman_pumps
+                                                 if pump.propagation_direction == 'coprop'])
+
+                co_power = concatenate((spectral_info.signal, co_raman_pump_power))
+                co_frequency = concatenate((spectral_info.frequency, co_raman_pump_frequency))
+
+                # Counter-propagating spectrum definition
+                cnt_power = array([pump.power for pump in fiber.raman_pumps
+                                   if pump.propagation_direction == 'counterprop'])
+                cnt_frequency = array([pump.frequency for pump in fiber.raman_pumps
+                                       if pump.propagation_direction == 'counterprop'])
+                # Co-propagating profile initialization
+                co_power_profile = zeros([co_frequency.size, z.size])
+                if co_frequency.size:
+                    co_cr = fiber.cr(co_frequency)
+                    co_alpha = fiber.alpha(co_frequency)
+                    co_power_profile = \
+                        RamanSolver.first_order_derivative_solution(co_power, co_alpha, co_cr, z, lumped_losses)
+                # Counter-propagating profile initialization
+                cnt_power_profile = zeros([cnt_frequency.size, z.size])
+                if cnt_frequency.size:
+                    cnt_cr = fiber.cr(cnt_frequency)
+                    cnt_alpha = fiber.alpha(cnt_frequency)
+                    cnt_power_profile = \
+                        flip(RamanSolver.first_order_derivative_solution(cnt_power, cnt_alpha, cnt_cr,
+                                                                         z[-1] - flip(z), flip(lumped_losses)), axis=1)
+                # Co-propagating and Counter-propagating Profile Computation
+                if co_frequency.size and cnt_frequency.size:
+                    co_power_profile, cnt_power_profile = \
+                        RamanSolver.iterative_algorithm(co_power_profile, cnt_power_profile,
+                                                        co_frequency, cnt_frequency, z, fiber, lumped_losses)
+                # Complete Power Profile
+                power_profile = concatenate((co_power_profile, cnt_power_profile), axis=0)
+                # Complete Loss Profile
+                co_loss_profile = co_power_profile / outer(co_power, ones(z.size))
+                cnt_loss_profile = cnt_power_profile / outer(cnt_power, ones(z.size))
+                loss_profile = concatenate((co_loss_profile, cnt_loss_profile), axis=0)
+                # Complete frequency
+                frequency = concatenate((co_frequency, cnt_frequency))
+            else:
+                # Without Raman pumps
+                alpha = fiber.alpha(spectral_info.frequency)
+                cr = fiber.cr(spectral_info.frequency)
+                # Power profile
+                power_profile = \
+                    RamanSolver.first_order_derivative_solution(spectral_info.signal, alpha, cr, z, lumped_losses)
+                # Loss profile
+                loss_profile = power_profile / outer(spectral_info.signal, ones(z.size))
+                frequency = spectral_info.frequency
+            power_profile = interp1d(z, power_profile, axis=1)(z_final)
+            loss_profile = interp1d(z, loss_profile, axis=1)(z_final)
+            stimulated_raman_scattering = StimulatedRamanScattering(power_profile, loss_profile, frequency, z_final)
+        else:
+            stimulated_raman_scattering = \
+                RamanSolver.calculate_attenuation_profile(spectral_info, fiber)
+        return stimulated_raman_scattering
+
+    @staticmethod
+    def calculate_spontaneous_raman_scattering(spectral_info: SpectralInformation, srs: StimulatedRamanScattering,
+                                               fiber):
+        """Evaluates the Raman profile along the z axis for all the frequency propagated in the fiber
+        including the Raman pumps co- and counter-propagating.
+        """
+        logger.debug('Start computing fiber Spontaneous Raman Scattering')
+        z = srs.z
+        baud_rate = spectral_info.baud_rate
+        frequency = spectral_info.frequency
+        channels_loss = srs.loss_profile[:spectral_info.number_of_channels, :]
+
+        # calculate ase power
+        ase = zeros(spectral_info.number_of_channels)
+        for i, pump in enumerate(fiber.raman_pumps):
+            pump_power = srs.power_profile[spectral_info.number_of_channels + i, :]
+            df = pump.frequency - frequency
+            eta = - 1 / (1 - exp(h * df / (k * fiber.temperature)))
+            cr = fiber._cr_function(df)
+            integral = trapz(pump_power / channels_loss, z, axis=1)
+            ase += 2 * h * baud_rate * frequency * (1 + eta) * cr * (df > 0) * integral  # 2 factor for double pol
+        return ase
+
+    @staticmethod
+    def first_order_derivative_solution(power_in, alpha, cr, z, lumped_losses):
+        """Solves the Raman first order derivative equation
+
+        :param power_in: launch power array
+        :param alpha: loss coefficient array
+        :param cr: Raman efficiency coefficients matrix
+        :param z: z position array
+        :param lumped_losses: concentrated losses array along the fiber span
+        :return: power profile matrix
+        """
+        dz = z[1:] - z[:-1]
+        power = outer(power_in, ones(z.size))
+        for i in range(1, z.size):
+            power[:, i] = \
+                power[:, i - 1] * (1 + (- alpha + sum(cr * power[:, i - 1], 1)) * dz[i - 1]) * lumped_losses[i - 1]
+        return power
+
+    @staticmethod
+    def iterative_algorithm(co_initial_guess_power, cnt_initial_guess_power, co_frequency, cnt_frequency, z, fiber,
+                            lumped_losses):
+        """Solves the Raman first order derivative equation in case of both co- and counter-propagating
+        frequencies
+
+        :param co_initial_guess_power: co-propagationg Raman first order derivative equation solution
+        :param cnt_initial_guess_power: counter-propagationg Raman first order derivative equation solution
+        :param co_frequency: co-propagationg frequencies
+        :param cnt_frequency: counter-propagationg frequencies
+        :param z: z position array
+        :param fiber: instance of gnpy.core.elements.Fiber or gnpy.core.elements.RamanFiber
+        :param lumped_losses: concentrated losses array along the fiber span
+        :return: co- and counter-propagatng power profile matrix
+        """
+        logger.debug('  Start iterative algorithm')
+        residue = 1
+        residue_tol = 1e-6
+        accuracy = 1
+        accuracy_tol = 1e-3
+        iteration = 0
+        num_max_iter = 1000
+        prev_power = concatenate((co_initial_guess_power, cnt_initial_guess_power))
+        frequency = concatenate((co_frequency, cnt_frequency))
+        dz = z[1:] - z[:-1]
+        cr = fiber.cr(frequency)
+        alpha = fiber.alpha(frequency)
+        next_power = array(prev_power)
+        while residue > residue_tol and accuracy > accuracy_tol and iteration < num_max_iter:
+            iteration += 1
+            for i in range(1, z.size):
+                dpdz = - alpha + sum(cr * next_power[:, i - 1], 1)
+                next_power[:co_frequency.size, i] = \
+                    next_power[:co_frequency.size, i - 1] * (1 + dpdz[:co_frequency.size] * dz[i - 1]) * \
+                    lumped_losses[i - 1]
+            for i in range(1, z.size):
+                dpdz = - alpha + sum(cr * next_power[:, -i], 1)
+                next_power[co_frequency.size:, -i - 1] = \
+                    next_power[co_frequency.size:, -i] * (1 + dpdz[co_frequency.size:] * dz[-i]) * \
+                    lumped_losses[-i]
+
+            dpdz_num = (next_power[:co_frequency.size, 1:] - next_power[:co_frequency.size, :-1]) / dz
+            dpdz_exp = next_power[:co_frequency.size, :-1] * \
+                (- outer(alpha, ones(z.size)) + inner(cr, transpose(next_power)))[:co_frequency.size, :-1] * \
+                lumped_losses[:-1]
+
+            residue = max(abs((next_power - prev_power) / next_power))
+            accuracy = max(abs((dpdz_exp - dpdz_num) / dpdz_exp))
+            prev_power = array(next_power)
+            logger.debug(f'     Iteration: {iteration}  Accuracy: {format_float_scientific(accuracy, precision=3)}')
+        return next_power[:co_frequency.size, :], next_power[co_frequency.size:, :]
+
+
+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': eq. 21 from arXiv: 1710.02225 spectrally separated
+    """
+
+    @staticmethod
+    def effective_length(alpha, length):
+        """The effective length identify the region in which the NLI has a significant contribution to
+        the signal degradation.
+        """
+        return (1 - exp(- alpha * length)) / alpha
+
+    @staticmethod
+    def compute_nli(spectral_info: SpectralInformation, srs: StimulatedRamanScattering, fiber):
+        """ Compute NLI power generated by the WDM comb `*carriers` on the channel under test `carrier`
+        at the end of the fiber span.
+        """
+        logger.debug('Start computing fiber NLI noise')
+        # Physical fiber parameters
+        alpha = fiber.alpha(spectral_info.frequency)
+        beta2 = fiber.params.beta2
+        beta3 = fiber.params.beta3
+        f_ref_beta = fiber.params.ref_frequency
+        gamma = fiber.params.gamma
+        length = fiber.params.length
+
+        if 'gn_model_analytic' == sim_params.nli_params.method:
+            nli = NliSolver._gn_analytic(spectral_info, alpha, beta2, gamma, length)
+        elif 'ggn_spectrally_separated' in sim_params.nli_params.method:
+            nli = NliSolver._ggn_spectrally_separated(spectral_info, srs, alpha, beta2, beta3, f_ref_beta, gamma)
+        else:
+            raise ValueError(f'Method {sim_params.nli_params.method} not implemented.')
+        return nli
+
+    # Methods for computing GN-model
+    @staticmethod
+    def _gn_analytic(spectral_info: SpectralInformation, alpha, beta2, gamma, length):
+        """ Computes the nonlinear interference power evaluated at the fiber input.
+        The method uses eq. 120 from arXiv:1209.0394
+        """
+        spm_weight = (16.0 / 27.0) * gamma ** 2
+        xpm_weight = 2 * (16.0 / 27.0) * gamma ** 2
+
+        nch = spectral_info.number_of_channels
+        identity = diag(ones(nch))
+        weight = spm_weight * identity + xpm_weight * (ones([nch, nch]) - identity)
+
+        effective_length = NliSolver.effective_length(alpha, length)
+        asymptotic_length = 1 / alpha
+
+        df = spectral_info.df
+        baud_rate = spectral_info.baud_rate
+
+        psd = spectral_info.signal / baud_rate
+        ggg = outer(psd, psd**2)
+
+        psi = NliSolver._psi(df, baud_rate, beta2, effective_length, asymptotic_length)
+        g_nli = sum(weight * ggg * psi, 1)
+        nli = spectral_info.baud_rate * g_nli  # Local white noise
+        return nli
+
+    @staticmethod
+    def _psi(df, baud_rate, beta2, effective_length, asymptotic_length):
+        """Calculates eq. 123 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__"""
+        cut_baud_rate = outer(baud_rate, ones(baud_rate.size))
+        pump_baud_rate = baud_rate
+        right_extreme = df + pump_baud_rate / 2
+        left_extreme = df - pump_baud_rate / 2
+        psi = (arcsinh(pi ** 2 * asymptotic_length * abs(beta2) * cut_baud_rate * right_extreme) -
+               arcsinh(pi ** 2 * asymptotic_length * abs(beta2) * cut_baud_rate * left_extreme)) / 2
+        psi *= effective_length ** 2 / (2 * pi * abs(beta2) * asymptotic_length)
+        return psi
+
+    # Methods for computing the GGN-model
+    @staticmethod
+    def _ggn_spectrally_separated(spectral_info: SpectralInformation, srs: StimulatedRamanScattering,
+                                  alpha, beta2, beta3, f_ref_beta, gamma):
+        """ Computes the nonlinear interference power evaluated at the fiber input.
+        The method uses eq. 21 from arXiv: 1710.02225
+        """
+        dispersion_tolerance = sim_params.nli_params.dispersion_tolerance
+        phase_shift_tolerance = sim_params.nli_params.phase_shift_tolerance
+        slot_width = max(spectral_info.slot_width)
+        delta_z = sim_params.raman_params.result_spatial_resolution
+        spm_weight = (16.0 / 27.0) * gamma ** 2
+        xpm_weight = 2 * (16.0 / 27.0) * gamma ** 2
+        cuts = [carrier for carrier in spectral_info.carriers if carrier.channel_number
+                in sim_params.nli_params.computed_channels] if sim_params.nli_params.computed_channels \
+            else spectral_info.carriers
+
+        g_nli = array([])
+        f_nli = array([])
+        for cut_carrier in cuts:
+            logger.debug(f'Start computing fiber NLI noise of cut: {cut_carrier}')
+            f_eval = cut_carrier.frequency
+            g_nli_computed = 0
+            g_cut = (cut_carrier.power.signal / cut_carrier.baud_rate)
+            for j, pump_carrier in enumerate(spectral_info.carriers):
+                dn = abs(pump_carrier.channel_number - cut_carrier.channel_number)
+                delta_f = abs(cut_carrier.frequency - pump_carrier.frequency)
+                k_tol = dispersion_tolerance * abs(alpha[j])
+                phi_tol = phase_shift_tolerance / delta_z
+                f_cut_resolution = min(k_tol, phi_tol) / abs(beta2) / (4 * pi ** 2 * (1 + dn) * slot_width)
+                f_pump_resolution = min(k_tol, phi_tol) / abs(beta2) / (4 * pi ** 2 * slot_width)
+                if dn == 0:  # SPM
+                    ggg = g_cut ** 3
+                    g_nli_computed += \
+                        spm_weight * ggg * NliSolver._generalized_psi(f_eval, cut_carrier, pump_carrier,
+                                                                      f_cut_resolution, f_pump_resolution,
+                                                                      srs, alpha[j], beta2, beta3, f_ref_beta)
+                else:  # XPM
+                    g_pump = (pump_carrier.power.signal / pump_carrier.baud_rate)
+                    ggg = g_cut * g_pump ** 2
+                    frequency_offset_threshold = NliSolver._frequency_offset_threshold(beta2, pump_carrier.baud_rate)
+                    if abs(delta_f) <= frequency_offset_threshold:
+                        g_nli_computed += \
+                            xpm_weight * ggg * NliSolver._generalized_psi(f_eval, cut_carrier, pump_carrier,
+                                                                          f_cut_resolution, f_pump_resolution,
+                                                                          srs, alpha[j], beta2, beta3, f_ref_beta)
+                    else:
+                        g_nli_computed += \
+                            xpm_weight * ggg * NliSolver._fast_generalized_psi(f_eval, cut_carrier, pump_carrier,
+                                                                               f_cut_resolution, srs, alpha[j], beta2,
+                                                                               beta3, f_ref_beta)
+            f_nli = append(f_nli, cut_carrier.frequency)
+            g_nli = append(g_nli, g_nli_computed)
+        g_nli = interp(spectral_info.frequency, f_nli, g_nli)
+        nli = spectral_info.baud_rate * g_nli  # Local white noise
+        return nli
+
+    @staticmethod
+    def _fast_generalized_psi(f_eval, cut_carrier, pump_carrier, f_cut_resolution, srs, alpha, beta2, beta3,
+                              f_ref_beta):
+        """Computes the generalized psi function similarly to the one used in the GN model."""
+        z = srs.z
+        rho_norm = srs.rho * exp(outer(alpha/2, z))
+        rho_pump = interp1d(srs.frequency, rho_norm, axis=0)(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 = NliSolver._generalized_rho_nli(delta_beta, rho_pump, z, alpha)
+            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
+
+    @staticmethod
+    def _generalized_psi(f_eval, cut_carrier, pump_carrier, f_cut_resolution, f_pump_resolution, srs, alpha, beta2,
+                         beta3, f_ref_beta):
+        """Computes the generalized psi function similarly to the one used in the GN model."""
+        z = srs.z
+        rho_norm = srs.rho * exp(outer(alpha / 2, z))
+        rho_pump = interp1d(srs.frequency, rho_norm, axis=0)(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 * NliSolver._generalized_rho_nli(delta_beta, rho_pump, z, alpha)
+            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_pump, z, alpha):
+        w = 1j * delta_beta - alpha
+        generalized_rho_nli = (rho_pump[-1]**2 * exp(w * z[-1]) - rho_pump[0]**2 * exp(w * z[0])) / w
+        for z_ind in range(0, len(z) - 1):
+            derivative_rho = (rho_pump[z_ind + 1]**2 - rho_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
+
+    @staticmethod
+    def _frequency_offset_threshold(beta2, symbol_rate):
+        k_ref = 5
+        beta2_ref = 21.3e-27
+        delta_f_ref = 50e9
+        rs_ref = 32e9
+        beta2 = abs(beta2)
+        freq_offset_th = ((k_ref * delta_f_ref) * rs_ref * beta2_ref) / (beta2 * symbol_rate)
+        return freq_offset_th
+
+
+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/utils.py

@@ -0,0 +1,415 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+gnpy.core.utils
+===============
+
+This module contains utility functions that are used with gnpy.
+"""
+
+from csv import writer
+from numpy import pi, cos, sqrt, log10, linspace, zeros, shape, where, logical_and, mean
+from scipy import constants
+
+from gnpy.core.exceptions import ConfigurationError
+
+
+def write_csv(obj, filename):
+    """
+    Convert dictionary items to a CSV file the dictionary format:
+    ::
+
+        {'result category 1':
+                        [
+                        # 1st line of results
+                        {'header 1' : value_xxx,
+                         'header 2' : value_yyy},
+                         # 2nd line of results: same headers, different results
+                        {'header 1' : value_www,
+                         'header 2' : 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
+            w.writerow([data_key])
+            # 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 arrange_frequencies(length, start, stop):
+    """Create an array of frequencies
+
+    :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 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 watt2dbm(value):
+    """Convert Watt units to dBm
+
+    >>> round(watt2dbm(0.001), 1)
+    0.0
+    >>> round(watt2dbm(0.02), 1)
+    13.0
+    """
+    return lin2db(value * 1e3)
+
+
+def dbm2watt(value):
+    """Convert dBm units to Watt
+
+    >>> round(dbm2watt(0), 4)
+    0.001
+    >>> round(dbm2watt(-3), 4)
+    0.0005
+    >>> round(dbm2watt(13), 4)
+    0.02
+    """
+    return db2lin(value) * 1e-3
+
+
+def psd2powerdbm(psd_mwperghz, baudrate_baud):
+    """computes power in dBm based on baudrate in bauds and psd in mW/GHz
+
+    >>> round(psd2powerdbm(0.031176, 64e9),3)
+    3.0
+    >>> round(psd2powerdbm(0.062352, 32e9),3)
+    3.0
+    >>> round(psd2powerdbm(0.015625, 64e9),3)
+    0.0
+    """
+    return lin2db(baudrate_baud * psd_mwperghz * 1e-9)
+
+
+def power_dbm_to_psd_mw_ghz(power_dbm, baudrate_baud):
+    """computes power spectral density in  mW/GHz based on baudrate in bauds and power in dBm
+
+    >>> power_dbm_to_psd_mw_ghz(0, 64e9)
+    0.015625
+    >>> round(power_dbm_to_psd_mw_ghz(3, 64e9), 6)
+    0.031176
+    >>> round(power_dbm_to_psd_mw_ghz(3, 32e9), 6)
+    0.062352
+    """
+    return db2lin(power_dbm) / (baudrate_baud * 1e-9)
+
+
+def psd_mw_per_ghz(power_watt, baudrate_baud):
+    """computes power spectral density in  mW/GHz based on baudrate in bauds and power in W
+
+    >>> psd_mw_per_ghz(2e-3, 32e9)
+    0.0625
+    >>> psd_mw_per_ghz(1e-3, 64e9)
+    0.015625
+    >>> psd_mw_per_ghz(0.5e-3, 32e9)
+    0.015625
+    """
+    return power_watt * 1e3 / (baudrate_baud * 1e-9)
+
+
+def round2float(number, step):
+    """Round a floating point number so that its "resolution" is not bigger than 'step'
+
+    The finest step is fixed at 0.01; smaller values are silently changed to 0.01.
+
+    >>> round2float(123.456, 1000)
+    0.0
+    >>> round2float(123.456, 100)
+    100.0
+    >>> round2float(123.456, 10)
+    120.0
+    >>> round2float(123.456, 1)
+    123.0
+    >>> round2float(123.456, 0.1)
+    123.5
+    >>> round2float(123.456, 0.01)
+    123.46
+    >>> round2float(123.456, 0.001)
+    123.46
+    >>> round2float(123.249, 0.5)
+    123.0
+    >>> round2float(123.250, 0.5)
+    123.0
+    >>> round2float(123.251, 0.5)
+    123.5
+    >>> round2float(123.300, 0.2)
+    123.2
+    >>> round2float(123.301, 0.2)
+    123.4
+    """
+    step = round(step, 1)
+    if step >= 0.01:
+        number = round(number / step, 0)
+        number = round(number * step, 1)
+    else:
+        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 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))
+    return snr
+
+
+def per_label_average(values, labels):
+    """computes the average per defined spectrum band, using labels
+
+    >>> labels = ['A', 'A', 'A', 'A', 'A', 'B', 'B', 'B', 'B', 'B', 'B', 'B', 'B', 'C', 'D', 'D', 'D', 'D']
+    >>> values = [28.51, 28.23, 28.15, 28.17, 28.36, 28.53, 28.64, 28.68, 28.7, 28.71, 28.72, 28.73, 28.74, 28.91, 27.96, 27.85, 27.87, 28.02]
+    >>> per_label_average(values, labels)
+    {'A': 28.28, 'B': 28.68, 'C': 28.91, 'D': 27.92}
+    """
+
+    label_set = sorted(set(labels))
+    summary = {}
+    for label in label_set:
+        vals = [val for val, lab in zip(values, labels) if lab == label]
+        summary[label] = round(mean(vals), 2)
+    return summary
+
+
+def pretty_summary_print(summary):
+    """Build a prettty string that shows the summary dict values per label with 2 digits
+    """
+    if len(summary) == 1:
+        return f'{list(summary.values())[0]:.2f}'
+    text = ', '.join([f'{label}: {value:.2f}' for label, value in summary.items()])
+    return text
+
+
+def deltawl2deltaf(delta_wl, wavelength):
+    """ deltawl2deltaf(delta_wl, wavelength):
+    delta_wl is BW in wavelength units
+    wavelength is the center wl
+    units for delta_wl and wavelength must be same
+
+    :param delta_wl: delta wavelength BW in same units as wavelength
+    :param wavelength: wavelength BW is relevant for
+    :type delta_wl: float or numpy.ndarray
+    :type wavelength: float
+    :return: The BW in frequency units
+    :rtype: float or ndarray
+
+    """
+    f = wavelength2freq(wavelength)
+    return delta_wl * f / wavelength
+
+
+def deltaf2deltawl(delta_f, frequency):
+    """ deltawl2deltaf(delta_f, frequency):
+        converts delta frequency to delta wavelength
+        units for delta_wl and wavelength must be same
+
+    :param delta_f: delta frequency in same units as frequency
+    :param frequency: frequency BW is relevant for
+    :type delta_f: float or numpy.ndarray
+    :type frequency: float
+    :return: The BW in wavelength units
+    :rtype: float or ndarray
+
+    """
+    wl = freq2wavelength(frequency)
+    return delta_f * wl / frequency
+
+
+def rrc(ffs, baud_rate, alpha):
+    """ rrc(ffs, baud_rate, alpha): computes the root-raised cosine filter
+    function.
+
+    :param ffs: A numpy array of frequencies
+    :param baud_rate: The Baud Rate of the System
+    :param alpha: The roll-off factor of the filter
+    :type ffs: numpy.ndarray
+    :type baud_rate: float
+    :type alpha: float
+    :return: hf a numpy array of the filter shape
+    :rtype: numpy.ndarray
+
+    """
+    Ts = 1 / baud_rate
+    l_lim = (1 - alpha) / (2 * Ts)
+    r_lim = (1 + alpha) / (2 * Ts)
+    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) *
+                                    (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

@@ -0,0 +1,106 @@
+{
+    "nf_ripple": [
+        0.0
+    ],
+    "gain_ripple": [
+        0.0
+    ],
+    "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
+    ]
+}

gnpy/example-data/edfa_example_network.json

@@ -0,0 +1,80 @@
+{
+    "network_name": "EDFA Example Network - P2P",
+    "elements": [{
+            "uid": "Site_A",
+            "type": "Transceiver",
+            "metadata": {
+                "location": {
+                    "city": "Site A",
+                    "region": "",
+                    "latitude": 0,
+                    "longitude": 0
+                }
+            }
+        },
+        {
+            "uid": "Span1",
+            "type": "Fiber",
+            "type_variety": "SSMF",
+            "params": {
+                "length": 80,
+                "loss_coef": 0.2,
+                "length_units": "km",
+                "att_in": 0,
+                "con_in": 0.5,
+                "con_out": 0.5                
+                },
+            "metadata": {
+                "location": {
+                    "region": "",
+                    "latitude": 1,
+                    "longitude": 0
+                }
+            }
+        },
+        {
+            "uid": "Edfa1",
+            "type": "Edfa",
+            "type_variety": "std_low_gain",            
+            "operational": {
+                "gain_target": 17,
+                "tilt_target": 0,
+                "out_voa": 0
+            },
+            "metadata": {
+                "location": {
+                    "region": "",
+                    "latitude": 2,
+                    "longitude": 0
+                }
+            }
+        },
+        {
+            "uid": "Site_B",
+            "type": "Transceiver",
+            "metadata": {
+                "location": {
+                    "city": "Site B",
+                    "region": "",
+                    "latitude": 2,
+                    "longitude": 0
+                }
+            }
+        }
+
+    ],
+    "connections": [{
+            "from_node": "Site_A",
+            "to_node": "Span1"
+        },
+        {
+            "from_node": "Span1",
+            "to_node": "Edfa1"
+        },
+        {
+            "from_node": "Edfa1",
+            "to_node": "Site_B"
+        }
+
+    ]
+}

gnpy/example-data/edfa_model/DFG_96.txt

@@ -0,0 +1 @@
+   2.5135969849999999e+01   2.5118228139999999e+01   2.5095421330000001e+01   2.5062457710000000e+01   2.5026027650000000e+01   2.4996379529999999e+01   2.4981672549999999e+01   2.4975306679999999e+01   2.4983207260000000e+01   2.4997185649999999e+01   2.5017572470000001e+01   2.5038327809999998e+01   2.5054955849999999e+01   2.5067071899999998e+01   2.5070914110000000e+01   2.5070943650000000e+01   2.5071143240000001e+01   2.5075336270000001e+01   2.5087310179999999e+01   2.5103139360000000e+01   2.5122762040000001e+01   2.5142394790000001e+01   2.5159456330000001e+01   2.5173927039999999e+01   2.5176737670000001e+01   2.5170371410000001e+01   2.5152162539999999e+01   2.5131143099999999e+01   2.5108023350000000e+01   2.5085487770000000e+01   2.5069166750000001e+01   2.5058481759999999e+01   2.5054473130000002e+01   2.5051544410000002e+01   2.5049460589999999e+01   2.5047178490000000e+01   2.5045516559999999e+01   2.5044676490000001e+01   2.5040729200000001e+01   2.5032854080000000e+01   2.5023488300000000e+01   2.5016592339999999e+01   2.5013321359999999e+01   2.5011234340000001e+01   2.5010300149999999e+01   2.5009365480000000e+01   2.5008739640000002e+01   2.5008425350000000e+01   2.5006964660000001e+01   2.5004043100000001e+01   2.5000709980000000e+01   2.4998423200000001e+01   2.4993063320000001e+01   2.4983524209999999e+01   2.4971251030000001e+01   2.4960381080000001e+01   2.4948887209999999e+01   2.4935314890000001e+01   2.4921319270000001e+01   2.4908986970000001e+01   2.4898965140000001e+01   2.4889584630000002e+01   2.4880838700000002e+01   2.4872100920000001e+01   2.4864620259999999e+01   2.4858397730000000e+01   2.4854458380000001e+01   2.4851554430000000e+01   2.4851766009999999e+01   2.4854080140000001e+01   2.4859096240000000e+01   2.4864744580000000e+01   2.4872034859999999e+01   2.4880365200000000e+01   2.4889106689999998e+01   2.4897213130000001e+01   2.4902826040000001e+01   2.4906566900000001e+01   2.4908650800000000e+01   2.4910939440000000e+01   2.4913430790000000e+01   2.4915923440000000e+01   2.4921553509999999e+01   2.4930318610000000e+01   2.4940528120000000e+01   2.4949046689999999e+01   2.4957571229999999e+01   2.4967818449999999e+01   2.4981800929999999e+01   2.4997826860000000e+01   2.5013931830000001e+01   2.5028098459999999e+01   2.5040325750000001e+01   2.5052569810000001e+01   2.5064797009999999e+01   2.5077046970000001e+01

gnpy/example-data/edfa_model/DGT_96.txt

@@ -0,0 +1 @@
+   2.7145266811316859e+00   2.7054438192385049e+00   2.6947834587664494e+00   2.6841217449620203e+00   2.6681935771243177e+00   2.6521732021128046e+00   2.6303964408153848e+00   2.6028603502864280e+00   2.5696460593920065e+00   2.5364027376452056e+00   2.4994462867966041e+00   2.4587748041127506e+00   2.4143984371852212e+00   2.3699990328716107e+00   2.3223736962293420e+00   2.2715207713712529e+00   2.2174389328192197e+00   2.1633756538423898e+00   2.1183028432496016e+00   2.0822250998736478e+00   2.0551007720052352e+00   2.0279625371819305e+00   2.0008103857988204e+00   1.9736443063300082e+00   1.9482128147680253e+00   1.9245345552113182e+00   1.9026104247588487e+00   1.8806927939516411e+00   1.8622356724442459e+00   1.8472755032011290e+00   1.8358140813807049e+00   1.8243814368429321e+00   1.8139629377087627e+00   1.8045606557581335e+00   1.7961751115773796e+00   1.7877868031023945e+00   1.7793941781790852e+00   1.7709972329654864e+00   1.7625959636196327e+00   1.7541903672600494e+00   1.7459181197626403e+00   1.7377807579136351e+00   1.7297783508684146e+00   1.7217732861435076e+00   1.7137640932265894e+00   1.7057507692361864e+00   1.6918150918099673e+00   1.6719047669939942e+00   1.6460167077689267e+00   1.6201194134191075e+00   1.5986915141218316e+00   1.5817353179379183e+00   1.5691997641843789e+00   1.5566577309558969e+00   1.5453741527614671e+00   1.5353620432989845e+00   1.5266220576235803e+00   1.5178910621476225e+00   1.5097346239790443e+00   1.5021530399096861e+00   1.4951454560626991e+00   1.4881342434792260e+00   1.4811193973568100e+00   1.4741004422522110e+00   1.4670307626366115e+00   1.4599103316162523e+00   1.4527395948591399e+00   1.4455651371583680e+00   1.4340878115214444e+00   1.4182738067303231e+00   1.3981208704326855e+00   1.3779439775587023e+00   1.3598972673004606e+00   1.3439818461440451e+00   1.3301807335621048e+00   1.3163839268630830e+00   1.3040618749785347e+00   1.2932153453410835e+00   1.2838336236692311e+00   1.2744470198196236e+00   1.2650555289898042e+00   1.2556591482982988e+00   1.2428104897182262e+00   1.2264996957264114e+00   1.2067249615595257e+00   1.1869318618366975e+00   1.1672278304018044e+00   1.1476135933863398e+00   1.1280891949729075e+00   1.1085552896156590e+00   1.0895983485572227e+00   1.0712204022764056e+00   1.0534217504465226e+00   1.0356155337864215e+00   1.0178077678537021e+00   1.0000000000000000e+00

gnpy/example-data/edfa_model/NFR_96.txt

@@ -0,0 +1 @@
+  -3.1537433199999998e-01  -3.1537433199999998e-01  -3.1540091571002721e-01  -3.1849146117510951e-01  -3.2158358425400546e-01  -3.2467728615499991e-01  -3.2762368641496226e-01  -3.2054138461232762e-01  -3.1345546385118733e-01  -3.0636592135697482e-01  -2.9920267890990127e-01  -2.7061972852631744e-01  -2.4202215770774693e-01  -2.1340995523361256e-01  -1.8478227130158695e-01  -1.4809761118389625e-01  -1.1139416731807622e-01  -7.4671925273579881e-02  -3.8026748965679924e-02  -1.9958469399422092e-02  -1.8809287980157928e-03   1.6205879960573561e-02   3.4301964005709673e-02   5.2407330474054062e-02   7.0521986509597359e-02   7.9578036683472006e-02   8.8546647361909522e-02   9.7519863231965306e-02   1.0649768784154924e-01   9.7741380449907406e-02   8.8803437172660038e-02   7.9860899732845866e-02   7.0913764587403796e-02   6.3335892740565308e-02   5.5756212252058776e-02   4.8172631747863209e-02   4.0585148217162359e-02   3.3381591675710129e-02   2.6178308595650738e-02   1.8971315351761126e-02   1.1760609076833628e-02   1.6950294922759991e-02   2.2274991357701439e-02   2.7602433189104329e-02   3.2932622540790261e-02   3.8265561538776145e-02   4.3601252311271169e-02   3.4856990743481552e-02   2.5991055149117932e-02   1.7120541224980364e-02   8.2757587359203223e-03   1.9423214065246042e-03  -4.3943890171043590e-03  -1.0734375072893196e-02  -1.7077639301414434e-02  -2.4679702899572852e-02  -3.2297970403821680e-02  -3.9920180090477250e-02  -4.7534566327530239e-02  -4.9234003141433724e-02  -5.0934320036547187e-02  -5.2635517696692252e-02  -5.4337596806402461e-02  -5.6040558050919301e-02  -5.7718452237076875e-02  -5.6840590379175944e-02  -5.5962273198734966e-02  -5.5083500341416583e-02  -5.4204271452516814e-02  -5.8396088726955113e-02  -6.2627330169715334e-02  -6.6860769089203700e-02  -7.0901736256069450e-02  -5.2096097309052243e-02  -3.3280684121412940e-02  -1.4455489070928059e-02   4.3150387579057158e-03   1.4839202394482527e-02   2.5368841662503576e-02   3.5903960836465652e-02   4.6444564195321399e-02   5.6990656022467459e-02   6.7542240605774059e-02   1.0002709623672751e-01   1.3258013095133617e-01   1.6515013362773309e-01   1.9773711753599391e-01   2.3194802687829724e-01   2.6618779883837107e-01   3.0044543658085349e-01   3.3472095409250663e-01   3.5929034770587287e-01   3.8384389188855605e-01   4.0841026111391787e-01   4.3298946543290784e-01   4.3298946543290784e-01

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

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Tue Jan 30 12:32:00 2018
+
+@author: jeanluc-auge
+
+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'
+"""
+import re
+import sys
+import json
+import numpy as np
+
+"""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:
+{
+    "nf_fit_coeff": "nf_filename.txt",
+    "nf_ripple": "nf_ripple_filename.txt",
+    "gain_ripple": "DFG_filename.txt",
+    "dgt": "DGT_filename.txt",
+}
+
+"""
+
+input_json_file_name = "OA.json"  # default path
+output_json_file_name = "default_edfa_config.json"
+gain_ripple_field = "gain_ripple"
+nf_ripple_field = "nf_ripple"
+nf_fit_coeff = "nf_fit_coeff"
+
+
+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:
+    #   data = this_file.read()
+    # 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
+        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:
+        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)):
+            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:
+        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)

gnpy/example-data/edfa_model/pNFfit3.txt

@@ -0,0 +1 @@
+   1.6824099999999999e-04   4.6996099999999999e-02   3.5954899999999998e-02   5.8285099999999996e+00

gnpy/example-data/eqpt_config.json

@@ -0,0 +1,323 @@
+{     "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_preamp_typical_ver5",
+            "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_worstcase_ver5",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-5.952e-4,-6.250e-2,-1.071,27.99],
+            "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,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "NZDF",
+            "dispersion": 0.5e-05,
+            "effective_area": 72e-12,
+            "pmd_coef": 1.265e-15
+            },
+            {
+            "type_variety": "LOF",
+            "dispersion": 2.2e-05,
+            "effective_area": 125e-12,
+            "pmd_coef": 1.265e-15
+            }
+      ],
+      "RamanFiber":[{
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+            }
+      ],
+      "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,
+            "pdl": 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_ver4.json

@@ -0,0 +1,349 @@
+{
+    "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],
+            "pmd": 3e-12,
+            "pdl": 0.7,
+            "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],
+            "pmd": 3e-12,
+            "pdl": 0.7,
+            "allowed_for_design": true
+        },
+        {
+            "type_variety": "openroadm_mw_mw_preamp",
+            "type_def": "openroadm_preamp",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "pmd": 0,
+            "pdl": 0,
+            "allowed_for_design": false
+        },
+        {
+            "type_variety": "openroadm_mw_mw_booster",
+            "type_def": "openroadm_booster",
+            "gain_flatmax": 32,
+            "gain_min": 0,
+            "p_max": 22,
+            "pmd": 0,
+            "pdl": 0,
+            "allowed_for_design": false
+        }
+    ],
+    "Fiber": [
+        {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+        },
+        {
+            "type_variety": "NZDF",
+            "dispersion": 0.5e-05,
+            "effective_area": 72e-12,
+            "pmd_coef": 1.265e-15
+        },
+        {
+            "type_variety": "LOF",
+            "dispersion": 2.2e-05,
+            "effective_area": 125e-12,
+            "pmd_coef": 1.265e-15
+        }
+    ],
+    "RamanFiber": [
+        {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+        }
+    ],
+    "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": 3e-12,
+            "pdl": 1.5,
+            "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 18e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 30,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        },
+                        {
+                            "pdl": 6,
+                            "penalty_value": 4
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 40e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 30,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        },
+                        {
+                            "pdl": 6,
+                            "penalty_value": 4
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 24e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 25,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 18e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 25,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 12e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 20,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "min_spacing": 87.5e9,
+                    "cost": 1
+                }
+            ]
+        }
+    ]
+}

gnpy/example-data/eqpt_config_openroadm_ver5.json

@@ -0,0 +1,409 @@
+{
+    "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],
+            "pmd": 3e-12,
+            "pdl": 0.7,
+            "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],
+            "pmd": 3e-12,
+            "pdl": 0.7,
+            "allowed_for_design": true
+        },
+        {
+            "type_variety": "openroadm_mw_mw_preamp_typical_ver5",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-5.952e-4, -6.250e-2, -1.071, 28.99],
+            "pmd": 0,
+            "pdl": 0,
+            "allowed_for_design": false
+        },
+        {
+            "type_variety": "openroadm_mw_mw_preamp_worstcase_ver5",
+            "type_def": "openroadm",
+            "gain_flatmax": 27,
+            "gain_min": 0,
+            "p_max": 22,
+            "nf_coef": [-5.952e-4, -6.250e-2, -1.071, 27.99],
+            "pmd": 0,
+            "pdl": 0,
+            "allowed_for_design": false
+        },
+        {
+            "type_variety": "openroadm_mw_mw_booster",
+            "type_def": "openroadm_booster",
+            "gain_flatmax": 32,
+            "gain_min": 0,
+            "p_max": 22,
+            "pmd": 0,
+            "pdl": 0,
+            "allowed_for_design": false
+        }
+    ],
+    "Fiber": [
+        {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+        },
+        {
+            "type_variety": "NZDF",
+            "dispersion": 0.5e-05,
+            "effective_area": 72e-12,
+            "pmd_coef": 1.265e-15
+        },
+        {
+            "type_variety": "LOF",
+            "dispersion": 2.2e-05,
+            "effective_area": 125e-12,
+            "pmd_coef": 1.265e-15
+        }
+    ],
+    "RamanFiber": [
+        {
+            "type_variety": "SSMF",
+            "dispersion": 1.67e-05,
+            "effective_area": 83e-12,
+            "pmd_coef": 1.265e-15
+        }
+    ],
+    "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": 33,
+            "pmd": 3e-12,
+            "pdl": 1.5,
+            "restrictions": {
+                "preamp_variety_list": ["openroadm_mw_mw_preamp_worstcase_ver5"],
+                "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. 5.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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 18e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 30,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        },
+                        {
+                            "pdl": 6,
+                            "penalty_value": 4
+                        }
+                    ],
+                    "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": 36,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 48e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 30,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        },
+                        {
+                            "pdl": 6,
+                            "penalty_value": 4
+                        }
+                    ],
+                    "min_spacing": 50e9,
+                    "cost": 1
+                },
+                {
+                    "format": "200 Gbit/s, 31.57 Gbaud, DP-16QAM",
+                    "baud_rate": 31.57e9,
+                    "OSNR": 20.5,
+                    "bit_rate": 100e9,
+                    "roll_off": 0.15,
+                    "tx_osnr": 36,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 24e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 30,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        },
+                        {
+                            "pdl": 6,
+                            "penalty_value": 4
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 24e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 25,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 18e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 25,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "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,
+                    "penalties": [
+                        {
+                            "chromatic_dispersion": -1e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 4e3,
+                            "penalty_value": 0
+                        },
+                        {
+                            "chromatic_dispersion": 12e3,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pmd": 10,
+                            "penalty_value": 0
+                        },
+                        {
+                            "pmd": 20,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 1,
+                            "penalty_value": 0.5
+                        },
+                        {
+                            "pdl": 2,
+                            "penalty_value": 1
+                        },
+                        {
+                            "pdl": 4,
+                            "penalty_value": 2.5
+                        }
+                    ],
+                    "min_spacing": 87.5e9,
+                    "cost": 1
+                }
+            ]
+        }
+    ]
+}

gnpy/example-data/fused_roadm_example_network.json

@@ -0,0 +1,196 @@
+{
+  "elements": [
+    {
+      "uid": "trx Site_A",
+      "metadata": {
+        "location": {
+          "city": "Site_A",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Transceiver"
+    },
+    {
+      "uid": "trx Site_C",
+      "metadata": {
+        "location": {
+          "city": "Site_C",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Transceiver"
+    },
+    {
+      "uid": "roadm Site_A",
+      "metadata": {
+        "location": {
+          "city": "Site_A",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Roadm",
+      "params": {
+        "loss": 17
+      }
+    },
+    {
+      "uid": "roadm Site_C",
+      "metadata": {
+        "location": {
+          "city": "Site_C",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Roadm"
+    },
+    {
+      "uid": "ingress fused spans in Site_B",
+      "metadata": {
+        "location": {
+          "city": "Site_B",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Fused",
+      "params": {
+        "loss": 0.5
+      }
+    },
+    {
+      "uid": "egress fused spans in Site_B",
+      "metadata": {
+        "location": {
+          "city": "Site_B",
+          "region": "",
+          "latitude": 0,
+          "longitude": 0
+        }
+      },
+      "type": "Fused"
+    },
+    {
+      "uid": "fiber (Site_A \u2192 Site_B)-",
+      "metadata": {
+        "location": {
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Fiber",
+      "type_variety": "SSMF",
+      "params": {
+        "length": 40.0,
+        "length_units": "km",
+        "loss_coef": 0.2
+      }
+    },
+    {
+      "uid": "fiber (Site_B \u2192 Site_C)-",
+      "metadata": {
+        "location": {
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Fiber",
+      "type_variety": "SSMF",
+      "params": {
+        "length": 50.0,
+        "length_units": "km",
+        "loss_coef": 0.2
+      }
+    },
+    {
+      "uid": "fiber (Site_B \u2192 Site_A)-",
+      "metadata": {
+        "location": {
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Fiber",
+      "type_variety": "SSMF",
+      "params": {
+        "length": 40.0,
+        "length_units": "km",
+        "loss_coef": 0.2
+      }
+    },
+    {
+      "uid": "fiber (Site_C \u2192 Site_B)-",
+      "metadata": {
+        "location": {
+          "latitude": 0.0,
+          "longitude": 0.0
+        }
+      },
+      "type": "Fiber",
+      "type_variety": "SSMF",
+      "params": {
+        "length": 50.0,
+        "length_units": "km",
+        "loss_coef": 0.2
+      }
+    }
+  ],
+  "connections": [
+    {
+      "from_node": "roadm Site_A",
+      "to_node": "fiber (Site_A \u2192 Site_B)-"
+    },
+    {
+      "from_node": "fiber (Site_B \u2192 Site_A)-",
+      "to_node": "roadm Site_A"
+    },
+    {
+      "from_node": "fiber (Site_A \u2192 Site_B)-",
+      "to_node": "ingress fused spans in Site_B"
+    },
+    {
+      "from_node": "ingress fused spans in Site_B",
+      "to_node": "fiber (Site_B \u2192 Site_C)-"
+    },
+    {
+      "from_node": "fiber (Site_C \u2192 Site_B)-",
+      "to_node": "egress fused spans in Site_B"
+    },
+    {
+      "from_node": "egress fused spans in Site_B",
+      "to_node": "fiber (Site_B \u2192 Site_A)-"
+    },
+    {
+      "from_node": "roadm Site_C",
+      "to_node": "fiber (Site_C \u2192 Site_B)-"
+    },
+    {
+      "from_node": "fiber (Site_B \u2192 Site_C)-",
+      "to_node": "roadm Site_C"
+    },
+    {
+      "from_node": "trx Site_A",
+      "to_node": "roadm Site_A"
+    },
+    {
+      "from_node": "roadm Site_A",
+      "to_node": "trx Site_A"
+    },
+    {
+      "from_node": "trx Site_C",
+      "to_node": "roadm Site_C"
+    },
+    {
+      "from_node": "roadm Site_C",
+      "to_node": "trx Site_C"
+    }
+  ]
+}

gnpy/example-data/initial_spectrum1.json

@@ -0,0 +1,12 @@
+{
+      "spectrum":[
+            {
+            "f_min": 191.35e12,
+            "f_max": 195.1e12,
+            "baud_rate": 32e9,
+            "slot_width": 50e9,
+            "roll_off": 0.15,
+            "tx_osnr": 40
+            }
+      ]
+}

gnpy/example-data/initial_spectrum2.json

@@ -0,0 +1,23 @@
+{
+      "spectrum":[
+            {
+            "f_min": 191.4e12,
+            "f_max":193.1e12,
+            "baud_rate": 32e9,
+            "slot_width": 50e9,
+            "delta_pdb": 0,
+            "roll_off": 0.15,
+            "tx_osnr": 40,
+            "label": "mode_1"
+            },
+            {
+            "f_min": 193.1625e12,
+            "f_max":195e12,
+            "baud_rate": 64e9,
+            "slot_width": 75e9,
+            "roll_off": 0.15,
+            "tx_osnr": 40,
+            "label": "mode_2"
+            }
+      ]
+}

gnpy/example-data/meshTopologyExampleV2_services.json

@@ -0,0 +1,268 @@
+{
+  "path-request": [
+    {
+      "request-id": "0",
+      "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",
+          "trx_type": "Voyager",
+          "trx_mode": null,
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 50000000000.0,
+          "max-nb-of-channel": 80,
+          "output-power": 0.0012589254117941673,
+          "path_bandwidth": 100000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "1",
+      "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",
+          "trx_type": "Voyager",
+          "trx_mode": "mode 1",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 50000000000.0,
+          "max-nb-of-channel": null,
+          "output-power": 0.0012589254117941673,
+          "path_bandwidth": 200000000000.0
+        }
+      },
+      "explicit-route-objects": {
+        "route-object-include-exclude": [
+          {
+            "explicit-route-usage": "route-include-ero",
+            "index": 0,
+            "num-unnum-hop": {
+              "node-id": "roadm Brest_KLA",
+              "link-tp-id": "link-tp-id is not used",
+              "hop-type": "LOOSE"
+            }
+          },
+          {
+            "explicit-route-usage": "route-include-ero",
+            "index": 1,
+            "num-unnum-hop": {
+              "node-id": "roadm Lannion_CAS",
+              "link-tp-id": "link-tp-id is not used",
+              "hop-type": "LOOSE"
+            }
+          },
+          {
+            "explicit-route-usage": "route-include-ero",
+            "index": 2,
+            "num-unnum-hop": {
+              "node-id": "roadm Lorient_KMA",
+              "link-tp-id": "link-tp-id is not used",
+              "hop-type": "LOOSE"
+            }
+          },
+          {
+            "explicit-route-usage": "route-include-ero",
+            "index": 3,
+            "num-unnum-hop": {
+              "node-id": "roadm Vannes_KBE",
+              "link-tp-id": "link-tp-id is not used",
+              "hop-type": "LOOSE"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "request-id": "3",
+      "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",
+          "trx_type": "vendorA_trx-type1",
+          "trx_mode": "mode 1",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 50000000000.0,
+          "max-nb-of-channel": null,
+          "output-power": null,
+          "path_bandwidth": 60000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "4",
+      "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",
+          "trx_type": "vendorA_trx-type1",
+          "trx_mode": null,
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 75000000000.0,
+          "max-nb-of-channel": null,
+          "output-power": 0.0019952623149688794,
+          "path_bandwidth": 150000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "5",
+      "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",
+          "trx_type": "vendorA_trx-type1",
+          "trx_mode": "mode 2",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 75000000000.0,
+          "max-nb-of-channel": 63,
+          "output-power": 0.0019952623149688794,
+          "path_bandwidth": 20000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "6",
+      "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",
+          "trx_type": "Voyager",
+          "trx_mode": "mode 1",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 50000000000.0,
+          "max-nb-of-channel": 76,
+          "output-power": 0.001,
+          "path_bandwidth": 300000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "7",
+      "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",
+          "trx_type": "Voyager",
+          "trx_mode": "mode 1",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 50000000000.0,
+          "max-nb-of-channel": 76,
+          "output-power": 0.001,
+          "path_bandwidth": 400000000000.0
+        }
+      }
+    },
+    {
+      "request-id": "7b",
+      "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",
+          "trx_type": "Voyager",
+          "trx_mode": "mode 1",
+          "effective-freq-slot": [
+            {
+              "N": null,
+              "M": null
+            }
+          ],
+          "spacing": 75000000000.0,
+          "max-nb-of-channel": 50,
+          "output-power": 0.001,
+          "path_bandwidth": 400000000000.0
+        }
+      }
+    }
+  ],
+  "synchronization": [
+    {
+      "synchronization-id": "3",
+      "svec": {
+        "relaxable": "false",
+        "disjointness": "node link",
+        "request-id-number": [
+          "3",
+          "1"
+        ]
+      }
+    },
+    {
+      "synchronization-id": "4",
+      "svec": {
+        "relaxable": "false",
+        "disjointness": "node link",
+        "request-id-number": [
+          "4",
+          "5"
+        ]
+      }
+    }
+  ]
+}

gnpy/example-data/raman_edfa_example_network.json

@@ -0,0 +1,117 @@
+{
+  "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": 224.403e-3,
+            "frequency": 205e12,
+            "propagation_direction": "counterprop"
+          },
+          {
+            "power": 231.135e-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": "Fused1",
+      "type": "Fused",
+      "params": {
+        "loss": 0
+      },
+      "metadata": {
+        "location": {
+          "latitude": 1.5,
+          "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": "Fused1"
+    },
+    {
+      "from_node": "Fused1",
+      "to_node": "Edfa1"
+    },
+    {
+      "from_node": "Edfa1",
+      "to_node": "Site_B"
+    }
+  ]
+}

gnpy/example-data/sim_params.json

@@ -0,0 +1,13 @@
+{
+  "raman_params": {
+    "flag": true,
+    "result_spatial_resolution": 10e3,
+    "solver_spatial_resolution": 50
+  },
+  "nli_params": {
+    "method": "ggn_spectrally_separated",
+    "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
+    ]
+}