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

Merge pull request #256 from jktjkt/docs

Browse Source 
Documentation fixes (plus an equipment.Fiber.beta2 change)
This commit is contained in:
Jan Kundrát
2019-06-11 10:45:23 +02:00
committed by GitHub
parent 5be30d89a7 89d666948e
commit a3c7811e9d
6 changed files with 75 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/conf.py
View File

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

60
docs/source/gnpy.core.rst
View File

@@ -4,10 +4,39 @@ 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\.exceptions module
-----------------------------
.. automodule:: gnpy.core.exceptions
:members:
:undoc-members:
:show-inheritance:
@@ -16,30 +45,34 @@ gnpy\.core\.execute module
--------------------------
.. automodule:: gnpy.core.execute
:members:
:undoc-members:
:show-inheritance:
gnpy\.core\.info module
-----------------------
.. automodule:: gnpy.core.info
:members:
:undoc-members:
:show-inheritance:
gnpy\.core\.network module
--------------------------
.. automodule:: gnpy.core.network
:members:
:undoc-members:
:show-inheritance:
gnpy\.core\.node module
-----------------------
.. automodule:: gnpy.core.node
gnpy\.core\.request module
--------------------------
.. automodule:: gnpy.core.request
:members:
:undoc-members:
:show-inheritance:
gnpy\.core\.service_sheet module
--------------------------------
.. automodule:: gnpy.core.service_sheet
:members:
:undoc-members:
:show-inheritance:
@@ -48,23 +81,14 @@ gnpy\.core\.units module
------------------------
.. automodule:: gnpy.core.units
:members:
:undoc-members:
:show-inheritance:
gnpy\.core\.utils module
------------------------
.. automodule:: gnpy.core.utils
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: gnpy.core
:members:
:undoc-members:
:show-inheritance:

3
docs/source/gnpy.rst
View File

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

54
gnpy/core/elements.py
View File

