From 095c635750557f7b036cf38639e49a8e01d0e55b Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 2 Oct 2026 19:10:47 +0200 Subject: [PATCH 1/2] Moved test lattice explanation to separate page and reformatted content for the configuration explanation. --- docs/source/explanation/index.md | 1 + docs/source/explanation/test_lattice.md | 15 +++++ .../functionality/01_create_accelerator.py | 57 ++++++------------- 3 files changed, 34 insertions(+), 39 deletions(-) create mode 100644 docs/source/explanation/test_lattice.md diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index a59fd96..d640dec 100644 --- a/docs/source/explanation/index.md +++ b/docs/source/explanation/index.md @@ -11,4 +11,5 @@ control-modes configuration schema_and_validation catalog +test_lattice ``` diff --git a/docs/source/explanation/test_lattice.md b/docs/source/explanation/test_lattice.md new file mode 100644 index 0000000..0e408bc --- /dev/null +++ b/docs/source/explanation/test_lattice.md @@ -0,0 +1,15 @@ +# Test Lattice + +The test lattice, `fodo_1gev_6d`, is a small 1 GeV electron storage ring made of +**16 identical FODO cells** of 4.8 m, for a circumference of 76.8 m. Each cell contains a +focusing quadrupole `QF` and sextupole `SF`, a beam position monitor `BPM`, a corrector +`COR` acting in both planes, a dipole `B`, a defocusing quadrupole `QD` and sextupole +`SD`, and a second dipole `B`: + +```{figure} /_static/fodo-cell.svg +:alt: Layout of one FODO cell of the test lattice +:width: 100% + +Each element is named after its family and a three-digit index equal to the cell number: +`QF_001` is the focusing quadrupole of the first cell. This is the magnet used in +this tutorial. \ No newline at end of file diff --git a/docs/tutorials/functionality/01_create_accelerator.py b/docs/tutorials/functionality/01_create_accelerator.py index a7da77a..b2ab6a2 100644 --- a/docs/tutorials/functionality/01_create_accelerator.py +++ b/docs/tutorials/functionality/01_create_accelerator.py @@ -40,26 +40,7 @@ # `pyAT `_. # # The example uses the lattice provided by the ``pyaml-test-lattice`` package. -# -# The Test Lattice -# ~~~~~~~~~~~~~~~~ -# -# The test lattice, ``fodo_1gev_6d``, is a small 1 GeV electron storage ring made of -# **16 identical FODO cells** of 4.8 m, for a circumference of 76.8 m. Each cell contains a -# focusing quadrupole ``QF`` and sextupole ``SF``, a beam position monitor ``BPM``, a corrector -# ``COR`` acting in both planes, a dipole ``B``, a defocusing quadrupole ``QD`` and sextupole -# ``SD``, and a second dipole ``B``: -# -# .. figure:: /_static/fodo-cell.svg -# :alt: Layout of one FODO cell of the test lattice -# :width: 100% -# -# One cell of the test lattice with the control-system name of each element -# (``cc`` is the cell number, from 01 to 16). -# -# Each element is named after its family and a three-digit index equal to the cell number: -# ``QF_001`` is the focusing quadrupole of the first cell. This is the magnet used in -# this tutorial. +# Go to `Test lattice <../../explanation/test_lattice.html>`_ for details about the lattice. # Get the path to the lattice file # sphinx_gallery_thumbnail_path = '_static/create_accelerator.png' @@ -150,22 +131,23 @@ # Configuration files can be written in YAML or JSON. This example shows a YAML file. # %% -# The Configuration Rule -# ~~~~~~~~~~~~~~~~~~~~~~ -# A configuration file describes the same objects as the ones created in approach 1, -# following one simple rule: +# .. admonition:: The Configuration Rule +# +# A configuration file describes the same objects as the ones created in approach 1, +# following one simple rule: # -# - the ``class`` field gives the full path of the Python class to create, -# - **every other field is an argument of the constructor of that class**, with the same name, -# - when an argument is itself an object, its value is a nested item with its own ``class``. +# - The ``class`` field gives the full path of the Python class to create, +# - **Every other field is an argument of the constructor of that class** with the same +# name as the field and the value to pass to the constructor, +# - When an argument is itself an object, its value is a nested item with its own ``class`` field. # -# For example, in approach 1 the quadrupole was created with: +# In approach 1 the quadrupole was created with: # # .. code-block:: python # # Quadrupole(name="QF_001", model=IdentityMagnetModel(physics="")) # -# which becomes in the configuration file: +# When writing a configuration file instead it becomes: # # .. code-block:: yaml # @@ -175,8 +157,8 @@ # class: pyaml.magnet.identity_model.IdentityMagnetModel # physics: '' # -# The accepted fields of any class are therefore given by the arguments of its constructor, -# which you can see with ``help()``. The first lines show the constructor signature, and the +# Since the accepted fields of a class are given by the arguments of its constructor, you +# can see them using ``help()``. The first lines show the constructor signature, and the # ``Parameters`` section describes each argument: help(Quadrupole) @@ -184,15 +166,12 @@ # %% # Write the Configuration File # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# A configuration file is a plain text file. You can write it with any text editor. Other -# tools which can help you are described in the how-to guide +# You can write a configuration file with any text editor. +# More details, advice and tools that can help are described in the how-to guide # :doc:`Create and Load Configuration <../../how-to/configuration/create-configuration>`. # -# The file below describes the same accelerator as in approach 1. Compare each item with -# the Python code above: ``Accelerator(facility=..., machine=..., energy=..., simulators=[...], -# devices=[...])``, ``Simulator(name=..., lattice=...)`` and ``Quadrupole(name=..., model=...)``. -# -# The lattice path is given by an environment variable, using the ``${env:NAME}`` syntax. +# The file below describes the same accelerator as in approach 1. The main difference is +# that the lattice path is given by an environment variable, using the ``${env:NAME}`` syntax. # It could also be written directly as an absolute path, or relative to a root directory. configuration = """\ @@ -216,7 +195,7 @@ file.write(configuration) # %% -# Specify the Paths +# Specify the Path # ~~~~~~~~~~~~~~~~~ # The path to the configuration file can be specified as absolute or relative to a root directory. From 00ad2ebb04293b66c052e2c98740b9b0f800df24 Mon Sep 17 00:00:00 2001 From: Alexis Gamelin Date: Tue, 6 Oct 2026 17:43:47 +0200 Subject: [PATCH 2/2] Add back the test lattice text in the tutorial --- docs/source/explanation/index.md | 1 - docs/source/explanation/test_lattice.md | 15 ------------ .../functionality/01_create_accelerator.py | 23 +++++++++++++++++-- 3 files changed, 21 insertions(+), 18 deletions(-) delete mode 100644 docs/source/explanation/test_lattice.md diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index d640dec..a59fd96 100644 --- a/docs/source/explanation/index.md +++ b/docs/source/explanation/index.md @@ -11,5 +11,4 @@ control-modes configuration schema_and_validation catalog -test_lattice ``` diff --git a/docs/source/explanation/test_lattice.md b/docs/source/explanation/test_lattice.md deleted file mode 100644 index 0e408bc..0000000 --- a/docs/source/explanation/test_lattice.md +++ /dev/null @@ -1,15 +0,0 @@ -# Test Lattice - -The test lattice, `fodo_1gev_6d`, is a small 1 GeV electron storage ring made of -**16 identical FODO cells** of 4.8 m, for a circumference of 76.8 m. Each cell contains a -focusing quadrupole `QF` and sextupole `SF`, a beam position monitor `BPM`, a corrector -`COR` acting in both planes, a dipole `B`, a defocusing quadrupole `QD` and sextupole -`SD`, and a second dipole `B`: - -```{figure} /_static/fodo-cell.svg -:alt: Layout of one FODO cell of the test lattice -:width: 100% - -Each element is named after its family and a three-digit index equal to the cell number: -`QF_001` is the focusing quadrupole of the first cell. This is the magnet used in -this tutorial. \ No newline at end of file diff --git a/docs/tutorials/functionality/01_create_accelerator.py b/docs/tutorials/functionality/01_create_accelerator.py index b2ab6a2..d9858f3 100644 --- a/docs/tutorials/functionality/01_create_accelerator.py +++ b/docs/tutorials/functionality/01_create_accelerator.py @@ -40,7 +40,26 @@ # `pyAT `_. # # The example uses the lattice provided by the ``pyaml-test-lattice`` package. -# Go to `Test lattice <../../explanation/test_lattice.html>`_ for details about the lattice. +# +# The Test Lattice +# ~~~~~~~~~~~~~~~~ +# +# The test lattice, ``fodo_1gev_6d``, is a small 1 GeV electron storage ring made of +# **16 identical FODO cells** of 4.8 m, for a circumference of 76.8 m. Each cell contains a +# focusing quadrupole ``QF`` and sextupole ``SF``, a beam position monitor ``BPM``, a corrector +# ``COR`` acting in both planes, a dipole ``B``, a defocusing quadrupole ``QD`` and sextupole +# ``SD``, and a second dipole ``B``: +# +# .. figure:: /_static/fodo-cell.svg +# :alt: Layout of one FODO cell of the test lattice +# :width: 100% +# +# One cell of the test lattice with the control-system name of each element +# (``cc`` is the cell number, from 01 to 16). +# +# Each element is named after its family and a three-digit index equal to the cell number: +# ``QF_001`` is the focusing quadrupole of the first cell. This is the magnet used in +# this tutorial. # Get the path to the lattice file # sphinx_gallery_thumbnail_path = '_static/create_accelerator.png' @@ -196,7 +215,7 @@ # %% # Specify the Path -# ~~~~~~~~~~~~~~~~~ +# ~~~~~~~~~~~~~~~~ # The path to the configuration file can be specified as absolute or relative to a root directory. # Set the root directory