Merge pull request #224 from python-accelerator-middle-layer/doc-fix-tuning-tool

Fix and add exmaple in docstring

Author: JeanLucPons

pyaml/apidoc/gen_api.py

@@ -10,7 +10,6 @@
 
 modules = [
     "pyaml.accelerator",
-    "pyaml.apidoc.gen_api",
     "pyaml.arrays.array",
     "pyaml.arrays.bpm",
     "pyaml.arrays.bpm_array",
@@ -81,8 +80,10 @@
     "pyaml.tuning_tools.dispersion",
     "pyaml.tuning_tools.orbit",
     "pyaml.tuning_tools.orbit_response_matrix",
-    "pyaml.tuning_tools.measurement_tool",
+    "pyaml.tuning_tools.chromaticity",
     "pyaml.tuning_tools.tune",
+    "pyaml.tuning_tools.chromaticity_response_matrix",
+    "pyaml.tuning_tools.measurement_tool",
     "pyaml.tuning_tools.orbit_response_matrix_data",
     "pyaml.tuning_tools.response_matrix_data",
     "pyaml.tuning_tools.tune_response_matrix",

pyaml/tuning_tools/chromaticity.py

@@ -80,6 +80,14 @@ def __init__(self, cfg: ConfigModel):
         self._setpoint = np.array([np.nan, np.nan])
 
     def load(self, load_path: Path):
+        """
+        Dyanmically loads a response matrix.
+
+        Parameters
+        ----------
+        load_path : Path
+            Filename of the :class:`~.ResponseMatrixData` to load
+        """
         self._cfg.response_matrix = ResponseMatrixData.load(load_path)
         self._response_matrix = np.array(self._cfg.response_matrix._cfg.matrix)
         self._correctionmat = np.linalg.pinv(self._response_matrix)

pyaml/tuning_tools/chromaticity_response_matrix.py

@@ -22,7 +22,7 @@ class ConfigModel(MeasurementToolConfigModel):
     Parameters
     ----------
     sextu_array_name : str
-        Array name of quad used to adjust the tune
+        Array name of sextupole used to adjust the chromaticity
     chromaticity_name : str
         Name of the diagnostic chromaticy monitor
     sextu_delta : float
@@ -54,24 +54,44 @@ def measure(
         """
         Measure tune response matrix
 
+        **Example**
+
+        .. code-block:: python
+
+            from pyaml.accelerator import Accelerator
+            from pyaml.common.constants import Action
+
+            def callback(action: Action, data:dict):
+                print(f"{action}, data:{data}")
+                return True
+
+            sr = Accelerator.load("tests/config/EBSOrbit.yaml")
+            acc = sr.design
+
+            if acc.crm.measure(callback=callback):
+                acc.crm.save("ideal_crm.json")
+                acc.crm.save("ideal_crm.yaml", with_type="yaml")
+                acc.crm.save("ideal_crm.npz", with_type="npz")
+
+
         Parameters
         ----------
         sextu_delta : float
             Delta strength used to get the response matrix
         n_step: int, optional
-            Number of step for fitting the tune [-quad_delta/n_step..quad_delta/n_step]
+            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 quad exitation
+            Default time sleep after sextu exitation
             Default: from config
         n_avg_meas : int, optional
-            Default number of chroma measurement per step used for averaging
+            Default number of chromaticity measurement per step used for averaging
             Default from config
         sleep_between_meas: float
-            Default time sleep between two tune measurment
+            Default time sleep between two chomaticity measurment
             Default: from config
         callback : Callable, optional
-            Callback executed after each strength setting.
+            Callback executed after each strength setting or measurement.
             See :py:meth:`~.measurement_tool.MeasurementTool.send_callback`.
             If the callback return false, then the scan is aborted and strength restored.
             callback_data dict contains:

pyaml/tuning_tools/orbit_response_matrix.py

@@ -61,18 +61,30 @@ def measure(
         callback: Optional[Callable] = None,
     ):
         """
-        Measure orbit response matrix
+        Measure orbit response matrix.
+
+        **Example**
+
+        .. code-block:: python
+
+            sr = Accelerator.load("MyAccelerator.yaml")
+            acc = sr.design
+
+            if acc.orm.measure():
+                acc.orm.save("ideal_orm.json")
+                acc.orm.save("ideal_orm.yaml", with_type="yaml")
+                acc.orm.save("ideal_orm.npz", with_type="npz")
 
         Parameters
         ----------
         sleep_between_step: float
-            Default time sleep after quad exitation
+            Default time sleep after steerer exitation
             Default: from config
         n_avg_meas : int, optional
-            Default number of tune measurement per step used for averaging
+            Default number of orbit measurement per step used for averaging
             Default from config
         sleep_between_meas: float
-            Default time sleep between two tune measurment
+            Default time sleep between two orbit measurment
             Default: from config
         callback : Callable, optional
             example: callback(action:int, callback_data: 'Complicated struct')

pyaml/tuning_tools/tune.py

@@ -81,6 +81,15 @@ def __init__(self, cfg: ConfigModel):
         self._setpoint = np.array([np.nan, np.nan])
 
     def load(self, load_path: Path):
+        """
+        Dyanmically loads a response matrix.
+
+        Parameters
+        ----------
+        load_path : Path
+            Filename of the :class:`~.ResponseMatrixData` to load
+
+        """
         self._cfg.response_matrix = ResponseMatrixData.load(load_path)
         self._response_matrix = np.array(self._cfg.response_matrix._cfg.matrix)
         self._correctionmat = np.linalg.pinv(self._response_matrix)

pyaml/tuning_tools/tune_response_matrix.py

@@ -52,12 +52,31 @@ def measure(
         """
         Measure tune response matrix
 
+        **Example**
+
+        .. code-block:: python
+
+            from pyaml.accelerator import Accelerator
+            from pyaml.common.constants import Action
+
+            def callback(action: Action, data:dict):
+                print(f"{action}, data:{data}")
+                return True
+
+            sr = Accelerator.load("tests/config/EBSTune.yaml")
+            acc = sr.design
+
+            if acc.trm.measure(n_avg_meas=3,sleep_between_meas=5,callback=callback):
+                acc.trm.save("ideal_trm.json")
+                acc.trm.save("ideal_trm.yaml", with_type="yaml")
+                acc.trm.save("ideal_trm.npz", with_type="npz")
+
         Parameters
         ----------
         quad_delta : float
             Delta strength used to get the response matrix
         n_step: int, optional
-            Number of step for fitting the tune [-quad_delta/n_step..quad_delta/n_step]
+            Number of step for fitting the tune slope [-quad_delta/n_step..quad_delta/n_step]
             Default from config
         sleep_between_step: float
             Default time sleep after quad exitation
@@ -69,7 +88,7 @@ def measure(
             Default time sleep between two tune measurment
             Default: from config
         callback : Callable, optional
-            Callback executed after each strength setting.
+            Callback executed after each strength setting or measurement.
             See :py:meth:`~.measurement_tool.MeasurementTool.send_callback`.
             If the callback return false, then the scan is aborted and strength restored.
             callback_data dict contains: