# Commissioning simulations tools based on python Accelerator Toolbox

S. M. Liuzzo, N. Carmignani, L.R. Carver, L. Hoummi, T. Perron, S. White, I. Agapov, M. Boese, T. Hellert, J. Keil, et al.

► To cite this version:

S. M. Liuzzo, N. Carmignani, L.R. Carver, L. Hoummi, T. Perron, et al. Commissioning simulations tools based on python Accelerator Toolbox. Journal of Physics: Conference Series, 2024, 2687 (3), pp.032001. 10.1088/1742-6596/2687/3/032001. [hal-05099472](https://hal.science/hal-05099472v1)

HAL Id: hal-05099472

https://hal.science/hal-05099472v1

Submitted on 5 Jun 2025

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
PAPER • OPEN ACCESS

# Commissioning simulations tools based on python Accelerator Toolbox

To cite this article: S. M. Liuzzo et al 2024 *J. Phys.: Conf. Ser.* **2687** 032001

View the [article online](#) for updates and enhancements.

You may also like

- Analysis and correction of linear optics errors, and operational improvements in the Indus-2 storage ring
Riyasat Husain and A. D. Ghodke

- Commissioning of the PLS-II
S Shin, S Kwon, D-T Kim et al.

- Physics design of SSRF synchrotron radiation security
Xu Yi, Dai Zhi-Min and Liu Gui-Min

<figure><img src="image_2.png" /></figure>
# Commissioning simulations tools based on python Accelerator Toolbox<fnref n="1" />

S. M. Liuzzo<fnref n="2" />, N. Carmignani, L. R. Carver, L. Hoummi, T. Perron, S. White, ESRF, Grenoble, France

I. Agapov, M. Boese, T. Hellert, J. Keil, L. Malina, E. Musa, B. Veglia, DESY, Hambourg, Germany

**Abstract.** Storage ring commissioning-like simulations are necessary to assess the feasibility of proposed future lattice designs. This paper proposes a python package for commissioning-like simulations based on python accelerator toolbox (pyAT). The software includes: 1) errors definition, 2) correction routines from open trajectory to optics and coupling correction and 3) the evaluation of the relevant parameters, such as dynamic aperture (DA), injection efficiency (IE) and Touschek lifetime (TL). The software is fully exploiting parallel resources (local or on a computing cluster) and is thought to be easily configured for any machine (examples are given for EBS DBA and HMBA, for PETRA IV and for FCC-ee). Whenever possible analytic formulas are made available to the user. Several examples are detailed in this paper and included in the code as demonstrations of use.

## 1. Introduction

Commissioning simulations are mandatory for any new storage ring (SR) design. Running such simulations allows to define the procedures to achieve first turns, accumulation and finally low emittance tuning and optics corrections. Once all the correction steps are tuned and optimized these commissioning simulations show if the SR under study will be able to reach its design performance in terms of injection efficiency and Touschek lifetime. Commissioning simulations are thus mandatory for any SR not only to define the final performances in presence of realistic errors but also to evaluate maximum tolerated errors, to chose the optimal commissioning correction sequences and to asses the loss/gain in DA, IE, TL of optics adaptations performed while operating the SR. Tools for commissioning simulations are available based on several codes (among others see [1] and [2]), but are often difficult to adapt to other SR. Recently Simulated Commissioning (SC) [3] has been introduced to the community based on matlab accelerator toolbox (AT) [4]. Work has been carried out in the framework of the present project to provide a set of tools for commissioning simulations also for the python version of AT (pyAT) [5].

## 2. Implementation of a python AT based commissioning simulation toolkit

The actions expected from a commissioning simulation toolkit are rather basic:

* set errors based on a given error table to generate *N* possible realistic SR scenarios

<figure><img src="image_3.png" /></figure>

<footnote n="1">¹ This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 871072</footnote>

<footnote n="2">² simone.liuzzo@esrf.fr</footnote>
* correct lattice orbit, tune, optics and chromaticity

* compute relevant quantities such as dynamic aperture, IE, momentum acceptance (MA), TL, etc...

* visualize a summary of the results

The software tools developed (available for download here [6]) are designed considering also the following specifications:

* simple and user friendly definition of errors and corrections to apply

* a modular structure: each component of the code is stand-alone; other parts of the code may be added easily, as plugins

* provide tests, examples and demos for each sub-module and for the overall usage of the package

* exploit parallel computation (multiprocessing) on the local computer

* give the possibility to submit the jobs to a remote cluster for distributed computations; development done for the SLURM [7] cluster scheduler.

* keep organized data folders for each error seed

* allow to skip/postpone DA/MA

