From 9109943955617b7a22a431e93d573b0a1dabe3a9 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 20:14:36 +0200 Subject: [PATCH 1/4] Change to the interface is exactly the same. --- docs/source/explanation/control-modes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/explanation/control-modes.md b/docs/source/explanation/control-modes.md index 823b862..b46b417 100644 --- a/docs/source/explanation/control-modes.md +++ b/docs/source/explanation/control-modes.md @@ -1,6 +1,6 @@ # Control Modes -A control mode is one way of accessing the accelerator. pyAML is built so that the core interactions with the machine work in exactly the same way in every control mode. The following requirements guide the design: +A control mode is one way of accessing the accelerator. PyAML is built so the interface is exactly the same in every control mode. The following requirements guide the design: - Core interactions work identically in all control modes. - All configured control modes are available at all times, and can be used at the same time in one script. From 254777919fe9aaa188963a654e529a3b6ecac9a1 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 20:29:26 +0200 Subject: [PATCH 2/4] Make it clearer that the names of the modes can be freely chosen and improve readability. --- docs/source/explanation/control-modes.md | 48 ++++++++++++++---------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/source/explanation/control-modes.md b/docs/source/explanation/control-modes.md index b46b417..1e1bc77 100644 --- a/docs/source/explanation/control-modes.md +++ b/docs/source/explanation/control-modes.md @@ -9,20 +9,26 @@ A control mode is one way of accessing the accelerator. PyAML is built so the in ## Available Control Modes -Two kinds of control modes are implemented today. +Two kinds of control modes are implemented today. Each mode is given a `name` which is used to access the mode. The name can be freely chosen but some standardized names are defined which should not be used for other modes. -**Live** (`ControlSystem`) -: Access to the accelerator through its control system. The values are read from and written to the control system through control-system bindings such as `tango-pyaml` or `pyaml-cs-oa`. The control system can be the real machine or a *virtual accelerator*, a simulation exposed through the same control-system interface as the real machine. By convention this mode is named `live`. +**ControlSystem** +: Access to the accelerator through a control system. The values are read from and written to the control system through control-system bindings such as `tango-pyaml` or `pyaml-cs-oa`. The control system can be the real machine or a *virtual accelerator*, i.e. a simulation exposed through the same control-system interface as the real machine. -**Design** (`Simulator`) -: Access to a simulation of the accelerator. Values are read from and written to a [pyAT](https://atcollab.github.io/at/p/index.html) lattice. Diagnostics such as BPMs and tune monitors return the values computed by the simulator. No control system is needed. By convention this mode is named `design`. + Current standardized names: + - `live` -The modes are declared in the configuration: control systems in `controls` and simulators in `simulators`. Each of them has a `name`, which is also the name of the attribute used to access it: +**Simulator** +: Access to a simulation of the accelerator. Values are read from and written to a [pyAT](https://atcollab.github.io/at/p/index.html) lattice. Diagnostics such as BPMs and tune monitors return the values computed by the simulator. No control system is needed. + + Current standardized names: + - `design` + +The modes are declared in the configuration: control systems in `controls` and simulators in `simulators`. For example: ```yaml class: pyaml.accelerator.Accelerator -facility: My facility -machine: sr +facility: my_facility +machine: accelerator energy: 1.0e9 simulators: - class: pyaml.lattice.simulator.Simulator @@ -36,29 +42,31 @@ devices: # ... magnets, BPMs, tuning tools ``` +The modes are accessed using: + ```python -accelerator.design # the Simulator -accelerator.live # the ControlSystem +accelerator.design # The simulator +accelerator.live # The controlSystem ``` -Several simulators or control systems can be defined, as long as they have different names. For example a second simulator loaded with a lattice including errors could be named `errors` and reached with `accelerator.errors`. +Several simulators or control systems can be defined, as long as they have different names. For example a second simulator loaded with a lattice including errors could be named `errors` and accessed with `accelerator.errors`. ## Using Control Modes -Because every mode exposes the same elements, arrays and tools, a script can be written once and run in any mode: +Since every mode exposes the same elements, arrays and tools, a script can be written once and run in any mode: ```python def correct_tune(sr): - sr.tune.set([0.2, 0.3]) + accelerator.tune.set([0.2, 0.3]) -correct_tune(accelerator.design) # try it on the simulator first -correct_tune(accelerator.live) # then run it on the machine +correct_tune(accelerator.design) # Try it on the simulator first +correct_tune(accelerator.live) # Then run it on the machine ``` A common pattern is to select the mode once at the top of a script: ```python -SR = accelerator.design # switch to accelerator.live to act on the machine +SR = accelerator.design # Change to accelerator.live to act on the machine ``` Different modes can also be used side by side, for example to compare the measured orbit with the simulated one: @@ -82,14 +90,14 @@ accelerator.design.magnets.get("HCorr").strengths.set(hcorr) ```{admonition} Planned, not implemented yet :class: note -The following control modes are described in the pyAML specification. They are part of the long-term plan of the collaboration and are **not available yet**. +The following control modes are described in the pyAML specification. They are part of the long-term plan and are **not available yet**. ``` **Errors / commissioning simulations** -: Simulators with lattices containing errors, and arrays of randomly generated error seeds, used to run simulated commissioning of a machine. +: Simulators with lattices containing errors used to run simulated commissioning of a machine. **Shadow (digital shadow)** -: A simulator that follows the real machine: settings read from the control system are applied to the model, which then computes the expected optics and diagnostics. Writing is forbidden in this mode. +: A simulator that follows the real machine: settings read from the control system are applied to the model which then computes the expected optics and diagnostics. Writing is forbidden in this mode. **Archive** -: A simulator loaded with the machine settings found in the archiving system at a given time, to reproduce and investigate a past situation. +: A simulator loaded with machine settings from an archiving system at a given timestamp to reproduce and investigate a past situation. From 206e68791ff0d4ca7ea66fea515cd9b6170a6fa8 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 20:32:26 +0200 Subject: [PATCH 3/4] Change name in configuration example since was wrongly changed. --- docs/source/explanation/control-modes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/explanation/control-modes.md b/docs/source/explanation/control-modes.md index 1e1bc77..7ec0149 100644 --- a/docs/source/explanation/control-modes.md +++ b/docs/source/explanation/control-modes.md @@ -28,7 +28,7 @@ The modes are declared in the configuration: control systems in `controls` and s ```yaml class: pyaml.accelerator.Accelerator facility: my_facility -machine: accelerator +machine: storage_ring energy: 1.0e9 simulators: - class: pyaml.lattice.simulator.Simulator From 7c52937c02b1129e0246dfcfc502972fbe4d595a Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 20:33:50 +0200 Subject: [PATCH 4/4] Add a sentence to explain that accelerator is the name of the accelerator object. --- docs/source/explanation/control-modes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/explanation/control-modes.md b/docs/source/explanation/control-modes.md index 7ec0149..942be2a 100644 --- a/docs/source/explanation/control-modes.md +++ b/docs/source/explanation/control-modes.md @@ -42,7 +42,7 @@ devices: # ... magnets, BPMs, tuning tools ``` -The modes are accessed using: +After loading the accelerator into an object called `accelerator`. The modes are accessed using: ```python accelerator.design # The simulator