feat: parametrize the function that computes power targets

enable changing the reference span loss and the ratio of the
loss deviation to this reference that should be reported on
the span input.

Initial target used a hardcoded 20dB loss span with
0.3 power slope.

update documentation accordingly.

requires yang updates
Signed-off-by: EstherLerouzic <esther.lerouzic@orange.com>
Change-Id: Ib763db6be2bd7e947057176f3246f19ac7e6ac0d

docs/json.rst

@@ -731,6 +731,30 @@ Span configuration is not a list (which may change in later releases) and the us
 |                                     |           | value is input in the topology for a        |
 |                                     |           | given Fiber.                                |
 +-------------------------------------+-----------+---------------------------------------------+
+| ``span_loss_ref``                   | (number)  | (optional) in dB. For autodesign.           |
+|                                     |           | Reference span loss value in dB, used to    |
+|                                     |           | calculate all delta_p deviations during     |
+|                                     |           | network autodesign. The default value is    |
+|                                     |           | 20dB.                                       |
++-------------------------------------+-----------+---------------------------------------------+
+| ``power_slope``                     | (number)  | (optional) Pure number. For autodesign.     |
+|                                     |           | Ratio used to compute all delta_p           |
+|                                     |           | deviations during network autodesign.       |
+|                                     |           | The default value is 0.3.                   |
++-------------------------------------+-----------+---------------------------------------------+
+| ``voa_margin``                      | (float)   | (optional) in dB. For autodesign.           |
+|                                     |           | Margin to subtract from the calculated VOA  |
+|                                     |           | during gain optimisation process, to        |
+|                                     |           | prevent maximum attenuation.                |
+|                                     |           | This creates a safety buffer.               |
+|                                     |           | Default value is 1dB.                       |
++-------------------------------------+-----------+---------------------------------------------+
+| ``voa_step``                        | (float)   | (optional) in dB. For autodesign.           |
+|                                     |           | Step size used for rounding the VOA value.  |
+|                                     |           | Ensures VOA adjustments align with hardware |
+|                                     |           | resolution.                                 |
+|                                     |           | Default value is 0.5dB.                     |
++-------------------------------------+-----------+---------------------------------------------+
 
 .. code-block:: json
 

gnpy/core/network.py

@@ -162,17 +162,18 @@ def target_power(network: DiGraph, node: PASSIVE_ELEMENT_TYPES,
     ------
     - If the node is a ROADM, the function returns 0.
     - The target power is calculated based on the span loss and adjusted by the specified deviation.
+    - In theory at the optimum, the slope should be 1/3 (~0.3)
+    - the returned delta_p will be the optimum deviation with respect to the span_loss_ref.
     """
     if isinstance(node, elements.Roadm):
         return 0
 
-    SPAN_LOSS_REF = 20
-    POWER_SLOPE = 0.3
     dp_range = list(equipment['Span']['default'].delta_power_range_db)
     node_loss = span_loss(network, node, equipment) + deviation_db
 
     try:
-        dp = round2float((node_loss - SPAN_LOSS_REF) * POWER_SLOPE, dp_range[2])
+        dp = round2float((node_loss - equipment['Span']['default'].span_loss_ref)
+                         * equipment['Span']['default'].power_slope, dp_range[2])
         dp = max(dp_range[0], dp)
         dp = min(dp_range[1], dp)
     except IndexError:
@@ -597,7 +598,8 @@ def find_last_node(network, node):
     return this_node
 
 
-def set_amplifier_voa(amp: elements.Edfa, power_target: float, power_mode: bool):
+def set_amplifier_voa(amp: elements.Edfa, power_target: float, power_mode: bool,
+                      voa_margin: float, voa_step: float):
     """Sets the output variable optical attenuator (VOA) for the amplifier.
 
     This function adjusts the VOA based on the target power and the operating mode
@@ -620,12 +622,11 @@ def set_amplifier_voa(amp: elements.Edfa, power_target: float, power_mode: bool)
       parameters and the target power.
     - If power_mode is False, the output VOA optimization is not applied.
     """
-    VOA_MARGIN = 1  # do not maximize the VOA optimization
     if amp.out_voa is None:
         if power_mode and amp.params.out_voa_auto:
             voa = min(amp.params.p_max - power_target,
                       amp.params.gain_flatmax - amp.effective_gain)
-            voa = max(round2float(voa, 0.5) - VOA_MARGIN, 0)
+            voa = max(round2float(voa, voa_step) - voa_margin, 0)
             amp.delta_p = amp.delta_p + voa
             amp.effective_gain = amp.effective_gain + voa
         else:
@@ -1066,7 +1067,8 @@ def set_one_amplifier(node: elements.Edfa, prev_node: ELEMENT_TYPES, next_node:
     node.tilt_target = _tilt_target
     # if voa is not set, then set it and possibly optimize it with gain and update delta_p and
     # effective_gain values
-    set_amplifier_voa(node, power_target, power_mode)
+    set_amplifier_voa(node, power_target, power_mode,
+                      equipment['Span']['default'].voa_margin, equipment['Span']['default'].voa_step)
     # set_amplifier_voa may change delta_p in power_mode
     node._delta_p = node.delta_p if power_mode else dp
 

gnpy/tools/json_io.py

@@ -70,7 +70,8 @@ class _JsonThing:
         clean_kwargs = {k: v for k, v in kwargs.items() if v != ''}
         for k, v in default_values.items():
             setattr(self, k, clean_kwargs.get(k, v))
-            disable_warning_keys = ['use_si_channel_count_for_design']
+            disable_warning_keys = ['use_si_channel_count_for_design', 'voa_step', 'voa_margin', 'span_loss_ref',
+                                    'power_slope']
             if k not in clean_kwargs and name != 'Amp' and v is not None and v != [] and k not in disable_warning_keys:
                 # do not show this warning if the default value is None
                 msg = f'\n\tWARNING missing {k} attribute in eqpt_config.json[{name}]' \
@@ -113,7 +114,11 @@ class Span(_JsonThing):
         'padding': 10,
         'EOL': 0,
         'con_in': 0,
-        'con_out': 0
+        'con_out': 0,
+        "span_loss_ref": 20.0,
+        "power_slope": 0.3,
+        "voa_margin": 1,
+        "voa_step": 0.5
     }
 
     def __init__(self, **kwargs):

tests/test_amplifier.py

@@ -401,7 +401,8 @@ def test_set_out_voa():
     power_target = 19 + amp.delta_p
     power_mode = True
     amp.params.out_voa_auto = True
-    set_amplifier_voa(amp, power_target, power_mode)
+    set_amplifier_voa(amp, power_target, power_mode,
+                      voa_margin=equipment['Span']['default'].voa_margin, voa_step=equipment['Span']['default'].voa_step)
     assert amp.out_voa == 4.0
     assert amp.effective_gain == 20.0 + 4.0
     assert amp.delta_p == -3.0 + 4.0