11 Examples

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

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 its size.

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 this command:

Similarly, to find all examples that use CSBEND elements, one could use

• 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 quadrupole strengths.
  • 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 procedure.
• 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 compression chicane.
• 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 bunch compressor.
  • bunchCompMatrix — Four examples revolving around a four-dipole chicane bunch compressor. Simulations include basic compression, sensitivity to timing, phase, and beam energy.
  • 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 beamline.
• 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 distribution.
  • 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 elegant.
  • customLongitudinal — Example of making customized longitudinal distributions.
  • 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 command.
  • example1 — Gaussian energy distribution, linearly-ramped time distribution, and uniform transverse distributions.
  • parabolic — Gaussian longitudinal distribution combined with parabolic transverse distributions.
• 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 dynamic aperture.
• 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 twiss parameters.
• emitProc — Various applications of the program sddsemitproc, which processes quad-scan emittance measurements.
  • 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 structures
• 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 undulator.
• GENESIS2.0 — Example of running SDDS-compliant GENESIS 1.3 with output from elegant for LCLS.
• geneticOptimizer1 — Illustration of using the geneticOptimizer script together with elegant.
  • FODO5 — A simple example of misaligning elements on girders for a five-cell FODO lattice.
  • NSLS-II-GirderMisalignment — Simulation of girder misalignment for NSLS-II, by S. Kramer (BNL) and M. Borland (ANL).
• ibsHaissinskiIteration — Example of using ibsEmittance and haissinski to compute IBS effects in the presence of bunch-lengthening due to impedance.
• ILMatrixFromTracking — Determination of the values for ILMATRIX based on analysis of tracking data.
• 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.
  • wakes —
• 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 space.
• 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.
  • transientBeamLoading — Includes main and harmonic cavities, beamloading, rf feedback, beam feedback, and short-range impedance. 48 bunches are grouped into four short trains to show the effect of transient beamloading.
• multiStepErrors1 — Example of multi-step addition and correction of errors for a storage ring.
• 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 RFMODE element.
  • 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 momentum.
  • 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 errors.
  • dynamicApertureWithSynchMotion — Example of dynamic aperture with radiation damping and synchrotron motion.
  • ejectionOptimization — Tuning of a multi-turn extraction system using several kickers.
  • elasticScatteringTracking — Tracking to determine elastic scattering lifetime and loss distribution.
  • emittanceOptimization — Direct optimization of the emittance using linear optics tuning.
  • 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).
  • fmaWithDispersiveOrbit — Performs frequency map analysis including the momentum-dependence of the horizontal orbit.
  • 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.
  • RfmodeRestart — Example of restarting a simulation of a beam abort that includes an RFMODE element.
  • 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 amplitude.
  • 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 matrices.
• 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 simulation.
• storageRingRfNoise — Example of including rf phase and amplitude noise in a tracking simulation.
• straightDipoleModels — Examples of setting up models of transverse gradient or longitudinal gradient dipoles with fringe effects.
  • ccbend1 — Example of using a generalized gradient expansion to create a symplectic model of a transverse gradient dipole with soft fringe effects using CCBEND.
  • lgbend1 — Example of using a generalized gradient expansion to create a symplectic model of a 5-segment lonitudinal gradient dipole with soft fringe effects using CCBEND.
• transportLineHigherOrderDispersion — Determine higher-order dispersion in a transport line using tracking.
• transportLineSteering — Examples of steering transport lines.
  • coupledTransportLineSteering — A simple example of a strongly-coupled transport line.
  • twoPlaneSteering — A simple example of trajectory correction 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 first bunch.
• 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 CSRCSBEND.
  • transverse1 — Compare use of transverse wake and impedance methods for a damped oscillator.