* fully exploit 6D tracking, with radiation and RF cavity managed by pyAT

* give access to analytic computations when possible

* flexibility in the definition of the correction sequence to be applied

A single configuration file holds all the lattice dependent information. This includes for example the location of steerers and multipoles required for each step of the correction. A flag is used to switch between local and cluster computing. In the first case lattices are analyzed in series, and computations are done exploiting all available local computing resources. In the second case, a given number of processors is charged to analyze the *N* lattice seed. In this case also the lattice seeds are analyzed in parallel. The two options are kept in order to make the code usable also by individuals that do not have access to large computing clusters.

In order to speed up the tests, and in particular to choose and fine tune the correction scheme it is often not necessary to compute DA, IE and MA. It is sufficient to look at basic lattice optics parameters such as orbit, tunes and optics. For this reason, the computation of DA, IE and MA may be excluded, with a significant gain in time (up to more than 90%).

All features of the pyAT tracking engine are inherited by the software. Full 6D tracking of electrons in presence of radiation, quantum diffusion and RF cavities may be performed by simply setting appropriately the input lattice.

Error setting is also based on the core pyAT. For the moment only the basic errors (alignment, gradient, rotation and BPM errors) are available, but work is ongoing on this topic and will be objective of future developments.

### 3. Correction using pyAT based commissioning simulation toolkit

The corrections available and tested are presently:

* first turns beam threading [8] (see Fig. 1)

* closed orbit correction

* tune correction

* chromaticity correction

* error model fit based on closed orbit response matrix (LOCO like optics correction)

* optics correction [9] (see Fig. 2)
<figure><img src="image_4.png" /><figcaption>**Figure 1.** Trajectory correction to get first turns and beam accumulation for the FCC-ee collider at 45.6 GeV [10].</figcaption></figure>

<figure><img src="image_5.png" /><figcaption>**Figure 2.** Optics dispersion and coupling correction based on measured orbit response matrix fit for the ESRF-EBS H7BA lattice [11, 12].</figcaption></figure>

* coupling correction

* normal and skew quadrupoles RDTs correction

In the near future also beam based alignment, NOECO [13] and tune correction from trajectory data will be added to the possible corrections.
These corrections may be done in any sequence and access is given to all relevant parameters for each correction. A typical correction sequence executes the corrections in the order listed above and iterates a few times before considering the lattice correction converged.

## 4. Use of analytic formulas

Several steps of corrections require the computation of response matrices ahead (for example the response of orbit to a variation of each steerer magnet in the lattice). Those matrices are computed based on the design lattice and stored in files such to be available for individual parallel correction computations of each error seed. These computations, even if done only once, may be rather long, in particular those necessary for the optics correction that require to compute the response of orbit at every steerer in both planes and for each normal and skew quadrupole in the lattice. Moreover in some cases it is necessary to update these matrices during the correction, thus multiplying the number of long computations. For this reason the code took advantage of recent analytic results [14] to make such computations as fast as possible. The details of such implementation are reported in a separated paper [15].

## 5. Typical output of pyAT commissioning simulations

The typical results of a full commissioning simulation in pyAT performed with the code presented in this paper are presented in Figures 3 and 4 for the EBS lattice. As an example Fig. 3 shows the distribution of rms orbit and rms beta beating before and after the commissioning sequence of corrections was applied. The same figures are produced for emittances, tunes, chromaticity and dispersion deviation compared to the model. Random alignment errors of 10 µm extracted from a Gaussian distribution truncated at $2\sigma$ are set in all dipoles, quadrupoles and sextupoles of each lattice.

## 6. Example of application to different lattices

The pyAT commissioning simulations code is thought to be easily applied to different lattice files for circular accelerators. The authors tested the software for four different lattices: ESRF's DBA, ESRF's EBS H7BA [11, 12], PETRA-IV H6BA [16] and FCC-ee at Z energy [10]. With modifications only to the first few lines of the example test code the simulations could run in all cases. The results obtained are summarized in table 1. All simulations assumed the same rms random errors of 10 µm (in dipoles quadrupoles and sextupoles) and the same sequence of corrections with the same parameters (not adjusted for each lattice). Analytic response matrices for orbit, tune dispersion and optics correction are used in all cases. For the PETRA-IV and FCC-ee lattices some of the quantities before correction are not available: the 50 lattice instances used for the computations are unstable before correction. In all cases the parameters after correction are reasonable and stable lattices are obtained.

## 7. Conclusions

