Example runs and post-processing files are available in a separate tar file. The examples are intended to
demonstrate program capabilities with minimal work on the user’s part. However, they don’t pretend to
cover all the capabilities.
Each demo is (typically) invoked using a command (usually a C-shell script) that can both run
elegant and post-process the output. The post-processing is often handled by a lower-level script that is
called from the demo script. These lower-level scripts are good models for the creation of customized
scripts for user applications.
The examples are organized into a number of directories and subdirectories. In each area, the user
will find a “Notebook” file (a simple ASCII file) that describes the example and how to run
Many examples for storage ring simulations reside in the PAR subdirectory. The PAR (Particle
Accumulator Ring) is a small storage ring in the APS injector that is good for quick examples because of
Here’s a helpful tip in searching the examples on UNIX/LINUX systems: suppose one wants to find an
example of the frequency_map command. One can search all the elegant command files very quickly with
find . -name ’*.ele’ | xargs fgrep frequency_map
Similarly, to find all examples that use CSBEND elements, one could use
find . -name ’*.lte’ | xargs fgrep -i csbend
- acceptance — Use of the acceptance feature when tracking collections of particles.
- energyScan1 — Tracking a FODO line with various apertures, with variation of the
initial momentum offset.
- fodoScan1 — Tracking a FODO line with various apertures, with scanning of the
- transportLineAcceptance — Determine transverse and momentum acceptance of a
transport line using tracking. Example by M. Borland (ANL).
- alphaMagnet — Optimization of the strength of an alpha magnet to compress the beam from a
thermionic rf gun.
- APSRing — Examples for the APS storage ring
- beamMoments — 6D beam moments calculation with errors
- ibsAndTouschekLifetime — Compute touschek lifetime with IBS-inflated emittances
- ibsVsEnergy — Compute IBS as a function of energy.
- ionEffects1 — Basic simulation of ion effects.
- beamBasedAlignment — Determines quadrupole offsets based on simulated beam-based alignment
- beamBreakup — Example of simulating beam-driven deflecting rf mode in a simple linac.
- bendErrors — Analysis of the effect of errors on the matrix elements for a four-dipole bunch
- boosterRamp — Examples of simulating ramping in a booster.
- elementByElement — Example of simulating ramping in a booster, using the NSLS-II
booster lattice (R. Fliller).
- ILMATRIX — Example of ramping using ILMATRIX for faster tracking.
- bpmOffsets1 — Example of loading BPM offsets from an external file and then correcting the orbit
with those offsets.
- bunchCompression — Examples of using a four-dipole chicane for bunch compression.
- backtrack-bunchCompCSRLSCWake — Simluation of bunch compression with CSR, LSC,
and wakes. Both forward and backward tracking are performed.
- bunchComp — Four examples revolving around a four-dipole chicane bunch compressor.
Simulations include basic compression, sensitivity to timing, phase, and beam energy.
- bunchCompJitter — Simulation of a linac with a bunch compressor, including phase
and voltage errors in the linac.
- bunchCompJitter2 — Simulation of a linac with a bunch compressor, including phase
and voltage errors in the linac. In this case, the errors are generated externally.
- bunchCompLSC — Inclusion of longitudinal space charge in simulation of a linac with a
- bunchCompOptimize — Example of using tracking to optimize a linac and bunch
compressor including a 4th-harmonic linearizer.
- chromaticAmplitudes — Example of minimizing chromatic amplitude functions in a simple
- chromaticResponse — Example of computing the chromatic transfer functions R16(s) and R26(s)
as described in P. Emma and R. Brinkmann, SLAC-PUB-7554.
- constructOrbitBump1 — Illustration of how to make an orbit bump using BPM offsets and the
orbit correction algorithm.
- coupling — Examples of coupling calculation and correction.
- couplingCorrection1 — Scripts to perform coupling correction for the APS ring,
emulating what is done in APS operations. These scripts are now part of the elegant
- couplingCorrection2 — Example of using cross-plane response matrix and vertical
dispersion to correct the coupling.
- customBeamDistributions — Examples of making custom beam distributions for tracking with
- doubleBeam1 — Example of how to make a double-gaussian time distribution using
two runs. The resultant beam would be used in a subsequent run using the sdds_beam
- example1 — Gaussian energy distribution, linearly-ramped time distribution, and
uniform transverse distributions.
- parabolic — Gaussian longitudinal distribution combined with parabolic transverse
- cwiggler — Examples of using the CWIGGLER element.
- cwig+kickmap — Example of simulating a simple wiggler with CWIGGLER, making a
kickmap from trackings, then validating the kickmap.
- cwiggler1 — A simple example of dynamic aperture with a set of sinusoidal wigglers,
using the CWIGGLER element.
- cwiggler2 — An simple example of dynamic aperture with a set of two-component
horizontal wigglers, using the CWIGGLER element.
- DATuneScan — Performs a scan of the tunes in a storage ring and determines the variation in
- defeatLinkage — Example of how to defeat the automatic link between the gradient and other
multipoles in a dipole and the strength of the dipole itself.
- ellipseComparison — Example of comparing beam ellipse from tracking to ellipse implied by the
- emitProc — Various applications of the program sddsemitproc, which processes quad-scan
- emitProc1 — Simple example with constant measurement errors.
- emitProc2 — Measurement errors are supplied in the data file.
- emitProc3 — Includes the presence of dispersion, with constant measurement errors.
- emitProc4 — Quadrupole scan values are supplied from an external source.
- emitProc5 — Includes acceleration as part of the beamline.
- fiducialization — Examples for fiducializaton of a beamline.
- fiducial1 — Example of fiducialization with a fiducial bunch and a perturbed bunch.
The system in question is a linac with 50 structures, a four dipole chicane, then 50 more
- followIndividualParticles — Tracking a bunch of particles, then extracting and plotting the
trajectories of a few particles.
- full457MeV — Tracking of the APS linac with a PC gun beam, up to the entrance of the LEUTL
- GENESIS2.0 — Example of running SDDS-compliant GENESIS 1.3 with output from elegant for
- geneticOptimizer1 — Illustration of using the geneticOptimizer script together with
- ILMatrixFromTracking — Determination of the values for ILMATRIX based on analysis of tracking
- injRingMatch — Matching of a transport line to a storage ring.
- injRingMatch1 — Illustration of finding the periodic solution for a ring, then matching
a transport line to that solution.
- injRingMatch2 — Illustration of finding the periodic solution for a ring, then matching
a transport line to that solution. In this case, a single run is used.
- movingElements — Example of matching a transport line to a ring with movable
quadrupoles but fixed total length.
- LCLS — LCLS-I tracking example from P. Emma, November 2007.
- linacDispersion1 — Example of determining the initial dispersion error in a linac.
- LongitudinalSpaceCharge — Examples related to longitudinal space charge.
- LSCOscillationExample — Example of longitudinal space charge oscillations in a drift
- lsrMdltr — Various examples of using the LSRMDLTR (Laser Modulator) element
- example1 — Simple example using LCLS-I-like parameters
- example2 — Includes a time-profile on the laser.
- example3 — Simulation of laser slicing for a storage ring.
- matching — Various examples of lattice matching and optimization.
- beamSizeMatch1 — Example of adjusting the initial beam parameters to match the
measured beam sizes at a set of diagnositcs.
- betaMatching — A simple two-stage matching example.
- IDCompensation — Example of compensating for insertion device focusing effects.
- linacMatching1 — Example of three-part matching of a linac with a bunch compressor.
- linearize2 — Example of reducing nonlinearities in phase space using the REMCOR
element to remove linear correlations first.
- matchMeasuredBetas — Optimization of lattice quadrupoles to create a model that
reproduces measured beta functions.
- matchTwoEnergies — Example of matching beams with two different initial energies in
a linac. The beams are affected by common quadrupoles, but also by quadrupoles unique
to each beam.
- multiPartMatching1 — Complex example of multi-part matching for a linac with
several splice points.
- multiPartMatching2 — Example of storage ring matching with three types of cells.
- spectrometer1 — Optimizes a simple spectrometer to maximize energy resolution.
- MBALatticeDAWithErrors — Example of performing DA vs momentum offset tracking when the
lattice has strong sextupoles that make the orbit difficult to correct.
- multibunchCollectiveEffects — Examples of multi-bunch collective effects for APS storage ring
and other cases.
- APS-24Bunch-CBI — Includes main and harmonic cavities, beamloading, rf feedback,
beam feedback, and short-range impedance.
- ILMatrixFromTracking — Example of using tracking to set up the ILMATRIX element
for fast tracking. This is useful for increasing the speed of collective effects simulations.
- linacBunchTrain1 — Includes main linac cavities, dipole HOMs, and monopole HOMs
for a simple linac, showing beam breakup.
- linacWithHOMs — Includes main linac cavities, dipole HOMs, monopole HOMs, and
wakes for part of LCLS. The number of bunches is varied using templates.
- multiStepErrors1 — Example of multi-step addition and correction of errors for a storage
- NSLS-II-GirderMisalignment — Simulation of girder misalignment for NSLS-II, by S. Kramer
(BNL) and M. Borland (ANL).
- outboardTrajCorr — Examples of using the response matrix computed by elegant to perform
trajectory correction with a script.
- outboardTrajCorr1 — Compares trajectory correction inside elegant to correction
performed with an external script.
- outboardTrajCorr2 — Compares trajectory correction inside elegant to correction
performed with an external script. Includes BPM offsets.
- PAR — Numerous examples using the small APS Particle Accumulator Ring.
- accumulate — Simulates adding particles to an already-stored beam.
- alphaExpansion — Example of computing momentum compaction (alpha) to higher
order using tracking.
- broadBandImpedance — Example of using ZLONGIT, ILMATRIX, and SREFFECTS
to simulate a broad-band impedance in a storage ring.
- bunchLengthening — Simulation of a passive bunch-lengthening cavity using the
- chromCorrection — Simple chromaticity correction with two families. Also illustrates
saving and loading correction results.
- chromTracking — Illustration of using tracking to determine variation of tune with
- chromTracking2 — Similar to chromTracking, but includes determination of the
momentum dependence of the beta functions.
- CSR — Example of tracking with APS Particle Accumulator Ring with a Coherent
Synchrotron Radiation impedance.
- DANormSigma — Determination of dynamic aperture in terms of beam size.
- daOpt — Example of optimization of dynamic acceptance.
- dynamicAperture — Determination of dynamic aperture for a series of momentum
- dynamicApertureWithSynchMotion — Example of dynamic aperture with radiation
damping and synchrotron motion.
- ejectionOptimization — Tuning of a multi-turn extraction system using several
- elasticScatteringTracking — Tracking to determine elastic scattering lifetime and
- emittanceOptimization — Direct optimization of the emittance using linear optics
- fineDynamicAperture — High-resolution dynamic aperture including a map of where
particles are lost.
- fixedLVsRegularOrbit — Illustration of the difference between orbits computed with
fixed path length (fixed rf frequency) and fixed beam energy (variable rf frequency).
- frequencyMap — Example of frequency map analysis
- frequencyMap-x-delta — Example of frequency map analysis for (x, delta)
- gasScatteringLifetime — Simple computation of gas scattering lifetime using a fixed
pressure and gas mixture.
- gasScatteringLifetimePresFile — Computation of gas scattering lifetime using a file
giving the pressure around the ring.
- ILMatrixScan — Set up ILMATRIX element, then scan the tune.
- inelasticScatteringTracking — Tracking to determine inelastic scattering lifetime
and loss distribution.
- moments — Computes 6D beam moments with coupling errors.
- momentumAperture — Computes the s-dependent momentum aperture without errors.
- offMomentumDA — Another computation of off-momentum dynamic aperture
- offMomentumTwiss — Computation of off-momentum twiss parameters.
- offMomentumTwiss2 — Computation of off-momentum twiss parameters vs s.
- quadScan — Computation of twiss parameters as quadrupoles are varied according to
an external table.
- randomMultipoles — Dynamic aperture including random multipole errors in the
quadrupoles and sextupoles.
- synchrotronTune — Simple example of tracking with synchrotron motion.
- tracking — Visualization of motion in x-x’ and y-y’ phase space.
- trajOrbitCorrect — Correct the first-turn trajectory, then correct the orbit.
- tswa — Example of obtaining amplitude-dependence of tunes from tracking.
- TSWATracking — Uses tracking and post-processing to determine tune variation with
- tuneExcitation — Use a swept kick to excite the horizontal tune, observing excitation
of the synchrotron tune as well.
- tuneOptimization — Correct the tunes and chromaticities.
- twissCalculation — Simple calculation of the twiss parameters
- twoCavityMoments — Calculation of 6D beam moments in the presence of main and
harmonic rf cavities.
- parallel — Various runs illustrating a few features of the parallel version.
- DA — Dynamic aperture calculation.
- FMA — Frequency map analysis.
- LMA — Local momentum aperture calculation.
- swarmOptimizer — Simple example of using the particle-swarm optimizer.
- pepperPot — Examples of using the PEPPER_POT element
- basic — Basic example of simulating a pepper-pot plate.
- pepperPotScan — Example of simulating a pepper-pot plate with emittance analysis.
- periodicTwissRFCA — Demonstration that one can’t have periodic beta functions in a FODO cell
array with linac structures.
- pulsedSextInjection — Illustration of optimizing the sextupoles of pulsed sextupole kickers for
injection into a storage ring.
- rampTunesWithBeam — Example of ramping tunes while tracking beam. In this case, we ramp the
tunes across the difference coupling resonance.
- rfDeflectingCavity — A simple example of using a traveling wave rf deflector (RFDF).
- RFTMEZ0 — Tracking through a TM-mode rf cavity based on an off-axis expansion starting from
Ez(z) at r=0.
- scanParameters — Examples of scanning parameters of beamline elements.
- scanParameters1 — Scan two quadrupoles together.
- scanParameters2 — Scan the phase of an rf cavity and look at synchrotron oscillations.
- scriptElement — Examples of using the SCRIPT element
- elegantShower — Use of the SCRIPT element to execute the electron-gamma shower
simulation code SHOWER as part of an elegant run.
- mergeBeams — Using the SCRIPT element to merge several beams into a simulation
that already has a beam.
- slitArray — Simulation of an array of slits using the SCRIPT element.
- sddsoptimizeExample — Example of using the program sddsoptimize to optimize the
results of elegant simulations. In this example, we vary a strength fudge factor for a set of
quadrupoles in a transport line in order to attempt to match measured H and V response
- serverExample — Example of using elegant in server mode to update lattice functions when
magnet strengths change.
- SPEAR3 — Various examples using an early SPEAR3 lattice
- dynamicAperture — Compute DA for several error seeds, including multipole errors.
- latticeErrors — Compute variation in lattice functions with errors, including
correction of the orbit, tunes, and chromaticities.
- staticPlusDynamicErrors — Example of combining static and dynamic errors in one
- storageRingRfNoise — Example of including rf phase and amplitude noise in a tracking
- transportLineHigherOrderDispersion — Determine higher-order dispersion in a transport line
- twissDerivatives — Example of how to compute slopes of beta, alpha, and dispersion as a
function of initial momentum for a transport line.
- twoBunchPhasing — Example of putting two bunches through a linac with the linac phased to the
- varyPlotExample — Example of varying a beamline parameter and computing beam properties,
then plotting those properties vs s.
- wakesAndImpedances — Examples of wakes and impedances.
- csrImpedance — Comparison of using CSR impedance (from csrImpedance) and
- transverse1 — Compare use of transverse wake and impedance methods for a damped