python-accelerator-middle-layer · simoneliuzzo · Nov 28, 2025 · Nov 7, 2025 · Nov 7, 2025 · Nov 7, 2025
diff --git a/.gitignore b/.gitignore
@@ -81,6 +81,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
+docs/jupyter_execute/
 
 # PyBuilder
 .pybuilder/

diff --git a/docs/conf.py b/docs/conf.py
@@ -121,14 +121,6 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {
-    "collapse_navigation": False,
-    "display_version": True,
-    "logo_only": True,
-    "navigation_depth": 6,
-    "rightsidebar": True,
-    "relbarbgcolor": "black",
-}
 
 
 # Name of an image file (path relative to the configuration directory)
@@ -137,8 +129,15 @@
 # its width should therefore not exceed 200 pixels.
 html_logo = "_static/img/logo.png"
 html_copy_source = False
+
 html_theme_options = {
-    "github_url": "https://github.com/atcollab/at",
+    "collapse_navigation": False,
+    "display_version": True,
+    "logo_only": True,
+    "navigation_depth": 6,
+    "rightsidebar": True,
+    "relbarbgcolor": "black",
+    "github_url": "https://github.com/python-accelerator-middle-layer/pyaml",
     "logo": {
         "image_light": "_static/img/logo.png",
         "image_dark": "_static/img/dark.png",

diff --git a/docs/index.rst b/docs/index.rst
@@ -35,6 +35,7 @@ Documentation
     Load a configuration file <notebooks/load_configuration>
     Switch design live <notebooks/live_design>
     Select a control system <notebooks/control_system>
+    Arrays <notebooks/arrays>
 
 .. toctree::
    :caption: Modules:

diff --git a/docs/notebooks/arrays.ipynb b/docs/notebooks/arrays.ipynb
@@ -0,0 +1,59 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "40dec8f5",
+   "metadata": {},
+   "source": [
+    "# use of magnet arrays\n",
+    "\n",
+    "In pyAML it is possible to configure magnet arrays (families of magnets)\n",
+    "\n",
+    "Some families are available by default:\n",
+    "- dipoles\n",
+    "- quadrupoles\n",
+    "- skewquadrupoles\n",
+    "- sextupoles\n",
+    "- horcorrectors\n",
+    "- vercorrectors\n",
+    "- octupoles\n",
+    "\n",
+    "Any other family (in the example my-family-of-quads) may be defined when configuring pyAML, using defined devices.\n",
+    "\n",
+    "```\n",
+    "type: pyaml.accelerator\n",
+    "name: sr\n",
+    "arrays:\n",
+    "  - type: pyaml.arrays.magnet\n",
+    "    name: my-family-of-quads\n",
+    "    elements:\n",
+    "      - QD2A-C03\n",
+    "      - QD2E-C04\n",
+    "      - QD2A-C05\n",
+    "devices: \n",
+    "  - type: pyaml.magnet.quadrupole\n",
+    "    name: QD2A-C03\n",
+    "  - type: pyaml.magnet.quadrupole\n",
+    "    name: QD2E-C04\n",
+    "  - type: pyaml.magnet.quadrupole\n",
+    "    name: QD2A-C05\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a78867b0",
+   "metadata": {},
+   "source": [
+    "Below some feature of magnets arrays is presented"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/notebooks/control_system.ipynb b/docs/notebooks/control_system.ipynb
@@ -8,14 +8,92 @@
     "# Control System set up"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "62672006",
+   "metadata": {},
+   "source": [
+    "The control system interface is in a separated package from pyaml\n",
+    "\n",
+    "pyaml itself: \\\n",
+    "pip install accelerator-middle-layer\n",
+    "\n",
+    "tango interface to pyaml: \\\n",
+    "pip install tango-pyaml \n",
+    "\n",
+    "ophyd-asynch interface to pyaml: \\\n",
+    "pip install pyaml-oa-cs          \n",
+    "\n",
+    "If the above packages are installed the examples below will work (also in the same script)"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "62672006",
+   "id": "ae7657cc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyaml.accelerator import Accelerator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ff7bfc05",
+   "metadata": {},
+   "source": [
+    "Assuming these lines are present in ../../tests/config/EBSTune_TANGO.yaml\n",
+    "```\n",
+    "type: pyaml.accelerator\n",
+    "name: sr\n",
+    "energy: 6e9\n",
+    "controls:\n",
+    "  - type: tango.pyaml.controlsystem\n",
+    "      tango_host: ebs-simu-3:10000\n",
+    "      name: live\n",
+    "...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "86dec08e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# work with TANGO\n",
+    "SR_Tango: Accelerator = Accelerator.load(\"../../tests/config/EBSTune_TANGO.yaml\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a61409b3",
+   "metadata": {},
+   "source": [
+    "Assuming these lines are present in ../../tests/config/EBSTune_OPHYDASYNCH.yaml\n",
+    "```\n",
+    "type: pyaml.accelerator\n",
+    "name: sr\n",
+    "energy: 6e9\n",
+    "controls:\n",
+    "  - type: pyaml-cs-oa.pyaml.controlsystem\n",
+    "      name: live\n",
+    "...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "637bc8cf",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pyaml.pyaml import PyAML, pyaml"
+    "# work with Ophyd-Asynch\n",
+    "SR_OphydAsynch: Accelerator = Accelerator.load(\n",
+    "    \"../../tests/config/EBSTune_OPHYDASYNCH.yaml\"\n",
+    ")"
    ]
   }
  ],

diff --git a/docs/notebooks/live_design.ipynb b/docs/notebooks/live_design.ipynb
diff --git a/docs/notebooks/load_configuration.ipynb b/docs/notebooks/load_configuration.ipynb
@@ -10,14 +10,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "id": "7204f09a",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pyaml.pyaml import PyAML, pyaml\n",
+    "from pyaml.accelerator import Accelerator\n",
     "\n",
-    "ml: PyAML = pyaml(\"../../tests/config/EBSTune.yaml\")"
+    "SR: Accelerator = Accelerator.load(\"../../tests/config/EBSTune.yaml\")"
    ]
   },
   {
@@ -35,59 +35,55 @@
     "It looks like this: \n",
     "\n",
     "```\n",
-    "type: pyaml.pyaml\n",
-    "instruments:\n",
-    "  - type: pyaml.instrument\n",
-    "    name: sr               \n",
-    "    energy: 6e9\n",
-    "    simulators:\n",
-    "      - type: pyaml.lattice.simulator\n",
-    "        lattice: sr/lattices/ebs.mat\n",
-    "        name: design\n",
-    "    controls:\n",
-    "      - type: tango.pyaml.controlsystem\n",
-    "        tango_host: ebs-simu-3:10000\n",
-    "        name: live\n",
-    "    data_folder: /data/store\n",
-    "    arrays:\n",
-    "      - type: pyaml.arrays.magnet\n",
-    "        name: QForTune\n",
-    "        elements:\n",
-    "          - QD2E-C04\n",
-    "          - QD2A-C05\n",
-    "          - QD2E-C05\n",
-    "          - QD2A-C06\n",
-    "          - QD2E-C06\n",
-    "          - QD2A-C07\n",
-    "          - ...\n",
-    "    devices: \n",
-    "    - type: pyaml.magnet.quadrupole\n",
-    "      name: QD2A-C03\n",
-    "      model:\n",
-    "        type: pyaml.magnet.linear_model\n",
-    "        calibration_factor: 1.002096389\n",
-    "        crosstalk: 0.99912\n",
-    "        curve:\n",
-    "          type: pyaml.configuration.csvcurve\n",
-    "          file: sr/magnet_models/QD2_strength.csv\n",
-    "        unit: 1/m\n",
-    "        powerconverter:\n",
-    "          type: tango.pyaml.attribute\n",
-    "          attribute: srmag/vps-qd2/c03-a/current\n",
-    "          unit: A\n",
-    "    - ... \n",
-    "    - ...\n",
-    "    - ...\n",
-    "    - type: pyaml.diagnostics.tune_monitor\n",
-    "      name: BETATRON_TUNE\n",
-    "      tune_h:\n",
-    "        type: tango.pyaml.attribute_read_only\n",
-    "        attribute: srdiag/tune/tune_h\n",
-    "        unit: mm\n",
-    "      tune_v:\n",
-    "        type: tango.pyaml.attribute_read_only\n",
-    "        attribute: srdiag/tune/tune_v\n",
-    "        unit: mm\n",
+    "type: pyaml.accelerator\n",
+    "name: sr\n",
+    "energy: 6e9\n",
+    "simulators:\n",
+    "  - type: pyaml.lattice.simulator\n",
+    "    lattice: sr/lattices/ebs.mat\n",
+    "    name: design\n",
+    "controls:\n",
+    "  - type: tango.pyaml.controlsystem\n",
+    "    tango_host: ebs-simu-3:10000\n",
+    "    name: live\n",
+    "\n",
+    "data_folder: /data/store\n",
+    "  arrays:\n",
+    "    - type: pyaml.arrays.magnet\n",
+    "      name: QForTune\n",
+    "      elements:\n",
+    "        - QD2A-C03\n",
+    "        - QD2E-C04\n",
+    "        - QD2A-C05\n",
+    "        - ...\n",
+    "  devices: \n",
+    "  - type: pyaml.magnet.quadrupole\n",
+    "    name: QD2A-C03\n",
+    "    model:\n",
+    "      type: pyaml.magnet.linear_model\n",
+    "      calibration_factor: 1.002096389\n",
+    "      crosstalk: 0.99912\n",
+    "      curve:\n",
+    "        type: pyaml.configuration.csvcurve\n",
+    "        file: sr/magnet_models/QD2_strength.csv\n",
+    "      unit: 1/m\n",
+    "      powerconverter:\n",
+    "        type: tango.pyaml.attribute\n",
+    "        attribute: srmag/vps-qd2/c03-a/current\n",
+    "        unit: A\n",
+    "  - ... \n",
+    "  - ...\n",
+    "  - ...\n",
+    "  - type: pyaml.diagnostics.tune_monitor\n",
+    "    name: BETATRON_TUNE\n",
+    "    tune_h:\n",
+    "      type: tango.pyaml.attribute_read_only\n",
+    "      attribute: srdiag/tune/tune_h\n",
+    "      unit: mm\n",
+    "    tune_v:\n",
+    "      type: tango.pyaml.attribute_read_only\n",
+    "      attribute: srdiag/tune/tune_v\n",
+    "      unit: mm\n",
     "```\n"
    ]
   },