Inspect an Accelerator

This tutorial shows how to find out what an accelerator contains using the yellow pages, and how to access what you found.

As a reminder, an accelerator contains one or several control modes (for example live and design). Each control mode contains the same elements (magnets, BPMs, …), arrays (named groups of elements) and tuning tools. See Introduction to pyAML for an overview.

Prerequisites

This tutorial requires an existing pyAML configuration file.

The example uses the configuration provided by the pyaml-test-lattice package.

# Get the path to the configuration file
from pyaml_test_lattice import configurations

# List available files and their descriptions
configurations

{
'UUID_database/fodo_1gev_6d_database.yaml': YAML database for "fodo_1gev_6d.json" lattice used to generate pyaml and dt4acc configurations,
'dt4acc/fodo_1gev_6d_dt4acc_epics.json': dt4acc generic-EPICS configuration file for "fodo_1gev_6d.json" lattice,
'dt4acc/fodo_1gev_6d_dt4acc_tango.json': dt4acc Tango configuration file for "fodo_1gev_6d.json" lattice,
'pyaml/epics/pyaml-cs-oa/fodo_1gev_6d_pyaml-epics.yaml': pyAML accelerator configuration for the pyaml-cs-oa EPICS bindings (dt4acc generic EPICS twin).,
'pyaml/orm.json': Orbit response matrix (HCorr/VCorr -> BPM) measured in design mode (6D lattice) for "fodo_1gev_6d.json", used by DEFAULT_ORBIT_CORRECTION.,
'pyaml/tango/pyaml-cs-oa/fodo_1gev_6d_pyaml-oa.yaml': pyAML accelerator configuration for the pyaml-cs-oa TANGO bindings.,
'pyaml/tango/pyaml-cs-oa/fodo_1gev_6d_pyaml_catalogs-oa.yaml': Catalog configuration for the pyaml-cs-oa TANGO bindings.,
'pyaml/tango/tango-pyaml/fodo_1gev_6d_pyaml.yaml': pyAML accelerator configuration for the tango-pyaml bindings.,
'pyaml/tango/tango-pyaml/fodo_1gev_6d_pyaml_catalogs.yaml': Catalog configuration for the tango-pyaml bindings.,
'pyaml/trm.json': Tune response matrix (QForTune -> BETATRON_TUNE) measured in design mode (6D disabled) for "fodo_1gev_6d.json", used by DEFAULT_TUNE_CORRECTION.
}

This tutorials uses a pyAML configuration for TANGO but you can switch to the configuration for EPICS if you want to try with that instead.

Load the Accelerator

from pyaml.accelerator import Accelerator
accelerator = Accelerator.load(configurations["pyaml/tango/pyaml-cs-oa/fodo_1gev_6d_pyaml-oa.yaml"])

07 Oct 2026, 08:00:39 | WARNING | PyAML OA control system binding (0.3.1) initialized with name 'live' and prefix=''

The Yellow Pages

The yellow pages are a directory of everything the accelerator provides: the control modes and, sorted by category, the arrays, the tuning tools and the diagnostics. They are built automatically by scanning every control mode, so they always reflect what is configured.

Printing them gives an overview:

yp = accelerator.yellow_pages
print(yp)

Controls:
    live
    .

Simulators:
    design
    .

Arrays:
    BPM                   (pyaml.arrays.bpm_array)                size=16
    HCorr                 (pyaml.arrays.magnet_array)             size=16
    VCorr                 (pyaml.arrays.magnet_array)             size=16
    QForTune              (pyaml.arrays.magnet_array)             size=32
    Cell1                 (pyaml.arrays.element_array)            size=6
    Cell2                 (pyaml.arrays.element_array)            size=6
    Cell3                 (pyaml.arrays.element_array)            size=6
    Cell4                 (pyaml.arrays.element_array)            size=6
    Cell5                 (pyaml.arrays.element_array)            size=6
    Cell6                 (pyaml.arrays.element_array)            size=6
    Cell7                 (pyaml.arrays.element_array)            size=6
    Cell8                 (pyaml.arrays.element_array)            size=6
    Cell9                 (pyaml.arrays.element_array)            size=6
    Cell10                (pyaml.arrays.element_array)            size=6
    Cell11                (pyaml.arrays.element_array)            size=6
    Cell12                (pyaml.arrays.element_array)            size=6
    Cell13                (pyaml.arrays.element_array)            size=6
    Cell14                (pyaml.arrays.element_array)            size=6
    Cell15                (pyaml.arrays.element_array)            size=6
    Cell16                (pyaml.arrays.element_array)            size=6
    .

