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 <[email protected]> Change-Id: I7727f00b38244152b95954e981cc9da096bb3d1d
Orange-OpenSource · May 24, 2024 · ee9af69 · ee9af69
1 parent ce21609
commit ee9af69
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 10 deletions.
diff --git a/docs/extending.rst b/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:
 

diff --git a/gnpy/core/elements.py b/gnpy/core/elements.py
@@ -757,7 +757,7 @@ def __init__(self, *args, params=None, operational=None, **kwargs):
             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 @@ def __init__(self, *args, params=None, operational=None, **kwargs):
         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 @@ def to_json(self):
                 '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 @@ def _gain_profile(self, pin, err_tolerance=1.0e-11, simple_opt=True):
         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

diff --git a/gnpy/tools/convert.py b/gnpy/tools/convert.py
@@ -122,7 +122,7 @@ def update_attr(self, kwargs):
         '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'