From 2ff1562521e0ca7d631e0655907b81b48017ed39 Mon Sep 17 00:00:00 2001 From: PONS Date: Fri, 20 Mar 2026 12:06:08 +0100 Subject: [PATCH 1/2] Fix and add exmaple in docstring --- pyaml/apidoc/gen_api.py | 6 ++-- pyaml/tuning_tools/chromaticity.py | 8 +++++ .../chromaticity_response_matrix.py | 32 +++++++++++++++---- pyaml/tuning_tools/orbit_response_matrix.py | 20 +++++++++--- pyaml/tuning_tools/tune.py | 9 ++++++ pyaml/tuning_tools/tune_response_matrix.py | 23 +++++++++++-- 6 files changed, 84 insertions(+), 14 deletions(-) diff --git a/pyaml/apidoc/gen_api.py b/pyaml/apidoc/gen_api.py index 36509a37..e608bafc 100644 --- a/pyaml/apidoc/gen_api.py +++ b/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,12 +80,15 @@ "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.tuning_tool", + "pyaml._version", "pyaml.yellow_pages", ] diff --git a/pyaml/tuning_tools/chromaticity.py b/pyaml/tuning_tools/chromaticity.py index 31735ca4..c1d3dea0 100644 --- a/pyaml/tuning_tools/chromaticity.py +++ b/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) diff --git a/pyaml/tuning_tools/chromaticity_response_matrix.py b/pyaml/tuning_tools/chromaticity_response_matrix.py index 783dacdf..5c1a9db2 100644 --- a/pyaml/tuning_tools/chromaticity_response_matrix.py +++ b/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: diff --git a/pyaml/tuning_tools/orbit_response_matrix.py b/pyaml/tuning_tools/orbit_response_matrix.py index 4bc9d959..9f2bf17d 100644 --- a/pyaml/tuning_tools/orbit_response_matrix.py +++ b/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') diff --git a/pyaml/tuning_tools/tune.py b/pyaml/tuning_tools/tune.py index ce4090b7..78e15074 100644 --- a/pyaml/tuning_tools/tune.py +++ b/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) diff --git a/pyaml/tuning_tools/tune_response_matrix.py b/pyaml/tuning_tools/tune_response_matrix.py index 2c0d57db..1c8491c6 100644 --- a/pyaml/tuning_tools/tune_response_matrix.py +++ b/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: From 0e9222081d30ccb61081fe6fd9f038b3be12c9cc Mon Sep 17 00:00:00 2001 From: PONS Date: Fri, 20 Mar 2026 12:07:53 +0100 Subject: [PATCH 2/2] Fix and add exmaple in docstring --- pyaml/apidoc/gen_api.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pyaml/apidoc/gen_api.py b/pyaml/apidoc/gen_api.py index e608bafc..f44afc9f 100644 --- a/pyaml/apidoc/gen_api.py +++ b/pyaml/apidoc/gen_api.py @@ -88,7 +88,6 @@ "pyaml.tuning_tools.response_matrix_data", "pyaml.tuning_tools.tune_response_matrix", "pyaml.tuning_tools.tuning_tool", - "pyaml._version", "pyaml.yellow_pages", ]