Commissioning simulations tools based on python Accelerator Toolbox

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.


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].

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 • 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.

• 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.

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].

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σ are set in all dipoles, quadrupoles and sextupoles of each lattice.

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.

Conclusions
A new software for storage ring commissioning simulations based on python AT has been developped.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.14th 1) • closed orbit correction • tune correction • chromaticity correction • error model fit based on closed orbit response matrix (LOCO like optics correction)

Figure 1 .
Figure 1.Trajectory correction to get first turns and beam accumulation for the FCC-ee collider at 45.6 GeV [10].

Figure 2 .
Figure 2. Optics dispersion and coupling correction based on measured orbit response matrix fit for the ESRF-EBS H7BA lattice [11, 12].

Figure 3 .
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.

Figure 4 .
Figure 4. DA (top) and MA (bottom) after correction for 50 different error seeds for the EBS lattice.

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.