From 87ea33233742c388331dab83bde92dd0b2f925f0 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 13:29:32 +0200 Subject: [PATCH 1/7] Make more generic so it doesn't sound like live and design are all possible control modes. --- docs/tutorials/functionality/00_introduction.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index 69e659c..23331bb 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -57,8 +57,8 @@ # # - **Accelerator**: the top-level object describing one machine. It is created from a # configuration. -# - **Control mode**: one way of accessing the accelerator. ``accelerator.live`` talks to the -# control system (the real machine or a virtual accelerator), ``accelerator.design`` talks +# - **Control mode**: one way of accessing the accelerator. In the figure above ``accelerator.live`` talks to the +# a control system and ``accelerator.design`` talks # to a simulation of the machine made with `pyAT `_. # Both provide exactly the same interface. # - **Element**: one object of the machine, such as a magnet, a BPM or the RF plant. From 0d96f5ab1d1a1e6c4c8084adff89b39c550315ce Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 13:30:17 +0200 Subject: [PATCH 2/7] Change RF plant to RF cavity since is better understood by the users. --- docs/tutorials/functionality/00_introduction.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index 23331bb..00d2296 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -61,7 +61,7 @@ # a control system and ``accelerator.design`` talks # to a simulation of the machine made with `pyAT `_. # Both provide exactly the same interface. -# - **Element**: one object of the machine, such as a magnet, a BPM or the RF plant. +# - **Element**: one object of the machine, such as a magnet, a BPM or a RF cavity. # - **Array**: a named group of elements which can be read or set in one call, such as all # the BPMs. # - **Attribute**: a value of an element that can be read with ``get()`` and written From 027365d58caa171934bcd0ddd531f8a48929badf Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 13:32:20 +0200 Subject: [PATCH 3/7] Make the explanation of the configuration more general since doesn't have to be a text file. --- docs/tutorials/functionality/00_introduction.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index 00d2296..cb45aa9 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -66,7 +66,7 @@ # the BPMs. # - **Attribute**: a value of an element that can be read with ``get()`` and written # with ``set()``, such as the ``strength`` of a magnet. -# - **Configuration**: a YAML or JSON file describing all of the above. Each item of the +# - **Configuration**: a structure (most commonly a YAML or JSON file) describing all of the above. Each item of the # configuration names a Python class with its ``class`` field, and **each other field is an # argument of that class's constructor**. This rule is explored in the first tutorial. # From 25e9e832a9b62a1adadaa5536695a65264fafdff Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 13:34:46 +0200 Subject: [PATCH 4/7] Fix the link to the glossary since has been moved. --- docs/tutorials/functionality/00_introduction.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index cb45aa9..daf2071 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -72,7 +72,7 @@ # # See :doc:`pyAML Structure <../../explanation/architecture>` and # :doc:`Control Modes <../../explanation/control-modes>` for more details, and the -# :doc:`Glossary <../../explanation/glossary>` for the definitions of the terms used in pyAML. +# :doc:`Glossary <../../glossary>` for the definitions of the terms used in pyAML. # %% # How the Tutorials Work From 2c688f817b47a76ddc8cda1faec1d90c57afce83 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 13:40:28 +0200 Subject: [PATCH 5/7] Modify how the tutorials work for better reading flow. --- docs/tutorials/functionality/00_introduction.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index daf2071..e5f00a4 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -78,10 +78,10 @@ # How the Tutorials Work # ---------------------- # -# **Running the tutorials.** Each tutorial can be run in the cloud with -# `Binder `_ using the launcher on its page, with nothing to install, -# or downloaded and run on your own computer, as a Jupyter notebook or a Python script -# (see below). +# **Running the tutorials.** Each tutorial can be run in the cloud without requiring +# to install or download anything by using the `Binder `_ launcher +# on the tutorial page or as a Jupyter notebook or a Python script on your own computer +# (see below for instructions). # # **The test machine.** The tutorials use a small test storage ring, with its lattice and # ready-made pyAML configurations, provided by the ``pyaml-test-lattice`` package. It is From 37c7e0f269dcb8733669ed55ea12069533314391 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 14:01:29 +0200 Subject: [PATCH 6/7] Update the instructions for how run locally so not need to be updated every time a new requirement is added. --- .../functionality/00_introduction.py | 32 +++++++------------ 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index e5f00a4..c23dea3 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -103,33 +103,23 @@ # # You need Python 3.11 or newer. Always install in a virtual environment, to avoid breaking # your Python installation (see :doc:`New to Python <../../how-to/getting-started/python-basics>` -# if you are not familiar with virtual environments). Then install: +# if you are not familiar with virtual environments). Then do: +# +# 1. Install the requirements for the tutorials # -# .. code-block:: bash +# .. code-block:: bash # -# pip install "accelerator-middle-layer[cs-oa-tango]" pyaml-test-lattice jupyterlab +# pip install -r https://raw.githubusercontent.com/python-accelerator-middle-layer/documentation/main/binder/requirements.txt # -# This installs: +# 2. [Optional] If you want to run as notebooks, install JupyterLab # -# - ``accelerator-middle-layer``: the ``pyaml`` core package. It also installs pyAT, used by -# the ``design`` control mode, together with numpy and matplotlib. -# - ``[cs-oa-tango]``: the ``pyaml-cs-oa`` control-system bindings for TANGO. The ready-made -# configurations of the test machine declare a ``live`` control mode using these bindings, -# so they are needed to load them, even if you only use the ``design`` control mode. -# - ``pyaml-test-lattice``: the test machine, with its lattice and pyAML configurations. -# - ``jupyterlab``: to open the tutorials as notebooks. It is not needed to run them as -# Python scripts. +# .. code-block:: bash # -# The other control-system bindings (``cs-oa-epics``, ``tango-pyaml``) are only needed to -# connect to your own control system, see -# :doc:`User Installation <../../how-to/installation/user-installation>`. To get exactly the -# same environment as on Binder, install the -# `Binder requirements `_ -# instead: ``pip install -r binder/requirements.txt`` from a clone of the documentation -# repository. +# pip install jupyterlab # -# Finally, download a tutorial as a notebook or a Python script with the download links in -# the right sidebar of its page, and run it with ``jupyter lab`` or ``python``. +# Finally, download a tutorial as a notebook or a Python script using the download link in +# the right sidebar of the tutorial's page, and run it with ``jupyter lab`` or ``python``. +# You can also download all tutorials in one go on the :doc:`Tutorials <../index>` main page. # %% # Where to Go Next From 73f2b6650d489110ba623ba173d4abb799cfb82f Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 14:09:41 +0200 Subject: [PATCH 7/7] Change where to go next to not have to modify every time a new tutorial is added. --- .../functionality/00_introduction.py | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index c23dea3..8615b93 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -124,23 +124,21 @@ # %% # Where to Go Next # ---------------- +# +# There are two type of tutorials: +# +# 1. **Functionality**: These cover the functionality of pyAML. +# +# 2. **Use cases**: These apply pyAML to real tasks. +# +# The tutorials are designed to first follow the functionality and then the use cases +# but they can also be run independently depending on your interests. +# +# For more background, read the explanations: # -# The tutorials are designed to be followed in this order: -# -# 1. :doc:`Create an Accelerator <01_create_accelerator>`: create an accelerator -# interactively and from a configuration file, and learn how the configuration maps to -# Python classes. -# 2. :doc:`Inspect an Accelerator <02_inspect_accelerator>`: explore what a complete -# accelerator configuration contains. -# 3. The **use cases**, which apply pyAML to real tasks: -# :doc:`tune correction <../use_cases/tune-correction>`, -# :doc:`orbit correction <../use_cases/orbit_correction>` and -# :doc:`chromaticity measurement <../use_cases/chromaticity-measurement>`. -# -# For more background, read the explanations: -# :doc:`What is pyAML? <../../explanation/about>`, -# :doc:`pyAML Structure <../../explanation/architecture>`, -# :doc:`Control Modes <../../explanation/control-modes>` and -# :doc:`Configuration Structure and Syntax <../../explanation/configuration>`. +# - :doc:`What is pyAML? <../../explanation/about>` +# - :doc:`pyAML Structure <../../explanation/architecture>` +# - :doc:`Control Modes <../../explanation/control-modes>` +# - :doc:`Configuration Structure and Syntax <../../explanation/configuration>` # sphinx_gallery_thumbnail_path = '_static/pyaml-hierarchy.svg'