A new software for storage ring commissioning simulations based on python AT has been developed. First results show that the code is flexible and easily adapted to different lattice optics. The code is available [6] and may be used, although it presently lacks documentation. The matlab SC software is already used by several facilities and is also beased on AT for tracking simualtions. Discussion among the authors led to the conclusion that conversion of the SC software to python would be more fruit-full than dedicating more efforts to continue the development of the code presented in this pages. The conversion of the SC code has already started. Part of the developments done for the code presented here will be included in the python converted SC code, in particular the implementation of the analytic formulas for response matrices. Compared to previous work, both codes lack the possibility to describe large survey errors as done in [17]. This possibility will be introduced in the final version of the code.
<figure><img src="image_6.png" /><figcaption>**Figure 3.** Rms closed orbit (top) and rms beta-beating deviation from model (bottom), before and after correction for pyAT commissioning simulations of 50 different error seeds for the ESRF EBS H7BA lattice.</figcaption></figure>
<figure><img src="image_7.png" /><figcaption>**Figure 4.** DA (top) and MA (bottom) after correction for 50 different error seeds for the EBS lattice.</figcaption></figure>
<table><caption>**Table 1.** Optics parameters before and after correction of 10 µm random errors in dipoles, quadrupoles and sextupoles. In parenthesis the values for horizontal and vertical plane respectively. The electron beam energy $E_0$ and circumference $C$ of each ring considered are reported.</caption><thead><tr><th></th><th>units</th><th>before</th><th>after</th></tr></thead><tbody><tr><td colspan="4">ESRF DBA</td></tr><tr><td>Δβ/β<sub>h,v</sub></td><td>%</td><td>(4.5, 2.7)</td><td>(0.1, 0.1)</td></tr><tr><td>Δη<sub>h,v</sub></td><td>mm</td><td>(5.8, 7.0)</td><td>(1.6, 1.4)</td></tr><tr><td>ε<sub>h,v</sub></td><td>pm rad</td><td>(4000, 24)</td><td>(4000, 0.5)</td></tr><tr><td>Δx<sub>h,v</sub></td><td>μm</td><td>(566, 467)</td><td>(13.3, 1.4)</td></tr><tr><td colspan="4">ESRF EBS H7BA</td></tr><tr><td>Δβ/β<sub>h,v</sub></td><td>%</td><td>(19.4, 11.1)</td><td>(0.2, 0.2)</td></tr><tr><td>Δη<sub>h,v</sub></td><td>mm</td><td>(17.3, 6.9)</td><td>(0.18,0.1)</td></tr><tr><td>ε<sub>h,v</sub></td><td>pm rad</td><td>(613, 94)</td><td>(140, 0)</td></tr><tr><td>Δx<sub>h,v</sub></td><td>μm</td><td>(725, 436)</td><td>(35,9)</td></tr><tr><td colspan="4">PETRA-IV H6BA</td></tr><tr><td>Δβ/β<sub>h,v</sub></td><td>%</td><td>(-, -)</td><td>(1.9, 2.3)</td></tr><tr><td>Δη<sub>h,v</sub></td><td>mm</td><td>(-, -)</td><td>(1.1, 1.2)</td></tr><tr><td>ε<sub>h,v</sub></td><td>pm rad</td><td>(-, -)</td><td>(38.8, 0.4)</td></tr><tr><td>Δx<sub>h,v</sub></td><td>μm</td><td>(-, -)</td><td>(37.3, 25.8)</td></tr><tr><td colspan="4">FCC-ee</td></tr><tr><td>Δβ/β<sub>h,v</sub></td><td>%</td><td>(3.6, 59.52)</td><td>(0.8, 4.3)</td></tr><tr><td>Δη<sub>h,v</sub></td><td>mm</td><td>(120.1, 82.6)</td><td>(26.0, 9.6)</td></tr><tr><td>ε<sub>h,v</sub></td><td>pm rad</td><td>(-, -)</td><td>(690.8, 0.17)</td></tr><tr><td>Δx<sub>h,v</sub></td><td>μm</td><td>(631, 289)</td><td>(29.8, 12.0)</td></tr></tbody></table>

References

[1] S.M. Liuzzo et al. Updates on Lattice Modeling and Tuning for the ESRF-EBS Lattice. In Proc. of International Particle Accelerator Conference (IPAC’16), Busan, Korea, May 8-13, 2016, number 7 in International Particle Accelerator Conference, pages 2818–2821, Geneva, Switzerland, June 2016. JACoW. doi:10.18429/JACoW-IPAC2016-WEPOW005.

[2] V. Sajaev. Commissioning simulations for the argonne advanced photon source upgrade lattice. Phys. Rev. Accel. Beams, 22:040102, Apr 2019.

[3] Thorsten Hellert, Christoph Steier, and Marco Venturini. Lattice correction and commissioning simulation of the advanced light source upgrade storage ring. Phys. Rev. Accel. Beams, 25:110701, Nov 2022.

