Overview of elegant and SDDS
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 uptodate 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:
 Simulation capabilties, for example, the ability to simulate random errors.
 Physics capabilities, for example, the ability to simulate coherent synchrotron radiation effects.
 Cooperative capabilities, for example, the ability to read data produced by other programs.
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.
 Tracking of rings, linacs, and transport lines
 Computation of sdependent and final properties, including
 Beam moments, from tracking or analysis
 Twiss parameters
 Matrix elements
 Trajectory/orbit
 Trajectory/orbit response matrix
 Floor coordinates
 Aperture determination
 Input of sdependent aperture
 Computation of dynamic acceptance
 Computation of sdependent momentum acceptance
 Optimization of results of computations and tracking
 Tracking and computations with errors
 Generate or load random error sets
 Perform correction of tunes, chromaticities, trajectory/orbit
 Control lattice parameters
 Scan parameters in multidimensional loops
 Alter parameters from values in lattice definition
 Load SDDS data to overwrite values in lattice definition
 Insert elements into lattice
 Subdivide elements
 Bunch generation, or reading of bunch data from files
 Multistage simulation
 Load particles from previous tracking run
 Load lattice parameters from previous optimization run
 Load errors and correction settings from previous error run
 Timedependent ramping or modulation
 Determination of frequency maps for rings
 Change of particle type (default is electrons)
The physics capabilities of elegant are listed here. Generally
speaking, these capabilities map into elements that can appear in the
lattice file.
 Singleparticle 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 standingwave rf cavities
 Traveling wave linear accelerating cavities
 Scattering by materials or using userdefined distributions
 Timedependent dipole and multipole kickers
 Userdesigned transformation using external program
 Userspecified matrix
 Apertures and scrapers
 Collective dynamics
 Shortrange wake fields and impedances.
 Longrange wakes due to resonant modes.
 Coherent synchrotron radiation.
 Longitudinal spacecharge impedance [4].
 Transverse spacecharge kicks for rings [5].
 Intrabeam scattering [6].
 Touschek scattering [7].
 Other
 Beam position monitors
 Phase space output and analysis monitors
 Digital feedback systems
One of the strengths of elegant is its ability to work cooperatively with other programs.
This is done through the use of SDDS (SelfDescribing Data Sets[1,2]) files.
Such capabilities include
 Use of the generalpurpose SDDS toolkit for postprocessing and graphics. Capabilities include
sophisticated plotting, definition of new quantities using formulae, filtering, crossreferencing, sorting,
one and twodimensional histograms, frequency analysis, fitting, etc.
You can find out more about SDDS from the SDDS Info Page.
 Reading particle distribution data from other programs, including ASTRA [10], IMPACT [11], and TRACK [12].
 Phase space analysis to obtain twiss parameters and moments.
 Computation of radiation brightness and flux tuning curves, as well as radiation distributions and other properties.
 Upsampling of particle distributions to increase particle number, smooth the distribution, and add modulations.
 Processing of quadrupolescan emittance measurement data.
 Computation of the CSR impedance for use in tracking [8].
 Use of elegant data for Touschek lifetime, intrabeam scattering, and potential well distortion computations.
 Translation of elegant lattice into other formats.
 Computation of multipole error data to reflect defined magnet construction errors [3].

 1

M. Borland, ``A SelfDescribing File Protocol for Simulation
Integration and Shared Postprocessors,'' Proc. 1995 PAC, May 15,
1995, Dallas, Texas, pp. 21842186 (1996).
 2

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

K. Halbach, ``First Order Perturbation Effects in IronDominated TwoDimensional Symmetrial Multipoles'',
NIM 741, 1969, 147164.
 4

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

A. Xiao et al., ``Direct SpaceCharge Calculation in elegant and its Application to the
ILC Damping Ring,'' Proc. PAC2007, 34563458.
 6

A. Xiao, ``Study of IBS Effects for HighBrightness Linac Beams,'' Proc. Linac08, 296298 (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,'' SLACPUB5375, 1990.
 9

P. Elleaume, ``A New Approach to Electron Beam Dynamics in Undulators and Wigglers,'' Proc. EPAC 1992, 661663.
 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, 20532055 (2005); ASCII version 39 from B. Mustapha.
Michael Borland
20101220