@@ -7,11 +7,11 @@ gnpy.core.elements
This module contains standard network elements.
A network element is a Python callable. It takes a .info.SpectralInformation
A network element is a Python callable. It takes a :class:`.info.SpectralInformation`
object and returns a copy with appropriate fields affected. This structure
represents spectral information that is "propogated" by this network element.
Network elements must have only a local "view" of the network and propogate
SpectralInformation using only this information. They should be independent and
:class:`.info.SpectralInformation` using only this information. They should be independent and
self-contained.
Network elements MUST implement two attributes .uid and .name representing a
@@ -290,12 +290,12 @@ class Fiber(Node):
@property
def fiber_loss(self):
# dB fiber loss, not including padding attenuator
"""Fiber loss in dB, not including padding attenuator"""
return self.loss_coef * self.length + self.con_in + self.con_out
@property
def loss(self):
#total loss incluiding padding att_in: useful for polymorphism with roadm loss
"""total loss including padding att_in: useful for polymorphism with roadm loss"""
return self.loss_coef * self.length + self.con_in + self.con_out + self.att_in
@property
@@ -320,8 +320,10 @@ class Fiber(Node):
def carriers(self, loc, attr):
"""retrieve carriers information
loc = (in, out) of the class element
attr = (ase, nli, signal, total) power information"""
:param loc: (in, out) of the class element
:param attr: (ase, nli, signal, total) power information
"""
if not (loc in ('in', 'out') and attr in ('nli', 'signal', 'total', 'ase')):
yield None
return
@@ -337,31 +339,28 @@ class Fiber(Node):
else:
yield c.power._asdict().get(attr, None)
def beta2(self, ref_wavelength=None):
""" Returns beta2 from dispersion parameter.
def beta2(self, ref_wavelength=1550e-9):
"""Returns beta2 from dispersion parameter.
Dispersion is entered in ps/nm/km.
Disperion can be a numpy array or a single value. If a
value ref_wavelength is not entered 1550e-9m will be assumed.
ref_wavelength can be a numpy array.
Disperion can be a numpy array or a single value.
:param ref_wavelength: can be a numpy array; default: 1550nm
"""
# TODO|jla: discuss beta2 as method or attribute
wl = 1550e-9 if ref_wavelength is None else ref_wavelength
D = abs(self.dispersion)
b2 = (wl ** 2) * D / (2 * pi * c) # 10^21 scales [ps^2/km]
b2 = (ref_wavelength ** 2) * D / (2 * pi * c) # 10^21 scales [ps^2/km]
return b2 # s/Hz/m
def dbkm_2_lin(self):
""" calculates the linear loss coefficient
"""
# alpha_pcoef is linear loss coefficient in dB/km^-1
# alpha_acoef is linear loss field amplitude coefficient in m^-1
"""calculates the linear loss coefficient"""
# linear loss coefficient in dB/km^-1
alpha_pcoef = self.loss_coef
# linear loss field amplitude coefficient in m^-1
alpha_acoef = alpha_pcoef / (2 * 10 * log10(exp(1)))
return alpha_pcoef, alpha_acoef
def _psi(self, carrier, interfering_carrier):
""" Calculates eq. 123 from arXiv:1209.0394.
"""
"""Calculates eq. 123 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__"""
if carrier.num_chan == interfering_carrier.num_chan: # SCI
psi = arcsinh(0.5 * pi**2 * self.asymptotic_length
* abs(self.beta2()) * carrier.baud_rate**2)
@@ -375,8 +374,9 @@ class Fiber(Node):
return psi
def _gn_analytic(self, carrier, *carriers):
""" Computes the nonlinear interference power on a single carrier.
The method uses eq. 120 from arXiv:1209.0394.
"""Computes the nonlinear interference power on a single carrier.
The method uses eq. 120 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__.
:param carrier: the signal under analysis
:param carriers: the full WDM comb
:return: carrier_nli: the amount of nonlinear interference in W on the under analysis
@@ -557,8 +557,10 @@ class Edfa(Node):
def carriers(self, loc, attr):
"""retrieve carriers information
loc = (in, out) of the class element
attr = (ase, nli, signal, total) power information"""
:param loc: (in, out) of the class element
:param attr: (ase, nli, signal, total) power information
"""
if not (loc in ('in', 'out') and attr in ('nli', 'signal', 'total', 'ase')):
yield None
return
@@ -575,7 +577,7 @@ class Edfa(Node):
yield c.power._asdict().get(attr, None)
def interpol_params(self, frequencies, pin, baud_rates, pref):
"""interpolate SI channel frequencies with the edfa dgt and gain_ripple frquencies from json
"""interpolate SI channel frequencies with the edfa dgt and gain_ripple frquencies from JSON
set the edfa class __init__ None parameters :
self.channel_freq, self.nf, self.interpol_dgt and self.interpol_gain_ripple
"""
@@ -674,7 +676,7 @@ class Edfa(Node):
return self.interpol_nf_ripple + nf_avg # input VOA = 1 for 1 NF degradation
def noise_profile(self, df):
""" noise_profile(bw) computes amplifier ase (W) in signal bw (Hz)
"""noise_profile(bw) computes amplifier ase (W) in signal bw (Hz)
noise is calculated at amplifier input
:bw: signal bandwidth = baud rate in Hz
@@ -829,7 +831,7 @@ class Edfa(Node):
return g1st - voa + array(self.interpol_dgt) * dgts3
def propagate(self, pref, *carriers):
"""add ase noise to the propagating carriers of SpectralInformation"""
"""add ASE noise to the propagating carriers of :class:`.info.SpectralInformation`"""
pin = array([c.power.signal+c.power.nli+c.power.ase for c in carriers]) # pin in W
freq = array([c.frequency for c in carriers])
brate = array([c.baud_rate for c in carriers])

2
gnpy/core/info.py
View File

@@ -5,7 +5,7 @@
gnpy.core.info
==============
This module contains classes for modelling SpectralInformation.
This module contains classes for modelling :class:`SpectralInformation`.
'''

6
gnpy/core/node.py
View File

@@ -8,13 +8,13 @@ gnpy.core.node
This module contains the base class for a network element.
Strictly, a network element is any callable which accepts an immutable
.info.SpectralInformation object and returns a .info.SpectralInformation object
(a copy.)
:class:`.info.SpectralInformation` object and returns an :class:`.info.SpectralInformation` object
(a copy).
Network elements MUST implement two attributes .uid and .name representing a
unique identifier and a printable name.
This base class provides a mode convenient way to define a network element
This base class provides a more convenient way to define a network element
via subclassing.
'''