diff --git a/docs/index.rst b/docs/index.rst index 8c831f49e..0aabd0716 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ in real-world mesh optical networks. It is based on the Gaussian Noise Model. cli_options amplifier_models_description json + json_instance_examples excel extending about-project diff --git a/docs/json.rst b/docs/json.rst index f4d1ce3b2..10fbdf6cf 100644 --- a/docs/json.rst +++ b/docs/json.rst @@ -11,9 +11,11 @@ Equipment Library Design and transmission parameters are defined in a dedicated json file. By default, this information is read from `gnpy/example-data/eqpt_config.json `_. -This file defines the equipment libraries that can be customized (EDFAs, fibers, and transceivers). +This file defines the equipment libraries that can be customized (Amplifiers, ROADMs, fibers, and transceivers). -It also defines the simulation parameters (spans, ROADMs, and the spectral information to transmit.) +It also defines the simulation parameters (spans and the spectral information to transmit.) + +Examples of instances are commented here :ref:`json instances examples`. EDFA ~~~~ diff --git a/docs/json_instance_examples.rst b/docs/json_instance_examples.rst new file mode 100644 index 000000000..07b84a931 --- /dev/null +++ b/docs/json_instance_examples.rst @@ -0,0 +1,824 @@ +.. _json-instance-examples: + +********************************************* +Equipment and Network description definitions +********************************************* + +1. Equipment description +######################## + +Equipment description defines equipment types and those parameters. +Description is made in JSON file with predefined structure. By default +the scripts **gnpy-transmission-example** and **path-request-run** uses +**eqpt_config.json** file present in `example-data`` folder. It +can be changed with **-e** or **--equipment** command line parameter. +Parsing of JSON file is made with +**gnpy.tools.json_io.load_equipment(equipment_file_path)** and return +value is a dictionary of format **dict[‘equipment type’][‘subtype’]=object** + +1.1. Structure definition +************************* + +1.1.1. Equipment types +********************** + +Every equipment type is defined in JSON equipment library root with according name and +array of parameters as value. + +possible types: + + - Edfa, + - Fiber, + - RamanFiber, + - Roadm, + - Transceiver + +.. code-block:: none + + {"Edfa": [...], + "Fiber": [...] + } + + +1.1.2. Equipment parameters and subtypes +***************************************** + + +Array of parameters is a list of objects with unordered parameter name +and its value definition. In case of multiple equipment subtypes each +object contains **"type_variety": ”type name”** name:value combination, +if only one subtype exists **"type_variety"** name is not mandatory and +it will be marked with **”default”** value. + +.. code-block:: json + + { + "Edfa": [{ + "type_variety": "std_medium_gain", + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 23, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": true + }, + { + "type_variety": "std_low_gain", + "type_def": "variable_gain", + "gain_flatmax": 16, + "gain_min": 8, + "p_max": 23, + "nf_min": 6.5, + "nf_max": 11, + "out_voa_auto": false, + "allowed_for_design": true + } + ], + "Fiber": [{ + "type_variety": "SSMF", + "dispersion": 1.67e-05, + "effective_area": 83e-12, + "pmd_coef": 1.265e-15 + } + ] + } + + + +1.2. Equipment parameters by type +********************************* + +1.2.1. Amplifier types +********************** + +Several types of amplfiers definition are possible: + +- `advanced_model` – with JSON file describing gain/noise figure tilt and + gain/noise figure ripple. **"advanced_config_from_json"** value + contains filename. + The corresponding file must be loaded with `--extra-config` option + in the **gnpy-transmission-example** or **path-request-run** scripts. + + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "high_detail_model_example", + "gain_flatmax": 25, + "gain_min": 15, + "p_max": 21, + "advanced_config_from_json": "std_medium_gain_advanced_config.json", + "out_voa_auto": false, + "allowed_for_design": false + } + ] + +- `variable_gain` – with JSON file describing gain figure tilt and gain/noise + figure ripple. Default config from GNPy is used for DGT, noise ripple and + gain ripple. User can input its own config with the + **"default_config_from_json"**. The corresponding file must be loaded with + `-extra-config option` in the **gnpy-transmission-example** or + **path-request-run** scripts. + Note that the extra_config must contain the frequency bandwidth of the + amplifier. ``f_min`` and ``f_max`` represent the boundary frequencies of + the amplification bandwidth (the entire channel must fit within this range). + if present in the amplifier equiment library definition, ``f_min`` and ``f_max`` + are used instead. + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "std_medium_gain", + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 23, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": true + }, + { + "type_variety": "user_defined", + "type_def": "variable_gain", + "f_min": 192.0e12, + "f_max": 195.9e12, + "gain_flatmax": 25, + "gain_min": 15, + "p_max": 21, + "nf_min": 6, + "nf_max": 10, + "default_config_from_json": "user_edfa_config.json", + "out_voa_auto": false, + "allowed_for_design": true + } + ] + +- `fixed_gain` – with default config from GNPy describing gain figure tilt and gain/noise + figure ripple. User can input its own config with the + **"default_config_from_json"**. + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "std_fixed_gain", + "type_def": "fixed_gain", + "gain_flatmax": 21, + "gain_min": 20, + "p_max": 21, + "nf0": 5.5, + "allowed_for_design": false + } + ] + +- `openroadm` – with default config from GNPy describing gain figure tilt and gain/noise + figure ripple. + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "openroadm_ila_low_noise", + "type_def": "openroadm", + "gain_flatmax": 27, + "gain_min": 12, + "p_max": 22, + "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62], + "allowed_for_design": false + } + ] + +- `openroadm_preamp` and `openroadm_booster` - with default config from GNPy + describing gain figure tilt and gain/noise figure ripple. + The model approximates the noise mask defined by OpenRoadm in :ref:`preamp and booster within an OpenROADM network`. + No extra parameters specific to the NF model are accepted. + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "openroadm_mw_mw_preamp", + "type_def": "openroadm_preamp", + "gain_flatmax": 27, + "gain_min": 0, + "p_max": 22, + "pmd": 0, + "pdl": 0, + "allowed_for_design": false + }, + { + "type_variety": "openroadm_mw_mw_booster", + "type_def": "openroadm_booster", + "gain_flatmax": 32, + "gain_min": 0, + "p_max": 22, + "pmd": 0, + "pdl": 0, + "allowed_for_design": false + } + ] + +Composed amplifier types +------------------------ + +- `multiband` + This type enables the definition of multiband amplifiers that consist of multiple + single-band amplifier elements, with each amplifier responsible for amplifying a + different portion of the spectrum. The types of single-band amplifiers that can be + included in these multiband amplifiers are specified, allowing for multiple options + to be available for the same spectrum band (for instance, providing several permitted + type varieties for both the C-band and the L-band). The actual element utilizing the + type_variety must implement only one option for each band. + +.. code-block:: json-object + + "Edfa":[{ + "type_variety": "std_low_gain", + "f_min": 191.25e12, + "f_max": 196.15e12, + "type_def": "variable_gain", + "gain_flatmax": 16, + "gain_min": 8, + "p_max": 21, + "nf_min": 7, + "nf_max": 11, + "out_voa_auto": false, + "allowed_for_design": true + }, { + "type_variety": "std_medium_gain_C", + "f_min": 191.225e12, + "f_max": 196.125e12, + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 21, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": false + }, + { + "type_variety": "std_medium_gain_L", + "f_min": 186.5e12, + "f_max": 190.1e12, + "type_def": "variable_gain", + "gain_flatmax": 26, + "gain_min": 15, + "p_max": 21, + "nf_min": 6, + "nf_max": 10, + "out_voa_auto": false, + "allowed_for_design": true + }, + { + "type_variety": "std_medium_gain_multiband", + "type_def": "multi_band", + "amplifiers": [ + "std_low_gain", + "std_medium_gain_C", + "std_medium_gain_L" + ], + "allowed_for_design": false + } + ] + +- `dual_stage` + This model allows for the combination of pre-defined amplifiers (`advanced_model`, + `variable_gain`, `fixed_gain`) into a cascade configuration, which consists of + any two amplifiers already described in the library. + + - The preamp_variety specifies the type variety for the first stage. + - The booster_variety defines the type variety for the second stage. + + One potential application is the creation of a simplified Raman-EDFA hybrid + amplifier, where a fixed-gain amplifier with a very low to negative noise figure + serves as the Raman amplifier preamp, and an EDFA serves as the booster. + Please note that there is currently no connection between the dual-stage + amplifier definition and the RamanFiber definition for modeling Raman + amplification. Users should avoid using dual-stage amplifiers modelling Raman + with a fixed_gain amplifier and RamanFiber simultaneously when defining a + Raman-amplified link. + +.. code-block:: json-object + + "Edfa":[ { + "type_variety": "std_low_gain", + "type_def": "variable_gain", + "gain_flatmax": 16, + "gain_min": 8, + "p_max": 23, + "nf_min": 6.5, + "nf_max": 11, + "out_voa_auto": false, + "allowed_for_design": true + }, + { + "type_variety": "4pumps_raman", + "type_def": "fixed_gain", + "gain_flatmax": 12, + "gain_min": 12, + "p_max": 21, + "nf0": -1, + "allowed_for_design": false + }, + { + "type_variety": "hybrid_4pumps_lowgain", + "type_def": "dual_stage", + "raman": true, + "gain_min": 25, + "preamp_variety": "4pumps_raman", + "booster_variety": "std_low_gain", + "allowed_for_design": true + } + +1.2.2. Fiber and RamanFiber types +********************************* + +Fiber type with its parameters: + +.. code-block:: json-object + + { + "Fiber":[{ + "type_variety": "SSMF", + "dispersion": 1.67e-05, + "effective_area": 83e-12, + "pmd_coef": 1.265e-15 + } + ], + "RamanFiber": [ + { + "type_variety": "SSMF", + "dispersion": 1.67e-05, + "effective_area": 83e-12, + "pmd_coef": 1.265e-15 + } + ] + } + +The parameters Gamma and Raman efficiency are calculated using the effective area. +In releases prior to version 2.5, Gamma and Raman efficiency were defined instead +of effective area. Both parameters are managed as optional for +backward compatibility. + +The RamanFiber is a specialized variant of the regular Fiber, where the simulation +engine incorporates Raman amplification. The actual pump definitions must be +specified within the RamanFiber instance in the topology +(refer to the gnpy.core.elements.RamanFiber class). + +More details can be found in :cite:curri_merit_2016. + +Raman efficiency is scaled against the effective area using the default Raman +coefficient profile (g0 * A_ff_overlap), where g0 is a Raman coefficient profile +defined for a reference effective area (gnpy.core.parameters.DEFAULT_RAMAN_COEFFICIENT). + +If a RamanFiber is defined in the library, a corresponding Fiber must also be defined +with the same type_variety. + +It is important to note that since version 2.5, Raman effects (Stimulated Raman Scattering) +are modeled in both Fiber and RamanFiber types if the raman_flag is set to True in the +global simulation definition (using the --sim-params option). The default value for this +flag is False. However, Raman amplification using co-propagation and counter-propagation +is only available in RamanFiber, which requires the flag to be set to True, making the +use of the --sim-params option mandatory. + +1.2.3 Roadm types +***************** + +Roadm element with its parameters: + +Since v2.10, it is possible to define several types of ROADM and to +describe their contribution to optical impairments. This follows a model +created at the IETF: `IETF +CCAMP optical impairment topology `_ + +.. code-block:: json-object + + "Roadm": [ + { + "target_pch_out_db": -20, + "add_drop_osnr": 38, + "pmd": 0, + "pdl": 0, + "restrictions": { + "preamp_variety_list": [], + "booster_variety_list": [] + } + }, + { + "type_variety": "roadm_type_1", + "target_pch_out_db": -18, + "add_drop_osnr": 35, + "pmd": 0, + "pdl": 0, + "restrictions": { + "preamp_variety_list": [], + "booster_variety_list": [] + }, + "roadm-path-impairments": [] + }, + { + "type_variety": "detailed_impairments", + "target_pch_out_db": -20, + "add_drop_osnr": 38, + "pmd": 0, + "pdl": 0, + "restrictions": { + "preamp_variety_list": [], + "booster_variety_list": [] + }, + "roadm-path-impairments": [ + { + "roadm-path-impairments-id": 0, + "roadm-express-path": [ + { + "frequency-range": { + "lower-frequency": 191.3e12, + "upper-frequency": 196.1e12 + }, + "roadm-pmd": 0, + "roadm-cd": 0, + "roadm-pdl": 0, + "roadm-inband-crosstalk": 0, + "roadm-maxloss": 16.5 + } + ] + }, + { + "roadm-path-impairments-id": 1, + "roadm-add-path": [ + { + "frequency-range": { + "lower-frequency": 191.3e12, + "upper-frequency": 196.1e12 + }, + "roadm-pmd": 0, + "roadm-cd": 0, + "roadm-pdl": 0, + "roadm-inband-crosstalk": 0, + "roadm-maxloss": 11.5, + "roadm-pmax": 2.5, + "roadm-osnr": 41, + "roadm-noise-figure": 23 + } + ] + }, + { + "roadm-path-impairments-id": 2, + "roadm-drop-path": [ + { + "frequency-range": { + "lower-frequency": 191.3e12, + "upper-frequency": 196.1e12 + }, + "roadm-pmd": 0, + "roadm-cd": 0, + "roadm-pdl": 0, + "roadm-inband-crosstalk": 0, + "roadm-maxloss": 11.5, + "roadm-minloss": 7.5, + "roadm-typloss": 10, + "roadm-pmin": -13.5, + "roadm-pmax": -9.5, + "roadm-ptyp": -12, + "roadm-osnr": 41, + "roadm-noise-figure": 15 + } + ] + } + ] + } + ] + +1.2.3. Spans element +******************** + +Spans element with its parameters: + +.. code-block:: json-object + + "Spans":[{ + "power_mode":true, + "delta_power_range_db": [0,0,0.5], + "max_length": 150, + "length_units": "km", + "max_loss": 28, + "padding": 10, + "EOL": 0, + "con_in": 0, + "con_out": 0 + } + ] + + +1.2.4. Spectral Information +*************************** + +Spectral information with its parameters: + +.. code-block:: json-object + + "SI":[{ + "f_min": 191.3e12, + "baud_rate": 32e9, + "f_max":195.1e12, + "spacing": 50e9, + "power_dbm": 0, + "power_range_db": [0,0,0.5], + "roll_off": 0.15, + "tx_osnr": 40, + "sys_margins": 0 + } + ] + + +1.2.5. Transceiver element +************************** + +Transceiver element with its parameters. **”mode”** can contain multiple +Transceiver operation formats. + +Note that ``OSNR`` parameter refers to the receiver's minimal OSNR threshold for a given mode. + +.. code-block:: json-object + + "Transceiver":[{ + "frequency":{ + "min": 191.35e12, + "max": 196.1e12 + }, + "mode":[ + { + "format": "mode 1", + "baud_rate": 32e9, + "OSNR": 11, + "bit_rate": 100e9, + "roll_off": 0.15, + "tx_osnr": 40, + "min_spacing": 37.5e9, + "cost":1 + }, + { + "format": "mode 2", + "baud_rate": 66e9, + "OSNR": 15, + "bit_rate": 200e9, + "roll_off": 0.15, + "tx_osnr": 40, + "min_spacing": 75e9, + "cost":1 + } + ] + } + ] + +*********************** +1. Network description +*********************** + +Network description defines network elements with additional to +equipment description parameters, metadata and elements interconnection. +Description is made in JSON file with predefined structure. By default +**gnpy-transmission-example** uses **edfa_example_network.json** file +and can be changed from command line. Parsing of JSON file is made with +**gnpy.core.network.load_network(network_description, +equipment_description)** and return value is **DiGraph** object which +mimics network description. + +2.1. Structure definition +########################## + +2.1.1. File root structure +*************************** + +Network description JSON file root consist of three unordered parts: + +- network_name – name of described network or service, is not used as + of now + +- elements - contains array of network element objects with their + respective parameters + +- connections – contains array of unidirectional connection objects + +.. code-block:: none + + {"network_name": "Example Network", + "elements": [{...}, + {...} + ], + "connections": [{...}, + {...} + ] + } + + +2.1.2. Elements parameters and subtypes +**************************************** + +Array of network element objects consist of unordered parameter names +and those values. In case of **"type_variety"** absence +**"type_variety":”default”** name:value combination is used. As of the +moment, existence of used **"type_variety"** in equipment description is +obligatory. + +2.2. Element parameters by type +********************************* + +2.2.1. Transceiver element +*************************** + +Transceiver element with its parameters. + +.. code-block:: json + + {"uid": "trx Site_A", + "metadata": { + "location": { + "city": "Site_A", + "region": "", + "latitude": 0, + "longitude": 0 + } + }, + "type": "Transceiver" + } + + + +2.2.2. ROADM element +********************* + +ROADM element with its parameters. **“params”** is optional, if not used +default loss value of 20dB is used. + +.. code-block:: json + + {"uid": "roadm Site_A", + "metadata": { + "location": { + "city": "Site_A", + "region": "", + "latitude": 0, + "longitude": 0 + } + }, + "type": "Roadm", + "params": { + "loss": 17 + } + } + + +2.2.3. Fused element +********************* + +Fused element with its parameters. **“params”** is optional, if not used +default loss value of 1dB is used. + +.. code-block:: json + + {"uid": "ingress fused spans in Site_B", + "metadata": { + "location": { + "city": "Site_B", + "region": "", + "latitude": 0, + "longitude": 0 + } + }, + "type": "Fused", + "params": { + "loss": 0.5 + } + } + + +2.2.4. Fiber element +********************* + +Fiber element with its parameters. + +.. code-block:: json + + {"uid": "fiber (Site_A \\u2192 Site_B)", + "metadata": { + "location": { + "city": "", + "region": "", + "latitude": 0.0, + "longitude": 0.0 + } + }, + "type": "Fiber", + "type_variety": "SSMF", + "params": { + "length": 40.0, + "length_units": "km", + "loss_coef": 0.2 + } + } + +2.2.5. RamanFiber element +************************* + +.. code-block:: json + + { + "uid": "Span1", + "type": "RamanFiber", + "type_variety": "SSMF", + "operational": { + "temperature": 283, + "raman_pumps": [ + { + "power": 200e-3, + "frequency": 205e12, + "propagation_direction": "counterprop" + }, + { + "power": 206e-3, + "frequency": 201e12, + "propagation_direction": "counterprop" + } + ] + }, + "params": { + "type_variety": "SSMF", + "length": 80.0, + "loss_coef": 0.2, + "length_units": "km", + "att_in": 0, + "con_in": 0.5, + "con_out": 0.5 + }, + "metadata": { + "location": { + "latitude": 1, + "longitude": 0, + "city": null, + "region": "" + } + } + } + + +2.2.6. EDFA element +******************** + +EDFA element with its parameters. + +.. code-block:: json + + {"uid": "Edfa1", + "type": "Edfa", + "type_variety": "std_low_gain", + "operational": { + "gain_target": 16, + "tilt_target": 0 + }, + "metadata": { + "location": { + "city": "Site_A", + "region": "", + "latitude": 2, + "longitude": 0 + } + } + } + +2.3. Connections objects +************************* + +Each unidirectional connection object in connections array consist of +two unordered **”from_node”** and **”to_node”** name pair with values +corresponding to element **”uid”** + +.. code-block:: json + + {"from_node": "roadm Site_C", + "to_node": "trx Site_C" + } + +************************ +3. Simulation Parameters +************************ + +Additional details of the simulation are controlled via ``sim_params.json``: + +.. code-block:: json + + { + "raman_parameters": { + "flag_raman": true, + "space_resolution": 10e3, + "tolerance": 1e-8 + }, + "nli_parameters": { + "nli_method_name": "ggn_spectrally_separated", + "wdm_grid_size": 50e9, + "dispersion_tolerance": 1, + "phase_shift_tolerance": 0.1, + "computed_channels": [1, 18, 37, 56, 75] + } + } diff --git a/json_structure_description.rst b/json_structure_description.rst deleted file mode 100644 index 810b7cfef..000000000 --- a/json_structure_description.rst +++ /dev/null @@ -1,559 +0,0 @@ -********************************************* -Equipment and Network description definitions -********************************************* - -1. Equipment description -######################## - -Equipment description defines equipment types and those parameters. -Description is made in JSON file with predefined structure. By default -**gnpy-transmission-example** uses **eqpt_config.json** file and that -can be changed with **-e** or **--equipment** command line parameter. -Parsing of JSON file is made with -**gnpy.core.equipment.load_equipment(equipment_description)** and return -value is a dictionary of format **dict[‘equipment -type’][‘subtype’]=object** - -1.1. Structure definition -************************* - -1.1.1. Equipment types -************************* - -Every equipment type is defined in JSON root with according name and -array of parameters as value. - -.. code-block:: none - - {"Edfa": [...], - "Fiber": [...] - } - - -1.1.2. Equipment parameters and subtypes -***************************************** - - -Array of parameters is a list of objects with unordered parameter name -and its value definition. In case of multiple equipment subtypes each -object contains **"type_variety":”type name”** name:value combination, -if only one subtype exists **"type_variety"** name is not mandatory and -it will be marked with **”default”** value. - -.. code-block:: json - - {"Edfa": [{ - "type_variety": "std_medium_gain", - "type_def": "variable_gain", - "gain_flatmax": 26, - "gain_min": 15, - "p_max": 23, - "nf_min": 6, - "nf_max": 10, - "out_voa_auto": false, - "allowed_for_design": true - }, - { - "type_variety": "std_low_gain", - "type_def": "variable_gain", - "gain_flatmax": 16, - "gain_min": 8, - "p_max": 23, - "nf_min": 6.5, - "nf_max": 11, - "out_voa_auto": false, - "allowed_for_design": true - } - ], - "Fiber": [{ - "type_variety": "SSMF", - "dispersion": 1.67e-05, - "gamma": 0.00127 - } - ] - } - - - -1.2. Equipment parameters by type -********************************* - -1.2.1. EDFA element -******************* - -Four types of EDFA definition are possible. Description JSON file -location is in **gnpy-transmission-example** folder: - -- Advanced – with JSON file describing gain/noise figure tilt and - gain/noise figure ripple. **"advanced_config_from_json"** value - contains filename. - -.. code-block:: json-object - - "Edfa":[{ - "type_variety": "high_detail_model_example", - "gain_flatmax": 25, - "gain_min": 15, - "p_max": 21, - "advanced_config_from_json": "std_medium_gain_advanced_config.json", - "out_voa_auto": false, - "allowed_for_design": false - } - ] - -- Variable gain – with JSON file describing gain figure tilt and gain/noise - figure ripple. **”default_edfa_config.json”** as source file. - -.. code-block:: json-object - - "Edfa":[{ - "type_variety": "std_medium_gain", - "type_def": "variable_gain", - "gain_flatmax": 26, - "gain_min": 15, - "p_max": 23, - "nf_min": 6, - "nf_max": 10, - "out_voa_auto": false, - "allowed_for_design": true - } - ] - -- Fixed gain – with JSON file describing gain figure tilt and gain/noise - figure ripple. **”default_edfa_config.json”** as source file. - -.. code-block:: json-object - - "Edfa":[{ - "type_variety": "std_fixed_gain", - "type_def": "fixed_gain", - "gain_flatmax": 21, - "gain_min": 20, - "p_max": 21, - "nf0": 5.5, - "allowed_for_design": false - } - ] - -- openroadm – with JSON file describing gain figure tilt and gain/noise - figure ripple. **”default_edfa_config.json”** as source file. - -.. code-block:: json-object - - "Edfa":[{ - "type_variety": "openroadm_ila_low_noise", - "type_def": "openroadm", - "gain_flatmax": 27, - "gain_min": 12, - "p_max": 22, - "nf_coef": [-8.104e-4,-6.221e-2,-5.889e-1,37.62], - "allowed_for_design": false - } - ] - -1.2.2. Fiber element -******************** - -Fiber element with its parameters: - -.. code-block:: json-object - - "Fiber":[{ - "type_variety": "SSMF", - "dispersion": 1.67e-05, - "gamma": 0.00127 - } - ] - -RamanFiber element -****************** - -A special variant of the regular ``Fiber`` where the simulation engine accounts for the Raman effect. -The newly added parameters are nested in the ``raman_efficiency`` dictionary. -Its shape corresponds to typical properties of silica. -More details are available from :cite:`curri_merit_2016`. - -The ``cr`` property is the normailzed Raman efficiency, so it is is (almost) independent of the fiber type, while the coefficient actually giving Raman gain is g_R=C_R/Aeff. - -The ``frequency_offset`` represents the spectral difference between the pumping photon and the one receiving energy. - -.. code-block:: json-object - - "RamanFiber":[{ - "type_variety": "SSMF", - "dispersion": 1.67e-05, - "gamma": 0.00127, - "raman_efficiency": { - "cr":[ - 0, 9.4E-06, 2.92E-05, 4.88E-05, 6.82E-05, 8.31E-05, 9.4E-05, 0.0001014, 0.0001069, 0.0001119, - 0.0001217, 0.0001268, 0.0001365, 0.000149, 0.000165, 0.000181, 0.0001977, 0.0002192, 0.0002469, - 0.0002749, 0.0002999, 0.0003206, 0.0003405, 0.0003592, 0.000374, 0.0003826, 0.0003841, 0.0003826, - 0.0003802, 0.0003756, 0.0003549, 0.0003795, 0.000344, 0.0002933, 0.0002024, 0.0001158, 8.46E-05, - 7.14E-05, 6.86E-05, 8.5E-05, 8.93E-05, 9.01E-05, 8.15E-05, 6.67E-05, 4.37E-05, 3.28E-05, 2.96E-05, - 2.65E-05, 2.57E-05, 2.81E-05, 3.08E-05, 3.67E-05, 5.85E-05, 6.63E-05, 6.36E-05, 5.5E-05, 4.06E-05, - 2.77E-05, 2.42E-05, 1.87E-05, 1.6E-05, 1.4E-05, 1.13E-05, 1.05E-05, 9.8E-06, 9.8E-06, 1.13E-05, - 1.64E-05, 1.95E-05, 2.38E-05, 2.26E-05, 2.03E-05, 1.48E-05, 1.09E-05, 9.8E-06, 1.05E-05, 1.17E-05, - 1.25E-05, 1.21E-05, 1.09E-05, 9.8E-06, 8.2E-06, 6.6E-06, 4.7E-06, 2.7E-06, 1.9E-06, 1.2E-06, 4E-07, - 2E-07, 1E-07 - ], - "frequency_offset":[ - 0, 0.5e12, 1e12, 1.5e12, 2e12, 2.5e12, 3e12, 3.5e12, 4e12, 4.5e12, 5e12, 5.5e12, 6e12, 6.5e12, 7e12, - 7.5e12, 8e12, 8.5e12, 9e12, 9.5e12, 10e12, 10.5e12, 11e12, 11.5e12, 12e12, 12.5e12, 12.75e12, - 13e12, 13.25e12, 13.5e12, 14e12, 14.5e12, 14.75e12, 15e12, 15.5e12, 16e12, 16.5e12, 17e12, - 17.5e12, 18e12, 18.25e12, 18.5e12, 18.75e12, 19e12, 19.5e12, 20e12, 20.5e12, 21e12, 21.5e12, - 22e12, 22.5e12, 23e12, 23.5e12, 24e12, 24.5e12, 25e12, 25.5e12, 26e12, 26.5e12, 27e12, 27.5e12, 28e12, - 28.5e12, 29e12, 29.5e12, 30e12, 30.5e12, 31e12, 31.5e12, 32e12, 32.5e12, 33e12, 33.5e12, 34e12, 34.5e12, - 35e12, 35.5e12, 36e12, 36.5e12, 37e12, 37.5e12, 38e12, 38.5e12, 39e12, 39.5e12, 40e12, 40.5e12, 41e12, - 41.5e12, 42e12 - ] - } - } - ] - - -1.2.3 Roadm element -******************* - -Roadm element with its parameters: - -.. code-block:: json-object - - "Roadms":[{ - "gain_mode_default_loss": 20, - "power_mode_pout_target": -20, - "add_drop_osnr": 38 - } - ] - -1.2.3. Spans element -******************** - -Spans element with its parameters: - -.. code-block:: json-object - - "Spans":[{ - "power_mode":true, - "delta_power_range_db": [0,0,0.5], - "max_length": 150, - "length_units": "km", - "max_loss": 28, - "padding": 10, - "EOL": 0, - "con_in": 0, - "con_out": 0 - } - ] - - -1.2.4. Spectral Information -*************************** - -Spectral information with its parameters: - -.. code-block:: json-object - - "SI":[{ - "f_min": 191.3e12, - "baud_rate": 32e9, - "f_max":195.1e12, - "spacing": 50e9, - "power_dbm": 0, - "power_range_db": [0,0,0.5], - "roll_off": 0.15, - "tx_osnr": 40, - "sys_margins": 0 - } - ] - - -1.2.5. Transceiver element -************************** - -Transceiver element with its parameters. **”mode”** can contain multiple -Transceiver operation formats. - -Note that ``OSNR`` parameter refers to the receiver's minimal OSNR threshold for a given mode. - -.. code-block:: json-object - - "Transceiver":[{ - "frequency":{ - "min": 191.35e12, - "max": 196.1e12 - }, - "mode":[ - { - "format": "mode 1", - "baud_rate": 32e9, - "OSNR": 11, - "bit_rate": 100e9, - "roll_off": 0.15, - "tx_osnr": 40, - "min_spacing": 37.5e9, - "cost":1 - }, - { - "format": "mode 2", - "baud_rate": 66e9, - "OSNR": 15, - "bit_rate": 200e9, - "roll_off": 0.15, - "tx_osnr": 40, - "min_spacing": 75e9, - "cost":1 - } - ] - } - ] - -*********************** -2. Network description -*********************** - -Network description defines network elements with additional to -equipment description parameters, metadata and elements interconnection. -Description is made in JSON file with predefined structure. By default -**gnpy-transmission-example** uses **edfa_example_network.json** file -and can be changed from command line. Parsing of JSON file is made with -**gnpy.core.network.load_network(network_description, -equipment_description)** and return value is **DiGraph** object which -mimics network description. - -2.1. Structure definition -########################## - -2.1.1. File root structure -*************************** - -Network description JSON file root consist of three unordered parts: - -- network_name – name of described network or service, is not used as - of now - -- elements - contains array of network element objects with their - respective parameters - -- connections – contains array of unidirectional connection objects - -.. code-block:: none - - {"network_name": "Example Network", - "elements": [{...}, - {...} - ], - "connections": [{...}, - {...} - ] - } - - -2.1.2. Elements parameters and subtypes -**************************************** - -Array of network element objects consist of unordered parameter names -and those values. In case of **"type_variety"** absence -**"type_variety":”default”** name:value combination is used. As of the -moment, existence of used **"type_variety"** in equipment description is -obligatory. - -2.2. Element parameters by type -********************************* - -2.2.1. Transceiver element -*************************** - -Transceiver element with its parameters. - -.. code-block:: json - - {"uid": "trx Site_A", - "metadata": { - "location": { - "city": "Site_A", - "region": "", - "latitude": 0, - "longitude": 0 - } - }, - "type": "Transceiver" - } - - - -2.2.2. ROADM element -********************* - -ROADM element with its parameters. **“params”** is optional, if not used -default loss value of 20dB is used. - -.. code-block:: json - - {"uid": "roadm Site_A", - "metadata": { - "location": { - "city": "Site_A", - "region": "", - "latitude": 0, - "longitude": 0 - } - }, - "type": "Roadm", - "params": { - "loss": 17 - } - } - - -2.2.3. Fused element -********************* - -Fused element with its parameters. **“params”** is optional, if not used -default loss value of 1dB is used. - -.. code-block:: json - - {"uid": "ingress fused spans in Site_B", - "metadata": { - "location": { - "city": "Site_B", - "region": "", - "latitude": 0, - "longitude": 0 - } - }, - "type": "Fused", - "params": { - "loss": 0.5 - } - } - - -2.2.4. Fiber element -********************* - -Fiber element with its parameters. - -.. code-block:: json - - {"uid": "fiber (Site_A \\u2192 Site_B)", - "metadata": { - "location": { - "city": "", - "region": "", - "latitude": 0.0, - "longitude": 0.0 - } - }, - "type": "Fiber", - "type_variety": "SSMF", - "params": { - "length": 40.0, - "length_units": "km", - "loss_coef": 0.2 - } - } - -2.2.5. RamanFiber element -************************* - -.. code-block:: json - - { - "uid": "Span1", - "type": "RamanFiber", - "type_variety": "SSMF", - "operational": { - "temperature": 283, - "raman_pumps": [ - { - "power": 200e-3, - "frequency": 205e12, - "propagation_direction": "counterprop" - }, - { - "power": 206e-3, - "frequency": 201e12, - "propagation_direction": "counterprop" - } - ] - }, - "params": { - "type_variety": "SSMF", - "length": 80.0, - "loss_coef": 0.2, - "length_units": "km", - "att_in": 0, - "con_in": 0.5, - "con_out": 0.5 - }, - "metadata": { - "location": { - "latitude": 1, - "longitude": 0, - "city": null, - "region": "" - } - } - } - - -2.2.6. EDFA element -******************** - -EDFA element with its parameters. - -.. code-block:: json - - {"uid": "Edfa1", - "type": "Edfa", - "type_variety": "std_low_gain", - "operational": { - "gain_target": 16, - "tilt_target": 0 - }, - "metadata": { - "location": { - "city": "Site_A", - "region": "", - "latitude": 2, - "longitude": 0 - } - } - } - -2.3. Connections objects -************************* - -Each unidirectional connection object in connections array consist of -two unordered **”from_node”** and **”to_node”** name pair with values -corresponding to element **”uid”** - -.. code-block:: json - - {"from_node": "roadm Site_C", - "to_node": "trx Site_C" - } - -************************ -3. Simulation Parameters -************************ - -Additional details of the simulation are controlled via ``sim_params.json``: - -.. code-block:: json - - { - "raman_parameters": { - "flag_raman": true, - "space_resolution": 10e3, - "tolerance": 1e-8 - }, - "nli_parameters": { - "nli_method_name": "ggn_spectrally_separated", - "wdm_grid_size": 50e9, - "dispersion_tolerance": 1, - "phase_shift_tolerance": 0.1, - "computed_channels": [1, 18, 37, 56, 75] - } - }