Improve doc to state when tilt is vs wavelength

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

docs/extending.rst

@@ -91,7 +91,8 @@ Advanced Specification
 **********************
 
 The amplifier performance can be further described in terms of gain ripple, NF ripple, and the dynamic gain tilt.
-When provided, the amplifier characteristic is fine-tuned as a function of carrier frequency.
+When provided, the amplifier characteristic is fine-tuned as a function of carrier frequency. Note that in this advanced
+specification tilt is defined vs frequency while tilt_target specified in EDFA instances is defined vs wavelength.
 
 .. _extending-raman:
 

gnpy/core/elements.py

@@ -757,7 +757,7 @@ class Edfa(_Node):
             operational = {}
         self.variety_list = kwargs.pop('variety_list', None)
         super().__init__(*args, params=EdfaParams(**params), operational=EdfaOperational(**operational), **kwargs)
-        self.interpol_dgt = None  # interpolated dynamic gain tilt
+        self.interpol_dgt = None  # interpolated dynamic gain tilt defined per frequency on amp band
         self.interpol_gain_ripple = None  # gain ripple
         self.interpol_nf_ripple = None  # nf_ripple
         self.channel_freq = None  # SI channel frequencies
@@ -780,7 +780,7 @@ class Edfa(_Node):
         self.delta_p = self.operational.delta_p
         # self._delta_p contains computed delta_p during design even if power_mode is False
         self._delta_p = None
-        self.tilt_target = self.operational.tilt_target
+        self.tilt_target = self.operational.tilt_target  # defined per lambda on the amp band
         self.out_voa = self.operational.out_voa
         self.propagated_labels = [""]
 
@@ -792,7 +792,7 @@ class Edfa(_Node):
                 'operational': {
                     'gain_target': round(self.effective_gain, 6) if self.effective_gain else None,
                     'delta_p': self.delta_p,
-                    'tilt_target': self.tilt_target,
+                    'tilt_target': self.tilt_target,  # defined per lambda on the amp band
                     'out_voa': self.out_voa
                 },
                 'metadata': {
@@ -1022,7 +1022,7 @@ class Edfa(_Node):
         p = polyfit(self.channel_freq, self.interpol_dgt, 1)
         dgt_slope = p[0]
 
-        # Calculate the target slope
+        # Calculate the target slope defined per frequency on the amp band
         targ_slope = -self.tilt_target / (self.params.f_max - self.params.f_min)
 
         # first estimate of DGT scaling

gnpy/tools/convert.py

@@ -122,7 +122,7 @@ class Eqpt(object):
         'east_att_in': 0,
         'east_amp_gain': None,
         'east_amp_dp': None,
-        'east_tilt': 0,
+        'east_tilt_vs_wavelength': 0,
         'east_att_out': None
     }
 
@@ -345,13 +345,13 @@ def create_east_eqpt_element(node):
         eqpt['type_variety'] = f'{node.east_amp_type}'
         eqpt['operational'] = {'gain_target': node.east_amp_gain,
                                'delta_p':     node.east_amp_dp,
-                               'tilt_target': node.east_tilt,
+                               'tilt_target': node.east_tilt_vs_wavelength,
                                'out_voa':     node.east_att_out}
     elif node.east_amp_type.lower() == '':
         eqpt['type'] = 'Edfa'
         eqpt['operational'] = {'gain_target': node.east_amp_gain,
                                'delta_p':     node.east_amp_dp,
-                               'tilt_target': node.east_tilt,
+                               'tilt_target': node.east_tilt_vs_wavelength,
                                'out_voa':     node.east_att_out}
     elif node.east_amp_type.lower() == 'fused':
         # fused edfa variety is a hack to indicate that there should not be
@@ -378,12 +378,12 @@ def create_west_eqpt_element(node):
         eqpt['type_variety'] = f'{node.west_amp_type}'
         eqpt['operational'] = {'gain_target': node.west_amp_gain,
                                'delta_p':     node.west_amp_dp,
-                               'tilt_target': node.west_tilt,
+                               'tilt_target': node.west_tilt_vs_wavelength,
                                'out_voa':     node.west_att_out}
     elif node.west_amp_type.lower() == '':
         eqpt['operational'] = {'gain_target': node.west_amp_gain,
                                'delta_p':     node.west_amp_dp,
-                               'tilt_target': node.west_tilt,
+                               'tilt_target': node.west_tilt_vs_wavelength,
                                'out_voa':     node.west_att_out}
     elif node.west_amp_type.lower() == 'fused':
         eqpt['type'] = 'Fused'