Overview of elegant and SDDS

Michael Borland

Purpose of this document

The purpose of this document is to briefly summarize the capabilities available of elegant and the SDDS toolkit for simulation of rings, linacs, and beam transport systems.. The description covers both the serial and parallel versions. The intended audience is potential new users, who may want to know in general terms what elegant can do without having to read the manual. Hence, we will not show detailed examples. For that, refer to the example files available from our web site.

elegant is open source, with both source code and executables available.

More detail as well as the most up-to-date information will be found in the manual, as well as the forum. Users are encouraged to join and participate in the forum. At minimum, users should subscribe to the ``Bugs'' topic, since this is where bug notifications are posted.

The capabilities of elegant for accelerator simulation will be broken down as follows:

1. Simulation capabilties, for example, the ability to simulate random errors.
2. Physics capabilities, for example, the ability to simulate coherent synchrotron radiation effects.
3. Cooperative capabilities, for example, the ability to read data produced by other programs.

Simulation Capabilities

The simulation capabilities of elegant at the highest level, irrespective of any particular physics, are listed here. Generally speaking, these capabilities map into the commands that appear in the main input file.

1. Tracking of rings, linacs, and transport lines
2. Computation of s-dependent and final properties, including
   • Beam moments, from tracking or analysis
   • Twiss parameters
   • Matrix elements
   • Trajectory/orbit
   • Trajectory/orbit response matrix
   • Floor coordinates
3. Aperture determination
   • Input of s-dependent aperture
   • Computation of dynamic acceptance
   • Computation of s-dependent momentum acceptance
4. Optimization of results of computations and tracking
5. Tracking and computations with errors
   • Generate or load random error sets
   • Perform correction of tunes, chromaticities, trajectory/orbit
6. Control lattice parameters
   • Scan parameters in multi-dimensional loops
   • Alter parameters from values in lattice definition
   • Load SDDS data to overwrite values in lattice definition
   • Insert elements into lattice
   • Sub-divide elements
7. Bunch generation, or reading of bunch data from files
8. Multi-stage simulation
   • Load particles from previous tracking run
   • Load lattice parameters from previous optimization run
   • Load errors and correction settings from previous error run
9. Time-dependent ramping or modulation
10. Determination of frequency maps for rings
11. Change of particle type (default is electrons)

Physics Capabilities

The physics capabilities of elegant are listed here. Generally speaking, these capabilities map into elements that can appear in the lattice file.

1. Single-particle dynamics
   • Magnetic elements using matrix or symplectic tracking methods, e.g., drifts, dipoles, quadrupoles, sextupoles, higher multipoles, wigglers, alpha magnets, solenoids, etc.
   • Stray fields and steering correctors
   • Undulator kick maps[9].
   • Classical and quantum synchrotron radiation effects in magnets
   • Accelerating and deflecting standing-wave rf cavities
   • Traveling wave linear accelerating cavities
   • Scattering by materials or using user-defined distributions
   • Time-dependent dipole and multipole kickers
   • User-designed transformation using external program
   • User-specified matrix
   • Apertures and scrapers
2. Collective dynamics
   • Short-range wake fields and impedances.
   • Long-range wakes due to resonant modes.
   • Coherent synchrotron radiation.
   • Longitudinal space-charge impedance [4].
   • Transverse space-charge kicks for rings [5].
   • Intrabeam scattering [6].
   • Touschek scattering [7].
3. Other
   • Beam position monitors
   • Phase space output and analysis monitors
   • Digital feedback systems

Cooperative Capabilities

One of the strengths of elegant is its ability to work cooperatively with other programs. This is done through the use of SDDS (Self-Describing Data Sets[1,2]) files. Such capabilities include

1. Use of the general-purpose SDDS toolkit for postprocessing and graphics. Capabilities include sophisticated plotting, definition of new quantities using formulae, filtering, cross-referencing, sorting, one- and two-dimensional histograms, frequency analysis, fitting, etc. You can find out more about SDDS from the SDDS Info Page.
2. Reading particle distribution data from other programs, including ASTRA [10], IMPACT [11], and TRACK [12].
3. Phase space analysis to obtain twiss parameters and moments.
4. Computation of radiation brightness and flux tuning curves, as well as radiation distributions and other properties.
5. Upsampling of particle distributions to increase particle number, smooth the distribution, and add modulations.
6. Processing of quadrupole-scan emittance measurement data.
7. Computation of the CSR impedance for use in tracking [8].
8. Use of elegant data for Touschek lifetime, intrabeam scattering, and potential well distortion computations.
9. Translation of elegant lattice into other formats.
10. Computation of multipole error data to reflect defined magnet construction errors [3].

Bibliography

1

M. Borland, ``A Self-Describing File Protocol for Simulation Integration and Shared Postprocessors,'' Proc. 1995 PAC, May 1-5, 1995, Dallas, Texas, pp. 2184-2186 (1996).

2

M. Borland, ``A Universal Postprocessing Toolkit for Accelerator Simulation and Data Analysis,'' Proc. 1998 ICAP Conference, Sept. 14-18, 1998, Monterey, California, to be published.

3

K. Halbach, ``First Order Perturbation Effects in Iron-Dominated Two-Dimensional Symmetrial Multipoles'', NIM 74-1, 1969, 147-164.

4

Z. Huang et al., Phys. Rev. ST Accel. Beams 7 074401 (2004).

5

A. Xiao et al., ``Direct Space-Charge Calculation in elegant and its Application to the ILC Damping Ring,'' Proc. PAC2007, 3456-3458.

6

A. Xiao, ``Study of IBS Effects for High-Brightness Linac Beams,'' Proc. Linac08, 296-298 (2009).

7

A. Xiao et al., ``Monte Carlo simulation of Touschek effect,'' Phys. Rev. ST Accel. Beams 13, 074201 (2010).

8

W. Warnock, ``Shielded Coherent Synchrotron Radiation and Its Effect on Very Short Bunches,'' SLAC-PUB-5375, 1990.

9

P. Elleaume, ``A New Approach to Electron Beam Dynamics in Undulators and Wigglers,'' Proc. EPAC 1992, 661-663.

10

K. Flöttmann, Astra User Manual, http://www.desy.de/ mpyflo/Astra_dokumentation/

11

J. Qiang et al., J. Comp. Phys. 163, 434 (2000).

12

V. N. Aseev et al., Proc. PAC05, 2053-2055 (2005); ASCII version 39 from B. Mustapha.