User’s Manual for elegant
September 13, 2023
Note: another source of help for elegant is the on-line forum. Users are encouraged to join and
participate. At minimum, users should subscribe to the “Bugs” topic, since this is where bug notifications
A set of examples and scripts is available from the software download page that demonstrates many
features of elegant. A brief overview of elegant is also available, which introduces the capabilities at a
1 Highlights of What’s New in Version 2023.3
1.1 Bug Fixes for Elements
1.2 Bug Fixes for Commands
1.3 New and Modified Elements
1.4 New and Modified Commands
1.5 Other Changes
1.6 Changes Specific to the MPI Parallel Version
1.7 Changes Specific to the GPU Version
1.8 Changes to Related Programs and Files
1.9 Known Bugs, Problems, and Limitations
3.1 Program Philosophy
3.2 Capabilities of elegant
4 Digression on the Longitudinal Coordinate Definition
5 Fiducialization in elegant
6 Preparing beams for bunch-mode simulations
7 Namelist Command Dictionary
7.1 Commandline Syntax
7.2 General Command Syntax
7.3 Setup and Action Commands
7.4 Table of elegant commands and their functions
8 Specialized Tools for Use with elegant
9 Accelerator and Element Description
9.1 Magnet Strength
10 Element Dictionary
10.1 ALPH—An alpha magnet implemented as a matrix, up to 3rd order.
10.2 APCONTOUR—An aperture (or its inverse) defined by (x,
y) points in an SDDS file.
10.3 BEAMBEAM—An element to provide kicks from another beam
10.4 BGGEXP—A magnetic field element using generalized gradient expansion.
10.5 BMAPXY—A map of Bx and By vs x and y.
10.6 BMXYZ—A map of (Bx, By, Bz) vs (x, y, z), for straight elements only
10.7 BOFFAXE—A straight magnetic field element using off-axis
expansion from an on-axis derivative.
10.8 BRANCH—Conditional branch instruction to jump to another
part of the beamline
10.9 BRAT—Bending magnet RAy Tracing using (Bx, By, Bz) vs (x, y, z).
10.10 BUMPER—A time-dependent kicker magnet with optional
spatial dependence of the kick and no fringe effects. The waveform is
in SDDS format, with time in seconds and amplitude normalized to 1.
The optional spatial dependence is also specified as an SDDS file.
10.11 CCBEND—A canonically-integrated straight dipole magnet,
assumed to have multipoles defined in Cartesian coordinates.
10.12 CENTER—An element that centers the beam transversely
on the ideal trajectory.
10.13 CEPL—A numerically-integrated linearly-ramped electric field deflector.
10.14 CHARGE—An element to establish the total charge of a beam. Active
on first pass only. If given, overrides all charge specifications on other elements.
10.15 CKICKER—Optical stochastic cooling kicker element—applies
a kick in particle momentum
10.16 CLEAN—Cleans the beam by removing outlier particles.
10.17 CORGPIPE—A corrugated round pipe, commonly used as
a dechirper in linacs.
10.18 CORGPLATES—A pair of corrugated plates, commonly
used as a dechirper in linacs.
10.19 CPICKUP—Optical stochastic cooling pickup element—records
10.20 CSBEND—A canonical kick sector dipole magnet.
10.21 CSRCSBEND—Like CSBEND, but incorporates a simulation
of Coherent Synchrotron radiation.
10.22 CSRDRIFT—A follow-on element for CSRCSBEND that
applies the CSR wake over a drift.
10.23 CWIGGLER—Tracks through a wiggler using canonical
integration routines of Y. Wu (Duke University).
10.24 DRIF—A drift space implemented as a matrix, up to 2nd
order. Use EDRIFT for symplectic tracking.
10.25 DSCATTER—A scattering element to add random changes
to particle coordinates according to a user-supplied distribution function
10.26 ECOL—An elliptical collimator.
10.27 EDRIFT—Tracks through a drift with no approximations
10.28 EHKICK—A horizontal steering dipole implemented using
an exact hard-edge model
10.29 EKICKER—A combined horizontal/vertical steering dipole
implemented using an exact hard-edge model
10.30 EMATRIX—Explicit matrix input with data in the element
definition, rather than in a file.
10.31 EMITTANCE—Applies a linear transformation to the beam
to force the emittance to given values.
10.32 ENERGY—An element that matches the central momentum to the
beam momentum, or changes the central momentum or energy to a specified value.
10.33 EVKICK—A vertical steering dipole implemented using an
exact hard-edge model
10.34 FLOOR—Sets floor coordinates
10.35 FMULT—Multipole kick element with coefficient input from
an SDDS file.
10.36 FRFMODE—One or more beam-driven TM monopole modes
of an RF cavity, with data from a file.
10.37 FTABLE—Tracks through a magnetic field which is expressed
by a SDDS table.
10.38 FTRFMODE—One or more beam-driven TM dipole modes
of an RF cavity, with data from a file.
10.39 GFWIGGLER—Tracks through a wiggler using generate function
method of J. Bahrdt and G. Wuestefeld (BESSY, Berlin, Germany).
10.40 GKICKMAP—An ordinary kick map (use UKICKMAP for undualtors).
10.41 HISTOGRAM—Request for histograms of particle coordinates
to be output to SDDS file.
10.42 HKICK—A horizontal steering dipole implemented as a matrix,
up to 2nd order. Use EHKICK for symplectic tracking.
10.43 HKPOLY—Applies kick according to a Hamiltonian that’s
a polynomial function of x and y together with a generalized drift also
given as a polynomial of qx and qy
10.44 HMON—A horizontal position monitor, accepting a rpn
equation for the readout as a function of the actual position (x).
10.45 IBSCATTER—A simulation of intra-beam scattering.
10.46 ILMATRIX—An Individualized Linear Matrix for each particle
for fast symplectic tracking with chromatic and amplitude-dependent effects
10.47 IONEFFECTS—Simulates ionization of residual gas and
interaction with the beam.
10.48 KICKER—A combined horizontal-vertical steering magnet implemented
as a matrix, up to 2nd order. For time-dependent kickers, see BUMPER.
10.49 KOCT—A canonical kick octupole.
10.50 KPOLY—A thin kick element with polynomial dependence
on the coordinates in one plane.
10.51 KQUAD—A canonical kick quadrupole.
10.52 KQUSE—A canonical kick element combining quadrupole
and sextupole fields.
10.53 KSEXT—A canonical kick sextupole, which differs from the MULT
element with ORDER=2 in that it can be used for chromaticity correction.
10.54 LGBEND—A multi-segment straight longitudinal dipole magnet
10.55 LMIRROR—A mirror for light optics
10.56 LRWAKE—Long-range (inter-bunch and inter-turn) longitudinal
and transverse wake
10.57 LSCDRIFT—Longitudinal space charge impedance
10.58 LSRMDLTR—A non-symplectic numerically integrated planar
undulator including optional co-propagating laser beam for laser modulation
of the electron beam.
10.59 LTHINLENS—A thin lens for light optics
10.60 MAGNIFY—An element that allows multiplication of phase-space
coordinates of all particles by constants.
10.61 MALIGN—A misalignment of the beam, implemented as a
10.62 MAPSOLENOID—A numerically-integrated solenoid specified
as a map of (Bz, Br) vs (z, r).
10.63 MARK—A marker, equivalent to a zero-length drift space.
10.64 MATR—Explicit matrix input from a text file, in the format
written by the print_matrix command.
10.65 MATTER—A Coulomb-scattering and energy-absorbing
element simulating material in the beam path.
10.66 MAXAMP—A collimating element that sets the maximum transmitted
particle amplitudes for all following elements, until the next MAXAMP.
10.67 MBUMPER—A time-dependent multipole kicker magnet. The
waveform is in SDDS format, with time in seconds and amplitude normalized to 1.
10.68 MHISTOGRAM—Request for multiple dimensions (1, 2, 4
or 6) histogram output of particle coordinates.
10.69 MODRF—A first-order matrix RF cavity with exact phase
dependence, plus optional amplitude and phase modulation.
10.70 MONI—A two-plane position monitor, accepting two rpn
equations for the readouts as a function of the actual positions (x and y).
10.71 MRFDF—Zero-length Multipole RF DeFlector from dipole to decapole
10.72 MULT—A canonical kick multipole.
10.73 NIBEND—A numerically-integrated dipole magnet with
various extended-fringe-field models.
10.74 NISEPT—A numerically-integrated dipole magnet with a
10.75 OCTU—An octupole implemented as a third-order matrix.
Use KOCT for symplectic tracking.
10.76 PEPPOT—A pepper-pot plate.
10.77 PFILTER—An element for energy and momentum filtration.
10.78 POLYSERIES—Tracks through a Polynomial series map
specified by a file containing coefficients.
10.79 QUAD—A quadrupole implemented as a matrix, up to 3rd
order. Use KQUAD for symplectic tracking.
10.80 QUFRINGE—An element consisting of a linearly increasing
or decreasing quadrupole field.
10.81 RAMPP—A momentum-ramping element that changes the
central momentum according to an SDDS-format file of the momentum
factor vs time in seconds.
10.82 RAMPRF—A voltage-, phase-, and/or frequency-ramped
RF cavity, implemented like RFCA.
10.83 RBEN—A rectangular dipole, implemented as a SBEND with
edge angles, up to 2nd order. Use CSBEND for symplectic tracking.
10.84 RCOL—A rectangular collimator.
10.85 RECIRC—An element that defines the point to which particles
recirculate in multi-pass tracking
10.86 REFLECT—Reflects the beam back on itself, which is useful
for multiple beamline matching.
10.87 REMCOR—An element to remove correlations from the
tracked beam to simulate certain types of correction.
10.88 RFCA—An rf cavity with exact phase dependence, first order
in transverse coordinates.
10.89 RFCW—A combination of RFCA, WAKE, TRWAKE, and LSCDRIFT.
10.90 RFDF—A simple traveling or standing wave deflecting RF cavity.
10.91 RFMODE—A simulation of a beam-driven TM monopole
mode of an RF cavity.
10.92 RFTM110—Tracks through a TM110-mode (deflecting) rf cavity with
all magnetic and electric field components. NOT RECOMMENDED—See below.
10.93 RFTMEZ0—A TM-mode RF cavity specified by the on-axis Ez field.
10.94 RIMULT—Multiplies radiation integrals by a given factor.
Use to compute emittance for collection of various types of cells.
10.95 RMDF—A linearly-ramped electric field deflector, using an
approximate analytical solution FOR LOW ENERGY PARTICLES.
10.96 ROTATE—An element that rotates the beam about the longitudinal axis.
10.97 SAMPLE—An element that reduces the number of particles
in the beam by interval-based or random sampling.
10.98 SBEN—A sector dipole implemented as a matrix, up to 2nd
order. Use CSBEND for symplectic tracking.
10.99 SCATTER—A scattering element to add random values to
10.100 SCRAPER—A collimating element that sticks into the beam from
one side only. The directions 0, 1, 2, and 3 are from +x, +y, -x, and -y, respectively.
10.101 SCRIPT—An element that allows transforming the beam
using an external script.
10.102 SEXT—A sextupole implemented as a matrix, up to 3rd
order. Use KSEXT for symplectic tracking.
10.103 SHRFDF—Simulation through space harmonics of zero
length deflecting cavity.
10.104 SLICE—Performs slice-by-slice analysis of the beam for output to a file.
10.105 SOLE—A solenoid implemented as a matrix, up to 2nd order.
10.106 SPEEDBUMP—Simulates a semi-circular protuberance
from one or both walls of the chamber.
10.107 SREFFECTS—Lumped simulation of synchrotron radiation
effects (damping and quantum excitation) for rings.
10.108 STRAY—A stray field element with local and global components.
Global components are defined relative to the initial beamline direction.
10.109 TAPERAPC—A tapered aperture that is a section of a circular cylinder.
10.110 TAPERAPE—A tapered elliptical aperture.
10.111 TAPERAPR—A tapered rectangular aperture.
10.112 TFBDRIVER—Driver for a turn-by-turn feedback loop
10.113 TFBPICKUP—Pickup for a turn-by-turn feedback loop
10.114 TMCF—A numerically-integrated accelerating TM RF cavity
with spatially-constant fields.
10.115 TRCOUNT—An element that defines the point from which
transmission calculations are made.
10.116 TRFMODE—A simulation of a beam-driven TM dipole
mode of an RF cavity.
10.117 TRWAKE—Transverse wake specified as a function of time
lag behind the particle.
10.118 TSCATTER—An element to simulate Touschek scattering.
10.119 TUBEND—A special rectangular bend element for top-up backtracking.
10.120 TWISS—Sets Twiss parameter values.
10.121 TWLA—A numerically-integrated first-space-harmonic
traveling-wave linear accelerator.
10.122 TWMTA—A numerically-integrated traveling-wave muffin-tin
10.123 TWPL—A numerically-integrated traveling-wave stripline deflector.
10.124 UKICKMAP—An undulator kick map (e.g., using data from RADIA).
10.125 VKICK—A vertical steering dipole implemented as a matrix,
up to 2nd order. Use EVKICK for symplectic tracking.
10.126 VMON—A vertical position monitor, accepting a rpn equation
for the readout as a function of the actual position (y).
10.127 WAKE—Longitudinal wake specified as a function of time
lag behind the particle.
10.128 WATCH—A beam property/motion monitor–allowed modes
are centroid, parameter, coordinate, and fft.
10.129 WIGGLER—A wiggler or undulator for damping or excitation
of the beam.
10.130 ZLONGIT—A simulation of a single-pass broad-band or
functionally specified longitudinal impedance.
10.131 ZTRANSVERSE—A simulation of a single-pass broad-band
or functionally-specified transverse impedance.
12 The rpn Calculator
13 Change Log
13.1 Highlights of What’s New in Version 2023.2
13.2 Highlights of What’s New in Version 2023.1
13.3 Highlights of What’s New in Version 2022.2
13.4 Highlights of What’s New in Version 2022.0
13.5 Highlights of What’s New in Version 2021.4
13.6 Highlights of What’s New in Version 2021.3
13.7 Highlights of What’s New in Version 2021.2
13.8 Highlights of What’s New in Version 2021.1
13.9 Highlights of What’s New in Version 2020.5
13.10 Highlights of What’s New in Version 2020.4
13.11 Highlights of What’s New in Version 2020.3
13.12 Highlights of What’s New in Version 2020.2
13.13 Highlights of What’s New in Version 2020.1.1
13.14 Highlights of What’s New in Version 2019.4.0
13.15 Highlights of What’s New in Version 2019.3.0
13.16 Highlights of What’s New in Version 2019.2.1
13.17 Highlights of What’s New in Version 2019.1.1
13.18 Highlights of What’s New in Version 35.1.0
13.19 Highlights of What’s New in Version 35.0.1
13.20 Highlights of What’s New in Version 34.4.0
13.21 Highlights of What’s New in Version 34.3.0, June 14, 2018
13.22 Highlights of What’s New in Version 34.2.0, March 22, 2018
13.23 Highlights of What’s New in Version 34.1.0, 27 February 2018
13.24 Highlights of What’s New in Version 34.0, 31 October 2017
13.25 Highlights of What’s New in Version 33.1.1, 25 July 2017
13.26 Highlights of What’s New in Version 33.0, March 3, 2017
13.27 Highlights of What’s New in Version 32.0, 5 Jan. 2017
13.28 Highlights of What’s New in Version 31.0, 1 Oct. 2016
13.29 Highlights of What’s New in Version 30.1, 3 Aug. 2016
13.30 Highlights of What’s New in Version 30.0, 5 July 2016
13.31 Highlights of What’s New in Version 29.1, 3 March 2016
13.32 Highlights of What’s New in Version 29.0, 15 Jan. 2016
13.33 Highlights of What’s New in Version 28.1.0, 23 July 2015
13.34 Highlights of What’s New in Version 28.0.0, 18 June 2015