Tools:
    DEFAULT_TUNE_CORRECTION (pyaml.tuning_tools.tune)
    DEFAULT_TUNE_RESPONSE_MATRIX (pyaml.tuning_tools.tune_response_matrix)
    CHROMATICITY_MONITOR (pyaml.tuning_tools.chromaticity_monitor)
    DEFAULT_ORBIT_RESPONSE_MATRIX (pyaml.tuning_tools.orbit_response_matrix)
    DEFAULT_DISPERSION (pyaml.tuning_tools.dispersion)
    DEFAULT_ORBIT_CORRECTION (pyaml.tuning_tools.orbit)
    .

Diagnostics:
    BETATRON_TUNE (pyaml.diagnostics.tune_monitor)
    .

Categories and Entries

The entries are sorted in categories. keys() lists the entries of one category, or of all categories if none is given.

print(yp.categories())
print("Arrays:     ", yp.keys("Arrays"))
print("Tools:      ", yp.keys("Tools"))
print("Diagnostics:", yp.keys("Diagnostics"))

['Arrays', 'Tools', 'Diagnostics']
Arrays:      ['BPM', 'HCorr', 'VCorr', 'QForTune', 'Cell1', 'Cell2', 'Cell3', 'Cell4', 'Cell5', 'Cell6', 'Cell7', 'Cell8', 'Cell9', 'Cell10', 'Cell11', 'Cell12', 'Cell13', 'Cell14', 'Cell15', 'Cell16']
Tools:       ['DEFAULT_TUNE_CORRECTION', 'DEFAULT_TUNE_RESPONSE_MATRIX', 'CHROMATICITY_MONITOR', 'DEFAULT_ORBIT_RESPONSE_MATRIX', 'DEFAULT_DISPERSION', 'DEFAULT_ORBIT_CORRECTION']
Diagnostics: ['BETATRON_TUNE']

Check an Entry

has() tells whether an entry exists, and availability() in which control modes it can be used.

print(yp.has("QForTune"), yp.has("QF"))
print(yp.availability("DEFAULT_TUNE_CORRECTION"))

True False
{'live', 'design'}

Get an Object

An entry can be accessed as an attribute of the yellow pages. The result gives the object in each control mode where it is available.

qfortune = yp.QForTune
print(qfortune.keys())

dict_keys(['design', 'live'])

The object of a given mode is the same as the one reached through the control mode itself:

print(qfortune["design"] is accelerator.design.magnets.get("QForTune"))

True

Search Element Names

Indexing the yellow pages searches the names of the elements. With the name of an array, it returns the names of the elements of the array:

print(yp["Cell1"])

['QF_001', 'SF_001', 'QD_001', 'SD_001', 'BPM_001', 'COR_001']

Wildcards can be used to match several names:

print(yp["QF_00*"])

['QF_001', 'QF_002', 'QF_003', 'QF_004', 'QF_005', 'QF_006', 'QF_007', 'QF_008', 'QF_009']

For more complex searches, use a regular expression by starting the query with re::

print(yp["re:^(QF|QD)_01[0-2]$"])

['QF_010', 'QF_011', 'QF_012', 'QD_010', 'QD_011', 'QD_012']

get() does the same search and can be restricted to one control mode. Here the correctors COR_00x are combined-function magnets: the search returns both the magnets and their horizontal (.hcorrector) and vertical (.vcorrector) parts, which are the elements of the HCorr and VCorr arrays.

print(yp.get("COR_00*", mode="design"))

['COR_001.hcorrector', 'COR_002.hcorrector', 'COR_003.hcorrector', 'COR_004.hcorrector', 'COR_005.hcorrector', 'COR_006.hcorrector', 'COR_007.hcorrector', 'COR_008.hcorrector', 'COR_009.hcorrector', 'COR_001.vcorrector', 'COR_002.vcorrector', 'COR_003.vcorrector', 'COR_004.vcorrector', 'COR_005.vcorrector', 'COR_006.vcorrector', 'COR_007.vcorrector', 'COR_008.vcorrector', 'COR_009.vcorrector', 'COR_001', 'COR_002', 'COR_003', 'COR_004', 'COR_005', 'COR_006', 'COR_007', 'COR_008', 'COR_009']

Use the Result

The names returned by a search can be used to access the elements in any control mode:

for name in yp["re:^QF_00[1-3]$"]:
    magnet = accelerator.design.magnet.get(name)
    print(name, magnet.strength.get())

QF_001 0.5032201257634845
QF_002 0.5032201257634845
QF_003 0.5032201257634845