Fix docstring snakecase

examples/use_cases/01-tune_correction.py

@@ -93,7 +93,7 @@
 # In[5]:
 
 
-qcorrectors = SR.get_magnets("QForTune")
+qcorrectors = SR.magnets.get("QForTune")
 first_q = qcorrectors[0]
 print(f"The ring has {len(qcorrectors)} quadrupolar correctors. First: {first_q.get_name()}")
 print(qcorrectors[0])  # string representation

examples/use_cases/03-orbit_correction.py

@@ -84,9 +84,9 @@
 # In[4]:
 
 
-bpms = SR.get_bpms("BPM")
-hcorr = SR.get_magnets("HCorr")
-vcorr = SR.get_magnets("VCorr")
+bpms = SR.bpms.get("BPM")
+hcorr = SR.magnets.get("HCorr")
+vcorr = SR.magnets.get("VCorr")
 print(f"BPMs: {len(bpms)}, H correctors: {len(hcorr)}, V correctors: {len(vcorr)}")
 
 

examples/use_cases/config/esrf/orm.json

@@ -0,0 +1,3 @@
+{
+    "type": "pyaml.tuning_tools.orbit_response_matrix_data"
+}

examples/use_cases/config/esrf/orm.yaml

@@ -0,0 +1 @@
+type: pyaml.tuning_tools.orbit_response_matrix_data

pyaml/tuning_tools/bba.py

@@ -54,17 +54,17 @@ class BBA(MeasurementTool, DynamicValidation):
     quad_name : str
         Name of the quadrupole to align.
     hcorr_delta : float
-        Change in horizontal corrector strength used for each horizontal
-        orbit-offset step.
+        Change in horizontal corrector kick angle used for each horizontal
+        orbit-offset step, in radians.
     vcorr_delta : float
-        Change in vertical corrector strength used for each vertical
-        orbit-offset step.
+        Change in vertical corrector kick angle used for each vertical
+        orbit-offset step, in radians.
     hquad_delta : float
         Change in quadrupole strength used during the horizontal alignment
-        measurement.
+        measurement, in the configured quadrupole unit (typically ``m^-1``).
     vquad_delta : float
         Change in quadrupole strength used during the vertical alignment
-        measurement.
+        measurement, in the configured quadrupole unit (typically ``m^-1``).
     n_step : int, default=1
         Number of orbit-offset steps to perform in each plane.
     sleep_between_step : float, default=0
