Tutorials for use cases

docs/source/_static/custom.css

@@ -39,3 +39,11 @@ a.gh-link:visited {
 .sphx-glr-script-out pre {
   padding: 0;
 }
+
+.sphx-glr-thumbnails:empty {
+  display: none;
+}
+
+.sphx-glr-tag-list:empty {
+  display: none;
+}

docs/source/conf.py

@@ -56,10 +56,10 @@
 }
 
 exclude_patterns = [
-    "tutorials/*.py",
-    "tutorials/*.ipynb",
-    "tutorials/*.zip",
-    "tutorials/*.codeobj.json",
+    "tutorials/**/*.py",
+    "tutorials/**/*.ipynb",
+    "tutorials/**/*.zip",
+    "tutorials/**/*.codeobj.json",
 ]
 
 # -- Options for HTML output -------------------------------------------------

docs/tutorials/GALLERY_HEADER.rst

@@ -3,5 +3,7 @@ Tutorials
 
 Here you can find learning-oriented tutorials that guide you through the functionality of pyAML step by step.
 
-The tutorials are designed to be followed in sequence, gradually increasing in complexity but
-each tutorial is self-contained and can also be completed independently.
+The notebooks can be run using `Binder <https://mybinder.org>`_ or be downloaded
+and run on your own computer. If you want to run them on your own computer, see
+:doc:`User Installation <../how-to/installation/user-installation>` for
+instructions on how to install the requirements.

docs/tutorials/config.yaml

@@ -0,0 +1,15 @@
+type: pyaml.accelerator
+facility: pyAML test facility
+machine: pyaml test machine
+data_folder: null
+energy: 1000000000.0
+simulators:
+- type: pyaml.lattice.simulator
+  lattice: ${env:PYAML_TEST_LATTICE}
+  name: design
+devices:
+- type: pyaml.magnet.quadrupole
+  name: QF_001
+  model:
+    type: pyaml.magnet.identity_model
+    physics: ''

docs/tutorials/02_inspect_accelerator.py → docs/tutorials/functionality/02_inspect_accelerator.py

@@ -41,4 +41,4 @@
 # Show the Configuration of a Magnet
 # ------------------------------------
 
-accelerator.design.magnets.get("QF_001")
+accelerator.design.magnet.get("QF_001")

docs/tutorials/functionality/README.rst

@@ -0,0 +1,6 @@
+Functionality
+-------------
+
+These tutorials cover the functionality of pyAML. They are designed to be
+followed in sequence, gradually increasing in complexity, but each tutorial is
+self-contained and can also be completed independently.

docs/tutorials/functionality/config.yaml

@@ -0,0 +1,15 @@
+type: pyaml.accelerator
+facility: pyAML test facility
+machine: pyaml test machine
+data_folder: null
+energy: 1000000000.0
+simulators:
+- type: pyaml.lattice.simulator
+  lattice: ${env:PYAML_TEST_LATTICE}
+  name: design
+devices:
+- type: pyaml.magnet.quadrupole
+  name: QF_001
+  model:
+    type: pyaml.magnet.identity_model
+    physics: ''

docs/tutorials/use_cases/README.rst

@@ -0,0 +1,4 @@
+Use Cases
+---------
+
+These tutorials demonstrate how pyAML can be used for specific use cases.

docs/tutorials/use_cases/chromaticity-measurement.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+# coding: utf-8
+# ---
+# jupyter:
+#   jupytext:
+#     cell_metadata_filter: -all
+#     custom_cell_magics: kql
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.11.2
+#   kernelspec:
+#     display_name: pyaml-documentation
+#     language: python
+#     name: python3
+# ---
+
+# %%
+"""Chromaticity Measurement
+============================
+
+This tutorial shows how to measure the chromaticity.
+"""
+
+# %%
+# Prerequisites
+# -------------
+#
+# The tutorial requires an existing pyAML configuration file which includes configuration
+# of the chromaticity monitor.
+#
+# The example uses the configuration provided by the ``pyaml-test-lattice`` package.
+
+from pyaml.common.constants import Action
+from pyaml_test_lattice import configurations
+
+# %%
+# Load the Accelerator
+# --------------------
+
+from pyaml.accelerator import Accelerator
+accelerator = Accelerator.load(configurations["pyaml/tango/pyaml-cs-oa/fodo_1gev_6d_pyaml-oa.yaml"])
+
+# Print the string representation of the accelerator
+print(accelerator)
+
+# %%
+# Control Mode Choice
+# --------------------
+#
+# - ``accelerator.design`` — runs pyAT locally, no control system needed. Set ``wait_time = 0.0``.
+# - ``accelerator.live`` — connects to the real machine or virtual twin. Set ``wait_time`` to allow readback settling (typically 1.5–2 s).
+#
+# For ``live`` control mode you need a running control system or virtual accelerator.
+# If you want to skip this, run the notebook in `design`` mode only.
+
+# Use the design mode
+SR = accelerator.design
+
+# For live mode
+# SR = accelerator.live
+
+wait_time = 0.0 if SR == accelerator.design else 2.0
+
+# Print the string representation of the simulator
+print(SR)
+
+# %%
+# Momentum Compaction Factor
+# --------------------------
+#
+# The momentum compaction factor is needed to convert RF frequency deviation to
+# momentum deviation. It is computed from the lattice model (design mode).
+
+accelerator.design.get_lattice().disable_6d()
+alphac = accelerator.design.get_lattice().get_mcf()
+accelerator.design.get_lattice().enable_6d()
+print(f"Momentum compaction factor: αc = {alphac:.6e}")
+
+# %%
+# Chromaticity Measurement
+# ------------------------
+#
+# The chromaticity monitor is named `CHROMATICITY_MONITOR` in the configuration.
+# The measurement sweeps the RF frequency and fits the resulting tune shift.
+#
+# Parameters:
+#
+# - ``alphac`` — momentum compaction factor (from lattice above)
+# - ``fit_order`` — polynomial fit order (2 = quadratic)
+# - ``n_step`` — number of RF frequency steps
+# - ``sleep_between_meas`` / ``sleep_between_step`` — settling times (set to ``wait_time`` for live mode)
+# - ``do_plot=True`` — show the tune vs. δp fit
+
+def chroma_callback(action: int, cb_data: dict):
+    if action == Action.MEASURE:
+        print(f"Chromaticity: #{cb_data['step']} RF={cb_data['rf']:.2f} Hz, Tune={cb_data['tune']}")
+    return True
+
+# %%
+chroma_monitor = SR.get_chromaticity_monitor("CHROMATICITY_MONITOR")
+
+# Measure the chromaticity
+chroma_monitor.measure(
+    callback=chroma_callback,
+    do_plot=True,
+    alphac=alphac,
+    fit_order=2,
+    n_step=5,
+    sleep_between_meas=wait_time,
+    sleep_between_step=wait_time,
+)
+
+# Get the measured chromaticity
+ksi = chroma_monitor.chromaticity.get()
+print(f"Measured chromaticity: ξx = {ksi[0]:.3f}, ξy = {ksi[1]:.3f}")
+