Right now, the documentation and code disagree on which values are mandatory, what exactly they mean, etc. Let's try to use a set of YANG models for verification.
FIXME: What is missing
- [x] ROADMs
- [ ] EDFA parameters
- [x] TODO: implement DGT (et al) indirection
- [x] check that this set of EDFA parameters makes sense for each possible simulation parameter set
- [x] rework for #227
- [x] EDFA maximal gain -- this one doesn't appear to be used by the code anywhere!, which confuses me
- [x] Raman support (preliminary, on-par with what we already have now in
devel)
- [x] Fibers
- [ ] Fiber.dispersion and Fiber.gamma range validation. Also, how do we describe Fiber type's gamma?
- [x] Fiber operational data
- [x] Transponders
- [x] Transceiver's tx roll-off; how exactly is this defined? I only understand it "intuitively".
- [x] minimal required OSNR (#298)
- [x] topology
- [x] replace
SpectralInfo
- [x] default transponder for
transmission_main_example
- [x] unclear how to reconcile the
f_min/f_max of the SI and TX
- [x] default spectrum allocation (autodesign assumes full allocation -> cannot use transponders)
- [ ] CI coverage:
- [x] YANG validation & linting
- [ ] positive and negative JSON samples for constraint testing
- "ignoring the YANG-specificity":
- or just use
yanglint proper, because it works (but might be a bit painful to package for CI and users),
- [x] or use yangson, a native Python library
- [x] prepare the JSON data in the
ietf-yang-library format
- [x] input validation
- this one should be in Python, not via
yanglint for dependency reasons
- [ ] conversion scripts
- [ ] use this as an input format
- [ ] generate docs from YANG
descriptions
Equipment Library
The first step in adding YANG description for gnpy's input is the equipment library (tip-photonic-equipment). It contains data about all defined EDFA and Fiber types. This is supposed to be functionally equivalent to the equpt_config.json. The JSON structure has changed because I (much) value YANG readability over being directly compatible with our previous format (there will be a conversion script anyway).
The core idea of this model is to describe capabilities of the simulation engine as it exists, which means that the individual choice/case statements mirror our different "simulation input parameters". The user is not expected to do any augmentations -- just describe the amplifiers, fiber, etc, with data.
The pre-YANG code actually split stuff from equpt_config.json into additional JSON files for "fancy bits", such as the DGT LUT. That's something that, IMHO, does not make sense when we're willing to ship with machine-validation of the complete input set. So instead of deferring to another JSON file for the NF-/gain-ripple/DGT, let's move everything in-line into the input data. This has one obvious downside in making the amplifier data a bit too verbose. There were several options:
-
Ignore the human-friendliness and push everything into the amplifier description. This is nice and self-contained, but the data are going to be very, very long, and the majority of the WG was worried that it would make human editing too difficult.
-
Move everything to a side-loaded JSON file. This option separates out some numerical parameters from the equipment library, and therefore splits the configuration into two places. One of these places would be exempt from the YANG validation, and loaded via unspecified means. That's a no-go.
-
Put stuff into a YANG model, but use one level of indirection between the amplifier description and the numerical data.
As a compromise, we've chosen the last option.
In the real world, some "common fiber types" are well-defined by ITU, such as the SSMF. Esther tried to model this via a set of identities and YANG identityrefs. I think that there's no disadvantage in shipping these data as a default content of the YANG-formatted datastore, similarly to how the equipment library used to be structured prior to this patch. Once again, I'm following the pattern where the user can change any data without augmenting the YANG model. The only reason for editing/augmenting the (equipment) YANG model should be changes in our simulation engine, such as when adding different input parameters for NF calculations, or adding Raman amplification, etc.
The amplifier model has been reworked a bit (only in the YANG model for now, though). I've reduced the number of available "simulation parameters" to a reasonable minimum as suggested by Jean-Luc (cf. issue #227):
- a polynomial NF model
- a polynomial OSNR model ("OpenROADM")
- a simplified model for operators with NF_min and NF_max
- a dual-stage amplifier using any of the above
Topology Model
The topology model (tip-photonic-topology) uses leafrefs for "instantiating" actual nodes from models defined in the equipment library. The topology is unidirectional.
At first, I used an ad-hoc, custom topology for simplicity. This was changed in response to Jonas' comment; there's clearly no need to reinvent this particular wheel. Now the model builds on top of RFC8345.
Both ietf-network-topology and the associated ietf-network are needed. The augmentations make it a bit harder to see the YANG rendering of the resulting modules, but that's just how the IETF model was designed. There's nothing to fix on our side.
Unlike the current JSON, Fibers are not nodes anymore. They are implemented as nt:link augmentations.
Sample Data
To see how the (total, complete) input data to GNPy might look like, I'm including a simple JSON file which defines some amplifiers, fiber, transponders, etc., and uses them to build a very simple path. I think that there's plenty of stuff which is missing, but it shows something which passes the YANG validation.
YANG trees
Equipment Inventory
module: tip-photonic-equipment
+--rw amplifier* [type]
| +--rw type string
| +--rw (simulation)
| | +--:(polynomial-NF)
| | | +--rw polynomial-NF
| | | +--rw gain-min gain
| | | +--rw gain-flatmax power
| | | +--rw gain-max-extended power
| | | +--rw max-power-out power
| | | +--rw gain-ripple* db-ratio
| | | +--rw nf-ripple* db-ratio
| | | +--rw dynamic-gain-tilt* db-ratio
| | | +--rw nf-polynomial-coefficients
| | | +--rw a polynomial-coefficient
| | | +--rw b polynomial-coefficient
| | | +--rw c polynomial-coefficient
| | | +--rw d polynomial-coefficient
| | +--:(polynomial-OSNR)
| | | +--rw polynomial-OSNR
| | | +--rw gain-min gain
| | | +--rw gain-flatmax power
| | | +--rw gain-max-extended power
| | | +--rw max-power-out power
| | | +--rw gain-ripple* db-ratio
| | | +--rw nf-ripple* db-ratio
| | | +--rw dynamic-gain-tilt* db-ratio
| | | +--rw osnr-polynomial-coefficients
| | | +--rw a polynomial-coefficient
| | | +--rw b polynomial-coefficient
| | | +--rw c polynomial-coefficient
| | | +--rw d polynomial-coefficient
| | +--:(min-max-NF)
| | | +--rw min-max-NF
| | | +--rw gain-min gain
| | | +--rw gain-flatmax power
| | | +--rw gain-max-extended power
| | | +--rw max-power-out power
| | | +--rw gain-ripple* db-ratio
| | | +--rw nf-ripple* db-ratio
| | | +--rw dynamic-gain-tilt* db-ratio
| | | +--rw nf-min noise-figure
| | | +--rw nf-max noise-figure
| | +--:(raman)
| | | +--rw raman
| | | +--rw gain gain
| | | +--rw nf noise-figure
| | +--:(dual-stage)
| | +--rw dual-stage!
| | +--rw preamp -> /tip-photonic-equipment:amplifier/type
| | +--rw booster -> /tip-photonic-equipment:amplifier/type
| | +--rw gain-min power
| +--rw frequency-min? frequency <191.35>
| +--rw frequency-max? frequency <196.1>
| +--rw has-output-voa? boolean <false>
+--rw fiber* [type]
| +--rw type string
| +--rw dispersion decimal64
| +--rw gamma decimal64
+--rw transceiver* [type]
+--rw type string
+--rw frequency-min? frequency <191.35>
+--rw frequency-max? frequency <196.1>
+--rw mode* [name]
+--rw name string
+--rw baud-rate uint64
+--rw required-osnr db-ratio
+--rw tx-osnr db-ratio
+--rw grid-spacing frequency
+--rw tx-roll-off? decimal64
+--rw cost? uint32 <1>
Topology
module: tip-photonic-topology
augment /ietf-network:networks/ietf-network:network/ietf-network:network-types:
+--rw photonic-topology!
augment /ietf-network:networks/ietf-network:network/ietf-network-topology:link:
+--rw fiber
+--rw type -> /tip-photonic-equipment:fiber/tip-photonic-equipment:type
+--rw length decimal64
augment /ietf-network:networks/ietf-network:network/ietf-network:node:
+--rw (element)
| +--:(amplifier)
| | +--rw amplifier
| | +--rw model -> /tip-photonic-equipment:amplifier/tip-photonic-equipment:type
| | +--rw gain-target tip-photonic-equipment:gain
| | +--rw tilt-target tip-photonic-equipment:db-ratio
| +--:(concentrated-loss)
| | +--rw concentrated-loss
| | +--rw attenuation? tip-photonic-equipment:db-ratio <0.0>
| +--:(transceiver)
| +--rw transceiver
| +--rw model -> /tip-photonic-equipment:transceiver/tip-photonic-equipment:type
+--rw geo-location
| +--rw reference-frame
| | +--rw alternate-system? string {ietf-geo-location:alternate-systems}?
| | +--rw astronomical-body? string <earth>
| | +--rw geodetic-system
| | +--rw geodetic-datum? string <wgs-84>
| | +--rw coord-accuracy? decimal64
| | +--rw height-accuracy? decimal64
| +--rw (location)?
| | +--:(ellipsoid)
| | | +--rw latitude ietf-geo-location:degrees
| | | +--rw longitude ietf-geo-location:degrees
| | | +--rw height? decimal64
| | +--:(cartesian)
| | +--rw x decimal64
| | +--rw y decimal64
| | +--rw z? decimal64
| +--rw velocity
| | +--rw v-north? decimal64
| | +--rw v-east? decimal64
| | +--rw v-up? decimal64
| +--rw timestamp? ietf-yang-types:date-and-time
WIP
If this needs, say, -20dBm per channel at point A, and this means that there will also be exactly -20dBm per channel at points B, C and D (because there's no 
This way per-degree output power is made explicit by setting it at the egress part of each ROADM degree. The drawback is that this model requires 2×N ROADM elements per N-degree real-world ROADM node, and plenty of internal links.
172 Dec 23, 2022
42 Oct 07, 2022
39 Nov 03, 2022
8 Aug 28, 2022
67 Nov 14, 2022
91 Dec 21, 2022
78 Dec 28, 2022
1 Jan 14, 2022
0 Nov 22, 2021
49 Jan 07, 2023
2.3k Jan 03, 2023
35 Jan 06, 2023
38 Oct 21, 2022
7 Apr 13, 2022
1 Feb 10, 2022
100 Dec 20, 2022
2 May 30, 2022
5 Nov 05, 2022
312 Jan 08, 2023
126 Jul 13, 2022