L2SS-1010: Add field-global attenuation, and allow overriding subband weights...

L2SS-1010: Add field-global attenuation, and allow overriding subband weights per subband per input, instead of just per input

Closes L2SS-1010

tangostationcontrol/docs/source/calibration.rst

@@ -122,34 +122,44 @@ The ``AntennaField`` device provides the following attributes that provide the r
 
   :type: ``uint32[N_ant]``
 
-:Calibration_SDP_Subband_Weights_Default_R: The computed remaining delay & loss compensation, to be applied as subband weights in SDP. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling) that can be used to compute the complex correction factor for each subband.
+:Calibration_SDP_Fine_Calibration_Default_R: The computed remaining delay & loss compensation, to be applied as subband weights in SDP. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling) that can be used to compute the complex correction factor for each subband.
 
   :type: ``float[N_ant][3]``
 
+:Calibration_SDP_Subband_Weights_Default_R: The computed remaining delay & loss compensation, per subband, as (real, imag) pairs representing complex weights. This array represents ``Calibration_SDP_Fine_Calibration_Default_R`` transformed into complex weights for every subband.
+
+  :type: ``float[N_ant][N_subbands][2]``
+
 :Calibration_SDP_Subband_Weights_R: The remaining delay & loss compensation to be applied. Returns rows from the preconfigured calibration table if available, falling back to rows from the computed ``Calibration_SDP_Subband_Weights_Default_R`` table otherwise.
 
-  :type: ``float[N_ant][3]``
+  :type: ``float[N_ant][N_subbands][2]``
 
 The preconfigured calibration tables are described below.
 
 Calibration configuration
 `````````````````````````````
 
+The software allows a generic additional calibration to tune all inputs further with the following property:
+
+:Field_Attenuation: Attenuation value to apply on all inputs in this field (in dB).
+
+  :type: ``float``
+
 The software models cannot account for all required corrections. We assume that the software correctly computes the coarse compensation, but that additional tuning of the fine compensations is needed. Actual measurements must be used to derive the precise correction factors for each antenna. The ``AntennaField`` device allows the following properties to be used to replace the computed ``Calibration_SDP_Subband_Weights_Default_R`` table for the fine correction factors:
 
-:Calibration_SDP_Subband_Weights_50MHz: The measured correction factors for each input, at the 50 MHz reference frequency. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling).
+:Calibration_SDP_Subband_Weights_50MHz: The measured correction factors for each input, at the 50 MHz reference frequency. Each antenna is by a weight for every subband, where each weight is a (real, imag) pair.
 
-  :type: ``float[N_ant][3]``
+  :type: ``float[N_ant][N_subbands][2]``
 
-:Calibration_SDP_Subband_Weights_150MHz: The measured correction factors for each input, at the 150 MHz reference frequency. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling).
 
-  :type: ``float[N_ant][3]``
+:Calibration_SDP_Subband_Weights_150MHz: The measured correction factors for each input, at the 150 MHz reference frequency. Each antenna is by a weight for every subband, where each weight is a (real, imag) pair.
 
-:Calibration_SDP_Subband_Weights_200MHz: The measured correction factors for each input, at the 200 MHz reference frequency. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling).
+  :type: ``float[N_ant][N_subbands][2]``
 
-  :type: ``float[N_ant][3]``
+:Calibration_SDP_Subband_Weights_200MHz: The measured correction factors for each input, at the 200 MHz reference frequency. Each antenna is by a weight for every subband, where each weight is a (real, imag) pair.
 
-:Calibration_SDP_Subband_Weights_250MHz: The measured correction factors for each input, at the 250 MHz reference frequency. Each antenna is represented by a triplet (delay_seconds, phase_offset, amplitude_scaling).
+  :type: ``float[N_ant][N_subbands][2]``
 
-  :type: ``float[N_ant][3]``
+:Calibration_SDP_Subband_Weights_250MHz: The measured correction factors for each input, at the 250 MHz reference frequency. Each antenna is by a weight for every subband, where each weight is a (real, imag) pair.
 
+  :type: ``float[N_ant][N_subbands][2]``