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

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 @@ 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

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'