Merge pull request #481 from slaclab/issue480

Adds a profile_slot script which extends profile_band to an entire slot, adds docstrings to smurf_atca_monitor submodule.

python/pysmurf/client/base/smurf_config_properties.py

@@ -2142,17 +2142,74 @@ def iq_swap_out(self, value):
  # Getter
  @property
  def ref_phase_delay(self):
- """Short description.
-
- Gets or sets ?.
- Units are ?.
+ """Coarse (analog + digital) round-trip delay.
+
+ Gets or sets the coarse (analog + digital) round-trip delay.
+ This is the total time it takes a tone to traverse the
+ synthesis filter bank, get generated by the DAC, propagate
+ through the external analog RF circuit (e.g. through a cold RF
+ chain including MUX chips), get digitized by the ADC, and then
+ traverse the analysis filter bank. This register is named
+ `refPhaseDelay` in firmware.
+
+ Unit-less unsigned integer. Each step is a clock tick whose
+ frequency is given by
+ :func:`~pysmurf.client.command.smurf_command.SmurfCommandMixin.get_channel_frequency_mhz`
+ in MHz. Different carrier firmware versions support different
+ ranges.
+
+ This delay is applied to the phase of each generated tone, and
+ an overall phase rotation of (`etaPhase` - `refPhaseDelay`) is
+ applied to each tone after demodulation and downmix.
+ `refPhaseDelay` can be measured using the
+ :func:`~pysmurf.client.util.smurf_util.SmurfUtilMixin.estimate_phase_delay`
+ routine.
+
+ The total effective delay can be fine tuned by also setting
+ the `refPhaseDelayFine` register (see
+ :func:`ref_phase_delay_fine`) which adjusts the compensated
+ delay more finely by 307.2 MHz ticks (although they way
+ `refPhaseDelayFine` compensates for delay in firmware is not
+ the same as `refPhaseDelay` - see the docstring for the
+ :func:`ref_phase_delay_fine` property for more details).
 
  Specified in the pysmurf configuration file as
- `ref_phase_delay`.
+ `init:band_#:refPhaseDelay` with # the SMuRF 500 MHz band
+ number *e.g.* `init:band_0:refPhaseDelay` for band 0.
+
+ .. warning::
+ Because `refPhaseDelay` and `refPhaseDelayFine` include the
+ digital delay, it will vary for different firmware
+ versions.
+
+ Examples
+ --------
+ For firmware where `refPhaseDelay` is measured in 2.4 MHz
+ ticks, if `refPhaseDelay` is 6 that corresponds to a time
+ delay of 6/(2.4 MHz) = 2.5 microseconds. For example, a 2
+ microsecond delay for a 100 kHz phi0 rate corresponds to an ~1
+ rad phase shift -- so it's particularly important to set
+ `refPhaseDelay` correctly if running at high phi0 rates (10
+ kHz or higher).
+
+ Returns
+ -------
+ int
+ Coarse (analog + digital) round-trip delay. Unit-less
+ unsigned integer. Each step is a clock tick whose rate is
+ given by
+ :func:`~pysmurf.client.command.smurf_command.SmurfCommandMixin.get_channel_frequency_mhz`
+ in MHz. Different carrier firmware versions support
+ different ranges.
 
  See Also
  --------
- ?
+ :func:`~pysmurf.client.util.smurf_util.SmurfUtilMixin.estimate_phase_delay` :
+ Measures `ref_phase_delay` and `ref_phase_delay_fine`.
+
+ :func:`ref_phase_delay_fine` : Fine adjustment for system roundtrip delay.
+
+ :func:`lms_delay` : System roundtrip delay including the tracking algorithm.
 
  """
  return self._ref_phase_delay
@@ -2171,17 +2228,72 @@ def ref_phase_delay(self, value):
  # Getter
  @property
  def ref_phase_delay_fine(self):
- """Short description.
-
- Gets or sets ?.
- Units are ?.
+ """Fine adjust for (analog + digital) round-trip delay.
+
+ Gets or sets fine adjustment for the total (analog + digital)
+ round-trip delay. This allows for fine adjustment of the
+ total effective system round-trip delay on top of the coarser
+ correction provided by programming the `refPhaseDelay` register
+ (see :func:`ref_phase_delay` and
+ :func:`~pysmurf.client.command.smurf_command.SmurfCommandMixin.set_ref_phase_delay`
+ for more details).
+
+ Unit-less unsigned integer. Each step is a 307.2 MHz tick
+ (3.255 ns), for all firmware versions. Different carrier
+ firmware versions support different ranges.
+
+ This register is named `refPhaseDelayFine` in firmware and is
+ implemented differently than `refPhaseDelay` : setting
+ `refPhaseDelayFine` only adds a time lag to the RF DAC output.
+ `refPhaseDelayFine` can be measured using the
+ :func:`~pysmurf.client.util.smurf_util.SmurfUtilMixin.estimate_phase_delay`
+ routine.
 
  Specified in the pysmurf configuration file as
- `ref_phase_delay_fine`.
+ `init:band_#:refPhaseDelayFine` with # the SMuRF 500 MHz band
+ number *e.g.* `init:band_0:refPhaseDelayFine` for band 0.
+
+ .. warning::
+ Because `refPhaseDelay` and `refPhaseDelayFine` include the
+ digital delay, it will vary for different firmware
+ versions.
+
+ Examples
+ --------
+ Say the total delay measured using
+ :func:`~pysmurf.client.util.smurf_util.SmurfUtilMixin.estimate_phase_delay`
+ is 2.3 microseconds. To program this delay, you'd first set
+ `refPhaseDelay` to 6, which is 2.5 microseconds (assuming that
+ `refPhaseDelay` is measured in 2.4 MHz ticks, and so 6/(2.4
+ MHz) = 2.5 microseconds). Because `refPhaseDelayFine` adds
+ time lag to the RF DAC output, it subtracts from the total
+ delay (so it compensates in the opposite direction that
+ `refPhaseDelay` does). So setting `refPhaseDelayFine` to 61
+ would result in a programmed delay of:
+
+ | `refPhaseDelay`/(2.4 MHz) - `refPhaseDelayFine`/(307.2 MHz)
+ | = 6/(2.4 MHz) - 61/(307.2 MHz)
+ | = 2.30143 microseconds
+
+ which is as close to 2.3 microseconds as we can program the
+ delay, given the clock rates.
+
+ Returns
+ -------
+ int
+ Fine adjustment for (analog + digital) round-trip delay.
+ Unit-less unsigned integer. Each step is a 307.2 MHz tick.
+ Different carrier firmware versions support different
+ ranges.
 
  See Also
  --------
- ?
+ :func:`~pysmurf.client.util.smurf_util.SmurfUtilMixin.estimate_phase_delay` :
+ Measures `ref_phase_delay` and `ref_phase_delay_fine`.
+
+ :func:`ref_phase_delay` : Coarse system roundtrip delay.
+
+ :func:`lms_delay` : System roundtrip delay including the tracking algorithm.
 
  """
  return self._ref_phase_delay_fine