doc fixes

docs/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# GNpy documentation build configuration file, created by
+# gnpy documentation build configuration file, created by
 # sphinx-quickstart on Mon Dec 18 14:41:01 2017.
 #
 # This file is execfile()d with the current directory set to its
@@ -47,8 +47,8 @@ source_suffix = ['.rst', '.md']
 master_doc = 'index'
 
 # General information about the project.
-project = 'GNpy'
+project = 'gnpy'
-copyright = '2017, Telecom InfraProject - OOPT PSE Group'
+copyright = '2018, Telecom InfraProject - OOPT PSE Group'
 author = 'Telecom InfraProject - OOPT PSE Group'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -120,7 +120,7 @@ html_sidebars = {
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'GNpydoc'
+htmlhelp_basename = 'gnpydoc'
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -147,7 +147,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'GNpy.tex', 'GNpy Documentation',
+    (master_doc, 'gnpy.tex', 'gnpy Documentation',
      'Telecom InfraProject - OOPT PSE Group', 'manual'),
 ]
 
@@ -157,7 +157,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'gnpy', 'GNpy Documentation',
+    (master_doc, 'gnpy', 'gnpy Documentation',
      [author], 1)
 ]
 
@@ -168,8 +168,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'GNpy', 'GNpy Documentation',
+    (master_doc, 'gnpy', 'gnpy Documentation',
-     author, 'GNpy', 'One line description of project.',
+     author, 'gnpy', 'One line description of project.',
      'Miscellaneous'),
 ]
 

docs/model.rst

@@ -0,0 +1,146 @@
+The QoT estimation in the PSE framework of TIP-OOPT
+=======================================================
+
+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:: biblio.bib