RF cavity tuning: introduce fundamental frequency

docs/p/CavityControl.md

@@ -2,73 +2,107 @@
 title: Controlling the RF cavities
 ---
 A lattice may contain multiple RF cavities, grouped according to different RF systems:
-main cavities, harmonic cavities…
-<br />
+main cavities, harmonic cavities…\
 AT provides simple tools to tune them, with methods and properties of the
 `Lattice` object.
 
 ### Lattice methods for cavity control
 
-The values handled by these methods concern the full ring (`periodicity` $$\times$$ superperiod).
+All methods have `array` and `cavpts` keyword arguments, used to select the cavities concerned by the command.
 
-All methods have a `cavpts` argument, used to select the cavities concerned by the command.
-The `cavpts` argument is used as follows:
-- `cavpts` is a "refpts" type (integer, integer or boolean array, callable): it is used to select the cavities,
-- `cavpts` is `None` (default value), and the `Lattice` object has a `cavpts` attribute: the lattice attribute is used to select the cavities,
-- `cavpts` is `None`, and the lattice has no `cavpts` attribute (or it is `None`): all cavities are selected.
-
-So the easier way to use it is:
-- **single RF system** (main cavities): forget the `cavpts` argument. The default is to use all cavities,
-- **main RF system + harmonic system**: set the `Lattice` `cavpts` attribute to the location of the main cavities,
-  so that the default behaviour is to drive the main system. Use the method's `cavpts` argument to drive the harmonic cavities.
+- if `array is True`, the output attribute value is an array as long as the number of selected cavities.
+  The input argument must be an array as long as the number of selected cavities
+  or a scalar which will be broadcasted to the number of cavities,
+- if `array is False` (default), the input and output are scalars. The scalar value
+applies to the set of cavities with the lowest frequency within the selection.
+The other cavities are ignored in `get_*` methods. For `set_*` methods, the other
+cavities are scaled as explained if the specific method description.
 
-All methods also have a `copy` argument to select either in-place modification
+The `cavpts` argument is used as follows:
+- `cavpts` is a "refpts" type (integer, integer or boolean array, callable): it is used to select the
+  cavities.
+- `cavpts is None` (default value), and the `Lattice` object has a `cavpts` attribute:
+  the lattice attribute is used to select the cavities.
+- `cavpts is None`, and the lattice has no `cavpts` attribute (or it is `None`):
+  all cavities are taken into account.
+
+{% include tip.html content="<br/>
+- **single RF system:** you can forget the `cavpts` argument: by default the methods
+address all cavities. However, using the `Lattice.cavpts` attribute makes calls significantly
+faster by skipping the search for cavities.<br/>
+- **complex system:** an easy way is to have the `Lattice.cavpts` address the accelerating
+cavities so that they will be driven by default. Harmonic cavities may be driven
+using the `cavpts` argument.
+" %}
+
+{% include tip.html content="
+Adding to the Lattice \"refpts\" type attributes addressing the different cavity sets make
+them available everywhere the lattice is visible.
+" %}
+
+All `set_*` methods also have a `copy` argument to select either in-place modification
 of the lattice, or creation of a shallow copy with modified cavities.
 
 #### Voltage:
-```voltage = Lattice.get_rf_voltage(cavpts=None)```
+```voltage = Lattice.get_rf_voltage(cavpts=None, array=False)```
+
+The scalar voltage is the sum of the cavity voltages of the cavities with the
+lowest frequency within the selection, multiplied by the periodicity.
 
-```Lattice.set_rf_voltage(voltage, cavpts=None, copy=False)```
+```Lattice.set_rf_voltage(voltage, cavpts=None, array=False, copy=False)```
 
-The specified voltage is equally distributed among all selected cavities in all superperiods.
+For array == False, all the existing voltages are scaled to reach the specified
+value on the fundamental mode.
 
 #### Frequency:
-`frequency = Lattice.get_rf_frequency(cavpts=None)`
+`frequency = Lattice.get_rf_frequency(cavpts=None, array=False)`
 
-`Lattice.get_rf_frequency(frequency=None, dp=None, dct=None, cavpts=None, copy=False)`
+The frequency of the fundamental mode is returned.
 
-If the frequency in `None`, the method will set the frequency to the nominal value,
+`Lattice.get_rf_frequency(frequency=None, dp=None, dct=None, cavpts=None, array=False, copy=False)`
+
+If the frequency is None, the method will set the frequency to the nominal value,
 according to the revolution frequency and harmonic number. An optional
 off-momentum may be applied using the `dp` or `dct` arguments. The frequency
 shift is then computed using the linear slip factor $$\eta_c = 1/\gamma^2 - \alpha_c$$ ,
-so that the resulting `dp` may slighly differ from the specified value.
+so that the resulting `dp` may slightly differ from the specified value.
+
+For array == False, the value is applied to the fundamental mode cavities and
+the frequency of all other cavities is scaled by the same ratio.
 
 #### Time lag
-`time_lag = Lattice.get_rf_timelag(cavpts=None)`
+The time lag is expressed in values of path lengthening "c&tau;", the 6<sup>th</sup> particle coordinate [m].
 
-`Lattice.set_rf_timelag(time_lag, cavpts=None, copy=False)`
+`time_lag = Lattice.get_rf_timelag(cavpts=None, array=False)`
+
+The time lag of the fundamental mode is returned.
+
+`Lattice.set_rf_timelag(time_lag, cavpts=None, array=False, copy=False)`
+
+For array == False, the time lag is applied to the fundamental mode cavities and
+the time lag of all the other selected cavities is shifted by the same amount.
 
-The time lag is expressed in values of path lengthening "c&tau;", the 6<sup>th</sup> particle coordinate [m].
 #### All-in-one method
 `Lattice.set_cavity(ring, Voltage=None, Frequency=None, TimeLag=None,
-                    cavpts=None, copy=False)`
+                    cavpts=None, array=False, copy=False)`
 
-This method sets only the explicity provided values, default ones are left unchanged.
+This method sets only the explicitly provided values, the other ones are left unchanged.
 For the frequency, a special value `at.Frf.NOMINAL` means nominal frequency,
 according to the revolution frequency and harmonic number.
 
+The behaviour of the `cavpts` and `array` keywords is the same as for individual methods.
+
 ### Lattice properties
 The properties provide an even easier way to control the cavities, but are restricted
 to the default behaviour of the equivalent Lattice method:
-- cavities are selected by the `Lattice` `cavpts` argument (all cavities by default),
+- cavities are selected by the `Lattice.cavpts` attribute (all cavities by default),
 - Setting a property modifies the ring in-place (no copy).
 
 `Lattice.rf_voltage`
 
 `Lattice.rf_frequency`
 
-The special value `at.Frf.NOMINAL` means nominal frequency,
-according to the revolution frequency and harmonic number.
+The special value `at.Frf.NOMINAL` means nominal frequency.
 
 `Lattice.harmonic_number`