[4] Boaz Nash, Nicola Carmignani, Laurent Farvacque, Simone Liuzzo, Thomas Perron, Pantaleo Raimondi, Reine Versteegen, and Simon White. New Functionality for Beam Dynamics in Accelerator Toolbox (AT). In 6th International Particle Accelerator Conference, page MOPWA014, 2015.

[5] W. A. H. Rogers, N. Carmignani, L. Farvacque, and B. Nash. pyAT: A Python Build of Accelerator Toolbox. In Proc. IPAC’17, pages 3855–3857. JACoW Publishing, Geneva, Switzerland.

[6] pyat commissioning simulations. https://gitlab.esrf.fr/BeamDynamics/commissioningsimulations. Accessed: 2023-03-06.

[7] Andy B. Yoo, Morris A. Jette, and Mark Grondona. Slurm: Simple linux utility for resource management. In Dror Feitelson, Larry Rudolph, and Uwe Schwiegelshohn, editors, Job Scheduling Strategies for Parallel Processing, pages 44–60, Berlin, Heidelberg, 2003. Springer Berlin Heidelberg.

[8] S M Liuzzo, N Carmignani, A Franchi, T Perron, K B Scheidt, E Taurel, L Torino, and S M White. Preparation of the ebs beam commissioning. Journal of Physics: Conference Series, 1350(1):012022, nov 2019.
[9] S.M. Liuzzo, N. Carmignani, L.R. Carver, L. Farvacque, T.P. Perron, P. Raimondi, and S.M. White.

[10] T.K. Charles, S. Aumon, B. Holzer, K. Oide, and F. Zimmermann. Low emittance tuning of fcc-ee. *Journal of Physics: Conference Series*, 1350(1):012006, nov 2019.

[11] Pantaleo Raimondi, Chamseddine Benabderrahmane, Paul Berkvens, Jean Claude Biasci, Pawel Borowiec, Jean-Francois Bouteille, Thierry Brochard, Nicholas B. Brookes, Nicola Carmignani, Lee R. Carver, Jean-Michel Chaize, Joel Chavanne, Stefano Checchia, Yuriy Chushkin, Filippo Cianciosi, Marco Di Michiel, Rudolf Dimper, Alessandro D'Elia, Dieter Einfeld, Friederike Ewald, Laurent Farvacque, Loys Goirand, Laurent Hardy, Jorn Jacob, Laurent Jolly, Michael Krisch, Gael Le Bec, Isabelle Leconte, Simone M. Liuzzo, Cristian Maccarrone, Thierry Marchial, David Martin, Mohamed Mezouar, Christian Nevo, Thomas Perron, Eric Plouviez, Harald Reichert, Pascal Renaud, Jean-Luc Revol, Benoît Roche, Kees-Bertus Scheidt, Vincent Serriere, Francesco Sette, Jean Susini, Laura Torino, Reine Versteegen, Simon White, and Federico Zontone. The extremely brilliant source storage ring of the european synchrotron radiation facility. *Communications Physics*, 6(1):82, 2023.

[12] P. Raimondi, N. Carmignani, L. R. Carver, J. Chavanne, L. Farvacque, G. Le Bec, D. Martin, S. M. Liuzzo, T. Perron, and S. White. Commissioning of the hybrid multibend achromat lattice at the european synchrotron radiation facility. *Phys. Rev. Accel. Beams*, 24:110701, Nov 2021.

[13] David K. Olsson, Åke Andersson, and Magnus Sjöström. Nonlinear optics from off-energy closed orbits. *Phys. Rev. Accel. Beams*, 23:102803, Oct 2020.

[14] Andrea Franchi, Simone Maria Liuzzo, and Zeus Marti. Analytic formulas for the rapid evaluation of the orbit response matrix and chromatic functions from lattice parameters in circular accelerators, 2017.

[15] A.Franchi and S.M. Liuzzo. Analytic derivative of orbit response matrix and dispersion with thick error sources and thick steerers implemented in python. In *Proc. of International Particle Accelerator Conference (IPAC'23), Venice, Italy, May 7-12, 2023*, number 7 in International Particle Accelerator Conference, Geneva, Switzerland, May 2023. JACoW.

[16] R. Bartolini, I.V. Agapov, A. Aloev, J. Chavanne, H.-J. Eckoldt, D. Einfeld, B. Krause, A. Petrov, M. Thede, and M. Tischer.

[17] Simone Liuzzo et al. Influence of errors on the ESRF Upgrade Lattice. In *6th International Particle Accelerator Conference*, page TUPWA014, 2015.