@@ -155,14 +155,14 @@ def measure(
         Parameters
         ----------
         sleep_between_step : float
-            Default time sleep after steerer or quad excitation
-            Default: from config
+            Delay in seconds after corrector or quadrupole excitation.
+            Default: from config.
         n_avg_meas : int, optional
             Default number of orbit measurement per step used for averaging
             Default from config
         sleep_between_meas : float
-            Default time sleep between two orbit measurment
-            Default: from config
+            Delay in seconds between two orbit measurements.
+            Default: from config.
         callback : Callable, optional
             example: callback(action:int, callback_data: 'Complicated struct')
             callback is executed after each strength setting and after each orbit
@@ -278,19 +278,19 @@ def measure(
         return True
 
     def h_offset(self) -> float:
-        """Return the measured horizontal magnetic-center offset."""
+        """Return the measured horizontal magnetic-center offset in metres."""
         return self.latest_measurement["HData"].offset if self.latest_measurement["HData"] is not None else np.nan
 
     def h_offset_error(self) -> float:
-        """Return the uncertainty of the horizontal center offset."""
+        """Return the horizontal center-offset uncertainty in metres."""
         return self.latest_measurement["HData"].offset_error if self.latest_measurement["HData"] is not None else np.nan
 
     def v_offset(self) -> float:
-        """Return the measured vertical magnetic-center offset."""
+        """Return the measured vertical magnetic-center offset in metres."""
         return self.latest_measurement["VData"].offset if self.latest_measurement["VData"] is not None else np.nan
 
     def v_offset_error(self) -> float:
-        """Return the uncertainty of the vertical center offset."""
+        """Return the vertical center-offset uncertainty in metres."""
         return self.latest_measurement["VData"].offset_error if self.latest_measurement["VData"] is not None else np.nan
 
     def plot_data(self, plane: str):

pyaml/tuning_tools/bba2.py

@@ -122,13 +122,14 @@ class BBA2(MeasurementTool, DynamicValidation):
         Name of the tune-correction tool used to compensate for tune changes
         caused by varying the quadrupole strength.
     hcorr_delta : float
-        Change in horizontal corrector strength used for each horizontal
-        orbit-offset step.
+        Change in horizontal corrector kick angle used for each horizontal
+        orbit-offset step, in radians.
     vcorr_delta : float
-        Change in vertical corrector strength used for each vertical
-        orbit-offset step.
+        Change in vertical corrector kick angle used for each vertical
+        orbit-offset step, in radians.
     quad_delta : float
-        Change in quadrupole strength used for the alignment measurement.
+        Change in quadrupole strength used for the alignment measurement, in
+        the configured quadrupole unit (typically ``m^-1``).
     bipolar_delta : bool, default=False
         If `True`, vary the quadrupole strength both above and below its
         initial value by `quad_delta`. If `False`, apply the change in one
@@ -526,14 +527,14 @@ def measure(
         Parameters
         ----------
         sleep_between_step : float
-            Default time sleep after steerer or quad excitation
-            Default: from config
+            Delay in seconds after corrector or quadrupole excitation.
+            Default: from config.
         n_avg_meas : int, optional
             Default number of orbit measurement per step used for averaging
             Default from config
         sleep_between_meas : float
-            Default time sleep between two orbit measurment
-            Default: from config
+            Delay in seconds between two orbit measurements.
+            Default: from config.
         callback : Callable, optional
             example: callback(action:int, callback_data: 'Complicated struct')
             callback is executed after each strength setting and after each orbit
@@ -701,19 +702,19 @@ def measure(
         return True
 
     def h_offset(self) -> float:
-        """Return the measured horizontal magnetic-center offset."""
+        """Return the measured horizontal magnetic-center offset in metres."""
         return self.latest_measurement["HData"].offset if self.latest_measurement["HData"] is not None else np.nan
 
     def h_offset_error(self) -> float:
-        """Return the uncertainty of the horizontal center offset."""
+        """Return the horizontal center-offset uncertainty in metres."""
         return self.latest_measurement["HData"].error if self.latest_measurement["HData"] is not None else np.nan
 
     def v_offset(self) -> float:
-        """Return the measured vertical magnetic-center offset."""
+        """Return the measured vertical magnetic-center offset in metres."""
         return self.latest_measurement["VData"].offset if self.latest_measurement["VData"] is not None else np.nan
 
     def v_offset_error(self) -> float:
-        """Return the uncertainty of the vertical center offset."""
+        """Return the vertical center-offset uncertainty in metres."""
         return self.latest_measurement["VData"].error if self.latest_measurement["VData"] is not None else np.nan
 
     def plot_plane_data(self, ax, plane: str):

pyaml/tuning_tools/chromaticity.py

@@ -130,11 +130,11 @@ def _sextu(self) -> "MagnetArray":
         return self.peer.magnets.get(self.sextu_array_name)
 
     def get(self):
-        """Return the requested horizontal and vertical chromaticity."""
+        """Return the requested dimensionless horizontal and vertical chromaticity."""
         return self._setpoint
 
     def readback(self):
-        """Measure and return the current horizontal and vertical chromaticity."""
+        """Measure and return the current dimensionless horizontal and vertical chromaticity."""
         self._cm.measure()
         return self._cm.chromaticity.get()
 
@@ -145,7 +145,7 @@ def set(self, chroma: np.array, iter: int = 1, wait_time: float = 0.0):
         Parameters
         ----------
         chroma : numpy.ndarray
-            Target horizontal and vertical chromaticity values.
+            Target horizontal and vertical chromaticity values (dimensionless).
         iter : int
             Number of correction iterations.
         wait_time : float
@@ -165,13 +165,14 @@ def correct(self, dchroma: np.array) -> np.array:
         Parameters
         ----------
         dchroma : numpy.ndarray
-            Desired horizontal and vertical chromaticity change.
+            Desired horizontal and vertical chromaticity change (dimensionless).
 
         Returns
         -------
         numpy.ndarray
             Sextupole-strength changes obtained from the response-matrix
-            pseudoinverse.
+            pseudoinverse, in the configured sextupole strength units
+            (typically ``m^-2``).
 
         Raises
         ------
@@ -189,7 +190,7 @@ def add(self, dchroma: np.array, wait_time: float = 0.0):
         Parameters
         ----------
         dchroma : numpy.ndarray
-            Horizontal and vertical chromaticity change to apply.
+            Horizontal and vertical chromaticity change to apply (dimensionless).
         wait_time : float
             Delay in seconds after changing sextupole strengths.
         """

pyaml/tuning_tools/chromaticity_monitor.py

@@ -65,7 +65,7 @@ def get(self) -> np.array:
 
     def unit(self) -> str:
         """Return the unit of the reported values."""
-        return self.unit
+        return self._unit
 
 
 @register_schema
@@ -88,9 +88,10 @@ class ChromaticityMonitor(MeasurementTool, DynamicValidation):
         Name of the BPM array used for dispersion measurements. Required
         only when dispersion fitting is enabled.
     e_delta : float, optional
-        Default relative momentum deviation used during the measurement.
+        Default relative momentum deviation, ``delta = dp/p`` (dimensionless),
+        used during the measurement.
     max_e_delta : float, optional
-        Maximum permitted relative momentum deviation.
+        Maximum permitted relative momentum deviation (dimensionless).
     fit_order : int, optional
         Polynomial order used to fit the chromaticity.
     fit_disp_order : int, optional
@@ -180,7 +181,7 @@ def chromaticity(self) -> ReadFloatArray:
         Returns
         -------
         ReadFloatArray
-            chromaticity values [q'x, q'y]
+            Chromaticity values ``[q'x, q'y]`` (dimensionless).
         """
         return self._chromaticity
 
@@ -194,7 +195,7 @@ def set_mcf(self, alphac: float):
         Parameters
         ----------
         alphac : float
-            Momentum-compaction factor, usually dimensionless.
+            Momentum-compaction factor (dimensionless).
         """
         self._alphac = alphac
 
@@ -206,7 +207,8 @@ def dispersion(self) -> ReadFloatArray:
         Returns
         -------
         ReadFloatArray
-            Array of dispersion values [[dx, dy],[d'x, d'y],...]
+            Array of dispersion values ``[[dx, dy], [d'x, d'y], ...]``, in
+            metres for the first-order values.
         """
         return self._dispersion
 
@@ -226,7 +228,7 @@ def measure(
         callback: Callable | None = None,
     ):
         """
-        Main function for chromaticity measurment.
+        Main function for chromaticity measurement.
 
         :py:attr:`~pyaml.tuning_tools.measurement_tool.MeasurementTool.latest_measurement` contains:
 
@@ -242,22 +244,23 @@ def measure(
         ----------
         n_step : int
             Default number of RF step during chromaticity
-            measurment [default: from config]
+            measurement [default: from config].
         alphac : float | None
-            Moment compaction factor [default: from config]
+            Momentum-compaction factor (dimensionless) [default: from config].
         e_delta : float
-            Default variation of relative energy during chromaticity measurment:
-            f0 - f0 * E_delta * alphac  < f_RF < f0 + f0 * E_delta * alphac
-            [default: from config]
+            Relative momentum variation ``delta = dp/p`` (dimensionless):
+            ``f0 - f0 * e_delta * alphac < f_RF <
+            f0 + f0 * e_delta * alphac`` [default: from config].
         max_e_delta : float
-            Maximum autorized variation of relative energy during chromaticity
-            measurment [default: from config]
+            Maximum permitted relative momentum variation (dimensionless)
+            [default: from config].
         n_avg_meas : int
-            Default number of tune/orbit measurment per RF frequency [default: from config]
+            Number of tune/orbit measurements per RF frequency
+            [default: from config].
         sleep_between_meas : float
-            Default time sleep between two tune measurment [default: from config]
+            Delay in seconds between two tune measurements [default: from config].
         sleep_between_step : float
-            Default time sleep after RF frequency variation [default: from config]
+            Delay in seconds after an RF-frequency variation [default: from config].
         fit_order : int
             Fitting order [default: from config]
         fit_disp_order : int, optional
@@ -276,10 +279,10 @@ def measure(
               source:MeasurementTool # Tool that triggered the callback
               step:int # The current step
               avg_step:int # The current averaging step
-              rf:float # RF frequency used for the current step
-              tune:np.array # The measured tune (on Action.MEASURE)
-              orbit:np_array # The measured orbit, if fit_dispersion is True, (on Action.MEASURE)
-              dtune:np.array # The tune variation (on Action.RESTORE)
+              rf:float # RF frequency in Hz used for the current step
+              tune:np.array # Dimensionless measured tune (on Action.MEASURE)
+              orbit:np_array # Orbit in m, if fit_dispersion is True (on Action.MEASURE)
+              dtune:np.array # Dimensionless tune variation (on Action.RESTORE)
         """
         n_step = n_step if n_step is not None else self.n_step
         alphac = alphac if alphac is not None else self._alphac
@@ -383,13 +386,14 @@ def fit(self, deltas, Q, order, orbit=None, fit_disp_order=None, do_plot=False):
         Parameters
         ----------
         deltas : array of float
-            Relative energy (delta) variation steps done.
+            Relative momentum variation steps, ``delta = dp/p`` (dimensionless).
         Q : array of [Qx,Qy]
-            Horizontal,Vertical tune measured.
+            Measured horizontal and vertical tune (dimensionless).
         order : int
             Chromaticity fitting order.
         orbit : array of [[x0,y0],[x1,y1],...], optional
-            Horizontal and vertical orbit at each energy step, used to fit the dispersion.
+            Horizontal and vertical orbit in metres at each energy step, used
+            to fit the dispersion.
         fit_disp_order : int, optional
             Dispersion fitting order.
         do_plot : bool, optional

pyaml/tuning_tools/chromaticity_response_matrix.py

@@ -42,7 +42,8 @@ class ChromaticityResponseMatrix(MeasurementTool, DynamicValidation):
     chromaticity_name : str
         Name of the chromaticity monitor used to measure the response.
     sextu_delta : float
-        Default sextupole excitation applied during the measurement.
+        Default sextupole-strength excitation applied during the measurement,
+        in the configured sextupole strength unit (typically ``m^-2``).
     n_step : int, optional
         Default number of excitation steps used to fit the response.
     sleep_between_step : float, optional
@@ -125,19 +126,20 @@ def callback(action: Action, data:dict):
         Parameters
         ----------
         sextu_delta : float
-            Delta strength used to get the response matrix
+            Sextupole-strength change in the configured sextupole unit
+            (typically ``m^-2``).
         n_step : int, optional
             Number of step for fitting the chomaticity slope [-sextu_delta/n_step..sextu_delta/n_step]
             Default from config
         sleep_between_step : float
-            Default time sleep after sextu excitation
-            Default: from config
+            Delay in seconds after sextupole excitation.
+            Default: from config.
         n_avg_meas : int, optional
             Default number of chromaticity measurement per step used for averaging
             Default from config
         sleep_between_meas : float
-            Default time sleep between two chomaticity measurment
-            Default: from config
+            Delay in seconds between two chromaticity measurements.
+            Default: from config.
         callback : Callable, optional
             Callback executed after each strength setting or measurement.
             See :py:meth:`~.measurement_tool.MeasurementTool.send_callback`.
@@ -151,9 +153,9 @@ def callback(action: Action, data:dict):
               step:int # The current step
               avg_step:int # The current averaging step
               magnet:str # The magnet being excited
-              strength:float # Magnet strength
-              chroma:np.array # The measured chroma (on Action.MEASURE)
-              dchroma:np.array # The chroma variation (on Action.RESTORE)
+              strength:float # Sextupole strength, typically in m^-2
+              chroma:np.array # Dimensionless measured chromaticity (on Action.MEASURE)
+              dchroma:np.array # Chromaticity change per sextupole-strength unit (on Action.RESTORE)
 
         Returns
         -------