Merge pull request #302 from Telecominfraproject/develop

Merge develop into master in preparation for the 1.8 release

Highlights for the upcoming release:

- Raman simulation
- automatic building of Docker images
- bugfixes, refactoring, CI and docs improvements

.docker-entry.sh

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

.docker-travis.sh

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

.travis.yml

@@ -1,15 +1,27 @@
 dist: xenial
 sudo: false
 language: python
+services: docker
 python:
   - "3.6"
   - "3.7"
-# command to install dependencies
-install:
+install: skip
+script:
   - python setup.py install
   - pip install pytest-cov rstcheck
-script:
   - pytest --cov-report=xml --cov=gnpy
   - rstcheck --ignore-roles cite --ignore-directives automodule --recursive --ignore-messages '(Duplicate explicit target name.*)' .
+  - ./examples/transmission_main_example.py
+  - ./examples/path_requests_run.py
+  - ./examples/transmission_main_example.py examples/raman_edfa_example_network.json --sim examples/sim_params.json --show-channels
+  - sphinx-build docs/ x-throwaway-location
 after_success:
   - bash <(curl -s https://codecov.io/bash)
+jobs:
+  include:
+    - stage: test
+      name: Docker image
+      script:
+        - git fetch --unshallow
+        - ./.docker-travis.sh
+        - docker images

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.7-slim
+COPY . /oopt-gnpy
+WORKDIR /oopt-gnpy
+RUN python setup.py install
+WORKDIR /shared/examples
+ENTRYPOINT ["/oopt-gnpy/.docker-entry.sh"]
+CMD ["/bin/bash"]

Excel_userguide.rst

@@ -19,8 +19,8 @@ In order to work the excel file MUST contain at least 2 sheets:
 Nodes sheet
 -----------
 
-Nodes sheet contains seven columns.
-Each line represents a 'node' (ROADM site or an in line amplifier site ILA)::
+Nodes sheet contains nine columns.
+Each line represents a 'node' (ROADM site or an in line amplifier site ILA or a Fused)::
 
   City (Mandatory) ; State ; Country ; Region ; Latitude ; Longitude ; Type
 
@@ -38,6 +38,9 @@ Each line represents a 'node' (ROADM site or an in line amplifier site ILA)::
 
 - *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**
 
 
@@ -166,6 +169,7 @@ This generates a text file meshTopologyExampleV2_eqt_sheet.txt  whose content ca
 - **amp type** is not mandatory. 
   If filled it must contain types listed in `eqpt_config.json <examples/eqpt_config.json>`_ in "Edfa" list "type_variety".
   If 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.

README.rst

@@ -41,6 +41,33 @@ Branches and Tagged Releases
 How to Install
 --------------
 
+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/examples#
+
+On Windows, launch from Powershell as:
+
+.. code-block:: powershell
+
+    PS C:\> docker run -it --rm --volume ${PWD}:/shared telecominfraproject/oopt-gnpy
+    root@89784e577d44:/shared/examples#
+
+In both cases, a directory named ``examples/`` 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.
+
+Using Python on your computer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
    **Note**: `gnpy` supports Python 3 only. Python 2 is not supported.
    `gnpy` requires Python ≥3.6
 
@@ -105,7 +132,6 @@ executes without a ``ModuleNotFoundError``, you have successfully installed
 
     $ python -c 'import gnpy' # attempt to import gnpy
 
-    $ cd oopt-gnpy
     $ pytest                  # run tests
 
 Instructions for First Use
@@ -118,7 +144,7 @@ fully-functional programs.
 
     **Note**: *If you are a network operator or involved in route planning and
     optimization for your organization, please contact project maintainer Jan
-    Kundrát <jan.kundrat@telecominfraproject>. gnpy is looking for users with
+    Kundrát <jan.kundrat@telecominfraproject.com>. gnpy is looking for users with
     specific, delineated use cases to drive requirements for future
     development.*
 
@@ -417,10 +443,15 @@ existing parameters:
 +--------------------------+-----------+---------------------------------------------+
 | ``add_drop_osnr``        | (number)  | OSNR contribution from the add/drop ports   |
 +--------------------------+-----------+---------------------------------------------+
-| ``restrictions``         | (strings) | Authorized type_variety of amplifier for    |
-|                          |           | booster or preamp.                          |
-|                          |           | Listed type_variety MUST be defined in the  |
-|                          |           | Edfa catalog.                               |
+| ``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.                                     |
 +--------------------------+-----------+---------------------------------------------+
 
 The ``SpectralInformation`` object can be configured as follows. The user can
@@ -470,6 +501,17 @@ 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
+
+     $ ./examples/transmission_main_example.py \
+       examples/raman_edfa_example_network.json \
+       --sim examples/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 <examples/raman_edfa_example_network.json>`_.
+General numeric parameters for simulaiton control are provided in the `examples/sim_params.json <examples/sim_params.json>`_.
+
 Use `examples/path_requests_run.py <examples/path_requests_run.py>`_ to run multiple optimizations as follows:
 
 .. code-block:: shell

docs/biblio.bib

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

docs/conf.py

@@ -173,5 +173,4 @@
      'Miscellaneous'),
 ]
 
-
-
+autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'show-inheritance']

docs/source/gnpy.core.rst

@@ -4,67 +4,91 @@ gnpy\.core package
 Submodules
 ----------
 
+gnpy\.core\.ansi_escapes module
+-------------------------------
+
+.. automodule:: gnpy.core.ansi_escapes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gnpy\.core\.convert module
+--------------------------
+
+.. automodule:: gnpy.core.convert
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 gnpy\.core\.elements module
 ---------------------------
 
 .. automodule:: gnpy.core.elements
+
+gnpy\.core\.equipment module
+----------------------------
+
+.. automodule:: gnpy.core.equipment
     :members:
     :undoc-members:
     :show-inheritance:
 
-gnpy\.core\.execute module
---------------------------
+gnpy\.core\.exceptions module
+-----------------------------
 
-.. automodule:: gnpy.core.execute
+.. automodule:: gnpy.core.exceptions
     :members:
     :undoc-members:
     :show-inheritance:
 
+gnpy\.core\.execute module
+--------------------------
+
+.. automodule:: gnpy.core.execute
+
 gnpy\.core\.info module
 -----------------------
 
 .. automodule:: gnpy.core.info
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.network module
 --------------------------
 
 .. automodule:: gnpy.core.network
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.node module
 -----------------------
 
 .. automodule:: gnpy.core.node
+
+gnpy\.core\.request module
+--------------------------
+
+.. automodule:: gnpy.core.request
     :members:
     :undoc-members:
     :show-inheritance:
 
-gnpy\.core\.units module
-------------------------
+gnpy\.core\.service_sheet module
+--------------------------------
 
-.. automodule:: gnpy.core.units
+.. automodule:: gnpy.core.service_sheet
     :members:
     :undoc-members:
     :show-inheritance:
 
+gnpy\.core\.units module
+------------------------
+
+.. automodule:: gnpy.core.units
+
 gnpy\.core\.utils module
 ------------------------
 
 .. automodule:: gnpy.core.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 
 Module contents
 ---------------
 
 .. automodule:: gnpy.core
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/gnpy.rst

@@ -12,6 +12,3 @@ Module contents
 ---------------
 
 .. automodule:: gnpy
-    :members:
-    :undoc-members:
-    :show-inheritance: