11 Specialized Tools for Use with elegant

A number of specialized programs are available that work with elegant. Most are SDDS-compliant, so they will also work with any program that reads or writes appropriate SDDS data. The following is a brief description of each program. Full descriptions for many programs are available on subsequent pages. Most programs will return a help message if the program name is given with no arguments, which should be sufficient documentation and may be more up-to-date than these manual pages.

• abrat — A program to integrate particles through a 3D magnetic field map. The name stands for Asymmetric Bend RAy trace. This program uses the same method as the BRAT element in elegant.
• analyzeMagnets — Generates SDDS and latex files giving magnet parameters. (Program by M. Borland.)
• astra2elegant — Converts ASCII particle output from ASTRA [30] to a binary SDDS file suitable for use with elegant. This program is recommended over the astra2sdds program on the ASTRA website, because the latter produces ASCII SDDS files that are quite slow to read and does not perform the correct computations for low-energy beams. (Program by M. Borland.)
• bremsstrahlungLifetime — Computes gas bremsstrahlung lifetime from local momentum acceptance and Twiss parameter output, assuming a constant gas pressure. (Program by M. Borland.)
• bremsstrahlungLifetimeDetailed — Computes gas bremsstrahlung lifetime from local momentum acceptance and Twiss parameter output, using a user-supplied, s-dependent gas pressure. (Program by M. Borland.)
• centroid2floor — Combines reference floor-coordinate and centroid data to make a file with the beam path in global (floor) coordinates.
• computeCoherentFraction — Computes the coherent fraction for undulator radiation.
• computeCBGGE — Computes generalized gradients from data on a circular cylinder for use with the BGGEXP element.
• computeGeneralizedGradients — Deprecated. Use computeCBGGE.
• computeRBGGE — Computes generalized gradients from data on a rectangular boundary for use with the BGGEXP element.
• computeSCTuneSpread — Compute space charge tune spread.
• coreEmittance — Computes the slice emittance for the beam core (e.g., 80% of the beam). (Program by X. Dong.)
• csrImpedance — Computes the shielded steady-state CSR impedance for a dipole magnet. The output can be used immediately with elegant’s ZLONGIT element. (Program by Y. Wang, H. Shang, and M. Borland.) See also the makeSummedCsrZ script.
• doubleDist6 — Increases the number of particles in a particle input file by successively doubling the number. Intended to be used to increase the number of particles produced by a photoinjector simulation to improve stability of CSR and LSC simulations. See also smoothDist6. (Program by M. Borland.)
• curvedDipoleFringeCalc — Computes fringe integrals needed by the CSBEND fringe model method 5.
• elasticScatteringAnalysis — Computes elastic gas scattering lifetime and loss distribution from multi-location tracking data, Twiss parameter output, and gas pressure distribution. Use with output of the elastic_scattering command in Pelegant. (Program by M. Borland.)
• elasticScatteringLifetime — Computes elastic gas scattering lifetime from single-location dynamic acceptance and Twiss parameter output, assuming a constant gas pressure. (Program by M. Borland.)
• elasticScatteringLifetimeDetailed — Computes elastic gas scattering lifetime from single-location dynamic acceptance and Twiss parameter output, using a user-supplied, s-dependent gas pressure. (Program by M. Borland.)
• elegant2astra — This program translates elegant phase space files into ASTRA [30] format. (Program by M. Borland.)
• elegant2track — This program translates elegant phase space files into TRACK [32] format. The ASCII version of TRACK is assumed. (Program by M. Borland.)
• elegant2genesis — This program performs slice analysis of particle output files, which are suitable for use with the SDDS-compliant APS version of GENESIS[14]. This program is part of the SDDS toolkit. See the SDDS toolkit manual for documentation. (Program by R. Soliday and M. Borland.)
• elegantto — Translates an elegant-style lattice file (or a MAD file, with some restrictions) into formats accepted by other programs, such as COSY, PARMELA, PATPET, PATRICIA, TRANSPORT, XORBIT, and MAD8. Will also generate an SDDS file containing lattice data. (Program by M. Borland.)
• generateBunch — Generates a gaussian-distributed bunch.
• generateBunchTrain — Generates a very flexible multi-train bunch file.
• haissinski — Computes the steady-state longitudinal distribution in an electron storage ring. Requires as input a file containing the Twiss parameters around the ring, such as that provided by the twiss_output command. Wakes can be specified with either a L, R model, a BBR resonator model or a wake function. Other inputs are external rf system parameters, with possibility of a harmonic cavity. Output is a charge or current profile with longitudinal time coordinate (front of bunch is at positive times). (Program by L. Emery and M. Borland.)
• ibsEmittance — Computes local intra-beam scattering rates for both storage ring and linac. Also computes the equlibrium transverse and longitudinal emittances of a beam in an electron storage ring, resulting from the combination of quantum excitation, damping, and intra-beam scattering. Requires as input a file containing the Twiss parameters, such as that provided by the twiss_output command. (Program by L. Emery, M. Borland, and A. Xiao)
• impact2elegant — Tranlates IMPACT-T [31] output into elegant conventions. (Program by M. Borland.)
• impact2sdds — Translates IMPACT-T output files into SDDS for easier postprocessing. (Program by M. Borland.)
• ionTrapping — Uses lattice function data from elegant to compute ion trapping condition in a ring. (Program by M. Borland.)
• LFBFirSetup — This script prepares data that can be used to configure turn-by-turn longitudinal feedback using TFBDRIVER and TFBPICKUP elements. (Program by M. Borland.)
• longitCalcs — Performs calculations of longitudinal dynamics parameters in storage rings, using output from elegant’s twiss_output command. Can also compute voltages for bunch lengthening and output these to a file that can be use with load_parameters. (Program by M. Borland.)
• makeSummedCsrZ — Computes the shielded or free-space steady-state CSR impedance for a ring composed of one or more types of dipole magnet. The output can be used immediately with elegant’s ZLONGIT element. (Program by M. Borland.)
• plotTwiss – Plots the twiss parameters using data from the twiss_output command. (Program by L. Emery and M. Borland.)
• plotTwissBeamsize – Plots the beam sizes using data from the twiss_output command.
• prepareTAPAs — Allows processing files from twiss_output into a form that is accepted by the Android App TAPAs [46]. The resultant files can be copied to, e.g., the downloads area on the Android device, from which they can be read by TAPAs for configuration of the Storage Ring Scaling activity. (Program by M. Borland.)
• radiationEnvelope — A tool for use with the output of sddsbrightness and sddsfluxcurve. It analyzes data for many harmonics and produces a single curve that shows the envelope of maximum brightness or flux over all harmonics. (Program by M. Borland.)
• removeBackDrifts — Allows post-processing s-dependent files to remove negative drifts, which improves the appearance of plots and is needed for certain types of analysis. (Program by M. Borland.)
• sddsanalyzebeam — Analyzes a beam of macro-particles and produces an SDDS file containing beam moments, emittances, equivalent beta functions, etc. The beam file is of the type written by elegant using the output field of the run_setup command, or the WATCH element. (Program by M. Borland.)
• sddsbrightness — Uses twiss parameter output or data from sddsanalyzebeam to compute undulator brightness curves. (Program by H. Shang, R. Dejus, R. Lindberg, M. Borland, X. Jiao.)
• sddsbs — Computes bending magnet spectra. (Program by H. Shang and M. Borland.)
• sddsbunchingfactor — Computes bunching factor vs frequency from phase space data. (Program by M. Borland.)
• sddsemitproc — Analyzes quadrupole scan emittance measurement data. Accepts a file containing the transport matrix for each point and measured beam sizes. The file may, for example, be the file produced by the final field of the run_setup command. The quadrupole scan can be executed inside of elegant using vary_elements. (Program by M. Borland.)
• sdds4x4sigmaproc — Analyzes quadrupole scan beam moment measurement data to determine the initial 4x4 sigma matrix of the beam. Accepts a file containing the transport matrix for each point and measured beam sizes. The file may, for example, be the file produced by the final field of the run_setup command. The quadrupole scan can be executed inside of elegant using vary_elements. (Program by M. Borland.)
• sdds5x5sigmaproc — Analyzes quadrupole scan beam moment measurement data to determine the initial 5x5 sigma matrix of the beam. Accepts a file containing the transport matrix for each point and measured beam sizes. The file may, for example, be the file produced by the final field of the run_setup command. The quadrupole scan can be executed inside of elegant using vary_elements. To work, requires a horizontal bending magnet in the beamline and variation quadrupoles before and after the bending magnet. (Program by M. Borland.)
• sddsfindresonances — Uses output from frequency map analysis to find and identify resonance lines. (Program by H. Shang, M. Borland.)
• sddsfluxcurve — Uses twiss parameter output or data from sddsanalyzebeam to compute undulator flux tuning curves. (Program by M. Borland, H. Shang, R. Dejus.)
• sddsmatchmoments — Transforms a beam of macro-particles to match a given set of 6x6 beam moments, where the moments are stored in an output file from moments_output.
• sddsmatchtwiss — Transforms a beam of macro-particles to match to given beta functions and dispersion. The beam file is of the type written by elegant using the output field of the run_setup command, or the WATCH element. (Program by M. Borland.)
• sddsws — Computes wiggler spectra, using code from WS (by R. Dejus). (Program by H. Shang.)
• sddsurgent — Uses algorithms from the programs US (by R. Dejus) and URGENT (by R. Walker) for computation of undulator radiation properties, including power density and intensity distributions. (Program by H. Shang, R. Dejus, M. Borland, X. Jiao.)
• sddsrandmult — Simulates the effect of random mechanical errors in a quadrupole or sextupole, generating multipole error data that can be used with elegant’s KQUAD and KSEXT elements. (Program by M. Borland.)
• sddssampledist — Allows creating particle distributions from user-designed distribution functions. It is thus a more flexible alternative to bunched_beam. This program is part of the SDDS toolkit. See the SDDS toolkit manual for documentation. (Program by M. Borland and H. Shang.)
• sddsupsample — Allows up-sampling a particle distribution to improve statistics in tracking runs. (Program by GPT-5.2-Codex and M. Borland.)
• smoothDist6s — Increases the number of particles in an input particle distribution. At the same time, smooths the distribution and adds optional energy and density modulation. Intended to be used to increase the number of particles produced by a photoinjector simulation to improve stability of CSR and LSC simulations. Also useful in studying the growth rate for energy and density modulations. See also doubleDist6. (Program by M. Borland.)
• The script spiffe2elegant allows converting the output of the PIC code spiffe to the same form as output by elegant. Note that elegant will read spiffe output directly. This script just allows converting the data for use with related programs, such as sddsanalyzebeam. (Program by M. Borland.)
• straightDipoleFringeCalc — Computes fringe integrals needed by the CCBEND fringe model. Computes fringe integrals and other parameters needed by the LGBEND segmented dipole model.
• TFBFirSetup — This script prepares data that can be used to configure turn-by-turn transverse feedback using TFBDRIVER and TFBPICKUP elements. (Program by M. Borland.)
• touschekLifetime — This program calculates Touschek lifetime using A. Piwinski’s formula. Input files are generated from “twiss_output” and “momentum_aperture”. (Program by A. Xiao and M. Borland.)
• track2sdds — Translates output files, including phase space files, from version 39 of TRACK (with ASCII output [32]) into SDDS. (Program by M. Borland.)
• track2mag — Uses TRACK output files to create a file similar to the magnets outupt file from elegant. This gives a profile of the beamline that can be plotted with other data. (Program by M. Borland.)
• trwake2impedance — Translates a transverse wake (e.g., used for TRWAKE) into an impedance usable with ZTRANSVERSE. (Script by M. Borland.)
• view3dGeometry — Uses freewrl viewer to display 3D geometry of a lattice. (Program by A. Petrenko and M. Borland.)
• wake2impedance — Translates a longitudinal wake (e.g., used for WAKE) into an impedance usable with ZLONGIT. (Script by M. Borland.)
• The scripts makeSkewResponseCP and correctCoupling can be used to compute the cross-plane response matrices for skew quadrupoles and to perform coupling correction using those matrices. (Program by M. Borland.)