and of the class referenced in the documentation
example-data folder is not accessible from the
generated pages on readthedocs. So use hyperlinks
to the files github repo.
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I135e2cb0b0d28fecffcbcbfec9a9d6c8cb5c7347
But enable the user to still input its own default file with a new
'default_config_from_json' attribute useable in fixed and variable gain
amplifiers.
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I773682ae6daa1025007fc051582e779986982838
An approximated version of the GGN is implemented to reduce the computational time enabling fast multi-band transmission simulations
Change-Id: I2951a878aa04b5eb4a33ba86d626a788c4cbb100
add some text in the docs to explain that tilt can be expressed
vs freq or lambda depending on context:
advanced_model expresses dgt as a function of frequency,
while tilt target is still defined vs wavelength (common usage).
Change the variable to have explicit name when it is per wavelength,
or add a comment to help identifyper wavelength or per frequency
variables.
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I7727f00b38244152b95954e981cc9da096bb3d1d
Historically, we've been using the RTD theme on the RTD site which hosts
the docs for us, and a Sphinx-default, "Alabaster" theme for other docs
builds. Doing that however started failing:
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1096, in handle_page
output = self.templates.render(templatename, ctx)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/readthedocs_ext/readthedocs.py", line 181, in rtd_render
content = old_render(template, render_context)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 194, in render
return self.environment.get_template(template).render(context)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 1301, in render
self.environment.handle_exception()
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 936, in handle_exception
raise rewrite_traceback_stack(source=source)
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
{%- extends "layout.html" %}
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/classic/layout.html", line 10, in top-level template code
{%- extends "basic/layout.html" %}
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 170, in top-level template code
{%- block content %}
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'content'
{%- block sidebar2 %}{{ sidebar() }}{% endblock %}
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'sidebar2'
{%- block sidebar2 %}{{ sidebar() }}{% endblock %}
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/sandbox.py", line 393, in call
return __context.call(__obj, *args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/runtime.py", line 777, in _invoke
rv = self._func(*arguments)
^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 63, in template
{%- include sidebartemplate %}
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 215, in get_source
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: about.html
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/cmd/build.py", line 281, in build_main
app.build(args.force_all, args.filenames)
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/application.py", line 347, in build
self.builder.build_update()
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 310, in build_update
self.build(to_build,
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 376, in build
self.write(docnames, list(updated_docnames), method)
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 571, in write
self._write_serial(sorted(docnames))
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 581, in _write_serial
self.write_doc(docname, doctree)
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 672, in write_doc
self.handle_page(docname, ctx, event_arg=doctree)
File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1103, in handle_page
raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page about-project.
Reason: TemplateNotFound('about.html')
Theme error:
An error happened in rendering the page about-project.
Reason: TemplateNotFound('about.html')
I have no clue what that means because we have never requested this
`about.html`, nor do we reference that file from anywhere. Chances are
that it's "just" some version pinning/compatibility issue, but hey --
why mess with that when there's a perfectly good default theme that
we're using for other purposes already.
As a side effect, this also solves that long-standing issue that Esther
reported where the tables have overly long lines. Apparently, it's a
theme-specific misfeature (readthedocs/sphinx_rtd_theme/#117), and the
Alabaster one doesn't suffer from that.
All hail alabaster!
Change-Id: I857890f29f14b7c0f66bca201c9a9c1b1cbf8841
In tox v4, "reuse of environments" was disabled [1]. This is then later
explained [2] to refer to exactly that thing which we were using for
inheriting the dependencies from the top-level testenv all the way to
the docs build. That's why the docs build in GitHub CI started failing.
IMHO, The Correct Way™ of specifying what dependencies are used for
which feature are the so-called "extra dependencies". Once they are in
place, it is be possible to install gnpy via, e.g., `pip install
oopt-gnpy[docs]`. However, this process is (as far as I can tell)
incompatible with `requirements.txt`; all my attempts at using the
standard dependency syntax in that file have failed for me.
So, in order to make this happen, let's move all the dependencies from a
more-or-less ad-hoc collection of files to this declarative approach
right in setup.cfg. That way, the deps are listed on a single place, in
a declarative manner, and as a result, the installation is now a trivial
pip oneliner.
As a result, one can also remove that duplication of dependencies in
docs requirements.
[1] https://tox.wiki/en/4.11.4/upgrading.html#reuse-of-environments
[2] https://tox.wiki/en/4.11.4/upgrading.html#packaging-configuration-and-inheritance
Change-Id: I34aa0c71e993b39e2b805a7de40e133b4d290318
Fixes: 47c89626 fix docs requirements
The chromatic dispersion and dispersion slope can be provided as a single values evaluated at the fiber reference frequency or in a dictionary containing the dispersion values evaluated at multiple frequencies:
"dispersion": {"value": [], "frequency": []}
Change-Id: I81429484dd373cc49bd9baf013247782ba1912fd
The nonlinear coefficient can be expressed at the reference frequency and will be scaled in frequency using the scaling rule of the effective area
Change-Id: Id103b227472702776bda17ab0a2a120ecfbf7473
1. Effective area scaling along frequency is implemented by means of a technological model.
2. Raman gain coefficient is extended coherently, including the scaling due to the pump frequency.
Change-Id: I4e8b79697500ef0f73ba2f969713d9bdb3e9949c
Co-authored-by: Giacomo Borraccini <giacomo.borraccini@polito.it>
Constant power per slot_width uses the slot width instead of
baud rate compared to PSD.
This is the equalization used in OpenROADM
add tests for constant power per slot width equalization
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: Ie350e4c15cb6b54c15e418556fe33e72486cb134
On a ROADM, the code would previously set the same per-carrier power
regardless of the channel spectrum width. With this patch, carriers are
equalized either by their:
- absolute power (same as before),
- power spectral density (PSD).
Also, it's possible to apply a per-channel power offset (in dB) which
will be applied to a specified channel on top of the selected
power-level or PSD strategy. The same offset can be also selected
through the `--spectrum` option via the `default_pdb` parameter.
The equalization policy can be set via the ROADM model (in the equipment
config) as well as on a per-instance basis.
The PSD is defined as the absolute power over a spectral bandwidth,
where the spectral bandwidth corresponds to the actual spectrum
occupation (without any applicable guard bands), as approximated by the
symbol rate. PSD is specified in mW/GHz. As an example, for a 32 GBaud
signal at 0.01 mW, the PSD is 0.01/32 = 3.125e-4 mW/GHz.
This has some implications on the power sweep and ROADM behavior. Same
as previously (with absolute power targets), the ROADM design determines
the power set points. Target power is usually the best (highest) power
that can be supported by the ROADMs, especially the Add/Drop and express
stages' losses, with the goal to maximize the power at the booster's
input. As such, the `--power` option (or the power sweep) doesn't
manipulate with ROADM's target output power, but only with the output
power of the amplifiers. With PSD equalization, the `--power` option is
interpreted as the power of the reference channel defined in equipment
config's `SI` container, and its PSD is used for propagation. Power
sweep is interpreted in the same way, e.g.:
"SI":[{
"f_min": 191.3e12,
"baud_rate": 32e9,
"f_max":195.1e12,
"spacing": 50e9,
"power_dbm": 0,
"power_range_db": [-1,1,1],
"roll_off": 0.15,
"tx_osnr": 40,
"sys_margins": 2
}],
...and with the PSD equalization in a ROADM:
{
"uid": "roadm A",
"type": "Roadm",
"params": {
"target_psd_out_mWperGHz": 3.125e-4,
}
},
{
"uid": "edfa in roadm A to toto",
"type": "Edfa",
"type_variety": "standard_medium_gain",
"operational": {
"gain_target": 22,
"delta_p": 2,
"tilt_target": 0.0,
"out_voa": 0
}
},
then we use the power steps of the power_range_db to compute resulting
powers of each carrier out of the booster amp:
power_db = psd2powerdbm(target_psd_out_mWperGHz, baud_rate)
sweep = power_db + delta_power for delta_power in power_range_db
Assuming one 32Gbaud and one 64Gbaud carriers:
32 Gbaud 64 Gbaud
roadmA out power
(sig+ase+nli) -20dBm -17dBm
EDFA out power
range[
-1 1dBm 4dBm
0 2dBm 5dBm
1 3dBm 6dBm
]
Design case:
Design is performed based on the reference channel set defined in SI
in equipment config (independantly of equalization process):
"SI":[{
"f_min": 191.3e12,
"baud_rate": 32e9,
"f_max":195.1e12,
"spacing": 50e9,
"power_dbm": -1,
"power_range_db": [0,0,1],
"roll_off": 0.15,
"tx_osnr": 40,
"sys_margins": 2
}],
`delta_p` values of amps refer to this reference channel, but are applicable
for any baudrate during propagation, e.g.:
{
"uid": "roadm A",
"type": "Roadm",
"params": {
"target_psd_out_mWperGHz": 2.717e-4,
}
},
{
"uid": "edfa in roadm A to toto",
"type": "Edfa",
"type_variety": "standard_medium_gain",
"operational": {
"gain_target": 22,
"delta_p": 2,
"tilt_target": 0.0,
"out_voa": 0
}
},
Then the output power for a 64 Gbaud carrier will be +4 =
= lin2db(db2lin(power_dbm + delta_p)/32e9 * 64e9)
= lin2db(db2lin(power_dbm + delta_p) * 2)
= powerdbm + delta + 3 = 4 dBm
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: I28bcfeb72b0e74380b087762bb92ba5d39219eb3
The lumped losses are used in the computation of the loss/gain profile
through the fiber whether the Raman effect is considered or not. The
computed power profile is used to calculate the related NLI impairment.
Using the 'gn_model_analytic' method, the lumped losses are taken into
account as the contribution of an additional total loss at the end of
the fiber span. In case the 'ggn_spectrally_separated' is selected, the
method uses the computed power profile according to the specified z and
frequency arrays. The lumped losses are so considered within the NLI
power evolution along the fiber.
Change-Id: I73a6baa321aca4d041cafa180f47afed824ce267
Signed-off-by: Jan Kundrát <jan.kundrat@telecominfraproject.com>
Python 3.10 builds require a fix in Sphinx, so let's update all docs
dependencies while we're at this.
Unfortunately, the myst-parser requires docutils<0.18,>=0.15 so we
cannot take the latest and greatest of that one.
After this update, sphinxcontrib-bibtex now requires an explicit
reference to the .bib files directly in the config file. Let's remove
the one in the actual docs, then.
Bug: https://github.com/sphinx-doc/sphinx/pull/9513
Change-Id: I80f62131b25f3afa23351646001f6ce381723487
In this change, the RamanSolver is completely restructured in order to obtain a simplified and faster solution of the Raman equation. Additionally, the inter-channel Raman effect can be evaluated also in the standard fiber, when no Raman pumping is present. The same is true for the GGN model.
The Raman pump parameter pumps_loss_coef has been removed as it was not used. The loss coefficient value evaluated at the pump frequency can be included within the fiber loss_coef parameter.
This change induces variations in some expected test results as the Raman profile solution is calculated by a completely distinct algorithm. Nevertheless, these variations are negligible being lower than 0.1dB.
Change-Id: Iaa40fbb23c555571497e1ff3bf19dbcbfcadf96b
Gamma and the raman efficiency are calculated using the effective area if not provided. Both these parameters are managed as optional in json_io.py for backward compatibility.
Change-Id: Id7f1403ae33aeeff7ec464e4c7f9c1dcfa946827
As Gert proposed on the latest call, submitting patches could be a bit
high of a barrier to go over. Let's make it clear that we're here to
help those vendors who are willing to collaborate.
Change-Id: Ieac1c91480143c553ffb25dd1c46e94022bf5ba3
Jan: only add those parameter which are not being removed in future
patches and which have useful documentation that the user can plausibly
act on.
Change-Id: I02173f500fed8c065a30de5d23e318bce2a90c33
Co-authored-by: Jan Kundrát <jan.kundrat@telecominfraproject.com>
