Release Notes for Elegant

Version 14.3

Version 14.3 of elegant is now available. There are no significant bug fixes in this version, but there are some useful and interesting new features. APS users will get this version automatically.
1. elegant now reads and writes platform-independent binary SDDS files. That means that you can share a binary SDDS file from a PC with a friend who uses a Sun workstation. In the past, the friend would have had to use the program sddsendian to convert the file. To make use of this feature, you and your friends must upgrade to SDDS1.19. This is a backward-compatible upgrade so you won't have any problems if you upgrade elegant only.
2. Added the "type" parameter to the alter_elements command. This allows specifying the element type for elements to be altered. Also, the wildcard range feature for the "name" and "exclude" fields now functions properly. For example:
&alter_elements
name = Q[1-5]*,
exclude = Q[3-5]X,
type = QUAD,
item = K1,
value = 0
&end
This would set the strength of quadrupoles Q1*, Q2*, ..., Q5* to zero, except it wouldn't touch Q3X, Q4X, or Q5X.
3. The interpretation of wildcard ranges for the element_type field of the error command had a bug that has been fixed.
4. The SREffects element (which does quantum excitation, radiation losses, and damping) has been corrected for case when user turns off losses or damping. The previous version would miscalculate the quantum excitation in such cases.
5. The bunched_beam command now supports a quiet-start feature using Halton sequences in place of random number generation. There are three new variables that control this feature. "halton_sequence" is an array of three flags that permit turning on Halton sequence generation for the horizontal, vertical, or longitudinal planes. For example, halton_sequence[0] = 3*1 will turn on Halton sequences for all three planes, while halton_sequence[2] = 1, will turn it on for the longitudinal plane only.
"halton_radix" is an array of six integers that permit giving the radix for each sequence (i.e., x, x', y, y', t, p). The radix must be a prime number. You should never use the same prime for two sequences (with one exception, see below). If these are left at zero, then elegant chooses values that eliminate phase-space banding to some extent.
"randomize_order" is an array of three integers that permit instructing elegant to randomize the order of coordinate pairs relative to other coordinate pairs. You may use this any time, but it is recommended with Halton sequences to prevent banding. Because the randomization is pair-wise, the special properties of the Halton sequences are retained for each pair (i.e., x-x', y-y', t-p), while banding between members of different pairs is eliminated.
I suggest the following values if you use Halton sequences:
halton_sequence[0] = 3*1,
halton_radix[0] = 2, 3, 2, 3, 2, 3,
randomize_order[0] = 3*1,
I am interested in feedback on this feature as I've had limited opportunity to evaluate whether it is worthwhile. If you choose not to use the randomization feature, I strongly suggest that you plot the initial phase space and look at *all* coordinate pairs (e.g., y-t, x-p, etc.) to verify that you don't have unacceptable banding. Banding is an annoying but apparently unavoidable result of using these kinds of sequences.
6. The optimization_term command has a new parameter, "weight." The default value is 1. The value can be changed to increase the weight of a term. This is sometimes easier than changing the equation.
On a related note, the optimization_setup command has a new parameter, "balance_terms." If set to 1, then upon initialization the optimizer adjusts the weights of all terms to make their contribution to the optimization function equal.
7. The optimizer has a new method, called "powell", which invokes a Powell's method optimizer instead of the default Simplex method. The new method works in many cases but there appears to be a bug that results in an infinite loop in other cases. At this point, treat it as a "beta" feature.
8. The WATCH element has a new parameter, flush_interval, that is active when in coordinate mode. This allows instructing elegant to flush coordinate data on every nth pass. The default value is 0, which means flushing of data occurs only at the end of the tracking step. Use a nonzero value if you want to be able to view the turn-by-turn coordinate data while the simulation runs. This feature was requested by Zhirong Huang.
9. The WATCH element now internally tracks the time-of-flight of the "reference" particle. The column dCt for parameter/centroid mode is now t-tReference. dt for coordinate mode is also more accurate, in that if the reference momentum changes, it is properly calculated.
10. The implementation of floor coordinate computations was completely rewritten, following the method in the MAD 8.1 manual. This allows inclusion of vertical as well as horizontal bending. Alpha magnets now support the TILT parameter and floor coodinate computation is done correctly for these magnets. However, the calculation of the survey angles is not correct for alpha magnets or other large-angle (e.g., 180 or more) bends.
11. I improved the error messages from WAKE and TRWAKE elements and changed default Savitzky-Golay filter order to 1 (was 2 for most wake and impedance elements). NB: This may change results if you are doing smoothing of wakes!
12. The program sddsanalyzebeam, which analyzes elegant output beams to give emittances, twiss parameters, etc, was upgraded to supply two types of beta function values. The "corrected" values use the transverse moments with the dispersive terms removed; these values have names like betacx, alphacx, etc. You should use these values if you really have dispersion at the point of analysis or think you can correct whatever dispersion you have. The "nominal" values use the transverse moments without the dispersive terms removed; these values have names like betax, alphax, etc. You should use these values if you have no (correctable) dispersion at the analysis point. This problem was brought to my attention by Paul Emma. The prior version only gave the corrected values.
13. The program ibsEmittance, which performs intra-beam scattering computations for storage rings, now supports the "energy" commandline option. This allows changing the energy at which the computation is done to differ from the energy of the elegant run.

Version 14.2

Version 14.2 of elegant is now available. I strongly recommend upgrading to this version, as 14.1 had some bugs and 14.2 has some nice new features. The following is a summary of changes to elegant in version 14.2.
Note that if you build elegant yourself, you'll need to download SDDS1.18beta as well.
1. Added first- and second-order dependence of the path-length on fractional strength error (FSE) for bending magnet matrix. This change affects the SBEN and RBEN elements.
2. Added emit_nx and emit_ny parameters to the bunched_beam command. These allow input of the normalized emittances. To use these alternate parameters, just leave emit_x and/or emit_y with the default values of 0.
3. Now correctly computes matrices for alpha magnets (ALPH element) and stray fields (STRAY element) in the presence of changes in central momentum. Prior versions would incorrectly compute matrices for these elements at the initial central momentum. These elements are unusual. The STRAY element requires specifying an actual field (in T). The ALPH element requires specifying the size of the alpha, which one usually does with a certain momentum particle in mind.
4. The sasefel command now does computations for beam slices, in addition to providing the slice-average and the whole-beam results. The usage is now
&sasefel
output = FILENAME,
beta = BETAFUNCTION, ! if 0, computed from beam (default)
undulator_K = K-VALUE,
undulator_period = METERS,
slice_fraction = FRACTION, ! if zero, no slices done
n_slices = INTEGER, ! if zero, no slices done
&end
If slice_fraction*n_slices<1, then the slice analysis is centered on the median of the time distribution. E.g., n_slices=1 and slice_fraction=0.1 would analyze the central 10% of the beam. More typically, one gives values such that slice_fraction*n_slices=1, so every part of the beam is analyzed.
5. Added REMCOR element type (REMoves beam CORrelations). This element is used to emulate certain corrections that one might apply, without the need to sweat the details. For example, one might want to remove all correlations between (x, x', y, y') and energy, to emulate a dispersion correction in a linac or transport line. This is the default action of the element. Parameters:
X Default is 1. If nonzero, remove correlations for x.
Y Default is 1. If nonzero, remove correlations for y.
XP Default is 1. If nonzero, remove correlations for x'.
YP Default is 1. If nonzero, remove correlations for y'.
WITH Default is 6, value may be any integer from 1 to 6.
This is the number of the phase space coordinate with
which to remove correlations.
ONCE_ONLY
Default is 0. If nonzero, then the correction is computed
for the first beam seen. It is then applied without
change to all subsequent beams.
6. The steering_element command now accepts wildcards on the 'name' and 'element_type' fields.
7. The CSRDRIFT element has several new modes for computing the spread of the beam (which results in intensity change for the CSR wake). The new parameter is SPREAD_MODE, and may have values "full", "simple", and "radiation-only". "full" is the previous mode: the full electron phase-space is convolved with a gaussian photon phase space; the problem is that this can sometimes result in a converging photon beam, so that CSR effects increase as one travels down the drift. If you consider this unphysical, then "simple" mode just adds the electron and photon beam divergences; the radiation will always decrease in strength along the drift. Finally, "radiation-only" mode ignores the electron beam contributions.
Previous versions of elegant had a bug that occured when a CSRDRIFT was upstream of all CSRBENDS. (Strictly speaking, this is an error, but elegant didn't give a warning.) If you tracked multiple beams, the upstream CSRDRIFT would pick up the CSR wake from the furthest downstream CSRBEND. This is fixed in 14.2.
8. CSRCSBEND has two new parameters:
ISR Default value 0. If nonzero, then incoherent synchrotron radiation scattering is included, which increases energy spread and, as a result, the emittance.
OUTPUT_LAST_WAKE_ONLY
Default value 0. If nonzero, then the OUTPUT_FILE contains only the final wake, instead of the wake at intervals through the bend.
9. The implementation of the RFDF (rf deflector) has been completely rewritten. The previous implementation was intended only for nonrelativistic particles (few MeV). Several parameters were removed and the meaning of others was changed. The parameters in the new implementation are:
L Length (m). Default is 0.
PHASE Rf phase (degrees). Default is 0 (on-crest).
TILT Rotation about the longitudinal axis (rad). Default is 0
(horizontal deflection).
FREQUENCY Rf frequency (Hz). Default is 2856MHz.
VOLTAGE Total rf voltage (V). Default is 0.
N_KICKS Number of kicks through length L. Default is 1.
TIME_OFFSET
Time offset of rf waveform. Equivalent to
PHASE->PHASE+Omega*TIME_OFFSET.
PHASE_REFERENCE
Integer phase reference used to synchronize this element to other rf
elements.
10. The "sigma" and "final" output files (from run_setup) now include the "corrected" emittances for x and y planes. These emittances have the linear correlations with energy removed, so that, for example, when you go through a chicane you don't see a big bump in apparent emittance due to the dispersion. The names are "ecx" and "ecy" for the geometric x and y emittances, and "ecnx" and "ecny" for the normalized emittances.
11. Fixed a somewhat stupid bug in the "final" output file data. The bunch length (St) would sometimes be badly miscomputed for low energy beams with large velocity spread.
Items 2, 5, 8 (ISR), 9, and 10 were suggested by P. Emma (SLAC). Item 6 was suggested by L. Emery (APS). Item 11 was discovered by J. Lewellen (APS). Thanks to all.
PS Downloading is a little more involved now. You must first obtain a download key, which you can continue to use for up to 30 days before obtaining a new one. To get a key, simply attempt to download, then enter your name and email address. Press "request download key". A download key will be emailed to you. You then enter this key the next time you want to download something. You must give *exactly* the same name and email address every time you use the key. This change was implemented after we had some anonymous downloads where people gave bogus names and email addresses. I apologize for the inconvenience. If you have downloading problems, contact soliday@aps.anl.gov

Version 14.1

The following changes and bug fixes were made for version 14.1 (version 14.0 was skipped).
1. A number of changes were made to reduce memory use during tracking. In the past, elegant always kept the initial coordinates of the particles being tracked, even if they wouldn't be needed. Now, the code is smarter about determining when it needs to keep these coordinates. In addition, one can force the code to not keep these coordinates (which means it may regenerate them or reread them from a file). This is done in the bunched_beam and sdds_beam namelists, by setting the new variable save_initial_coordinates=0. By default, this variable is 1, giving the old behavior.
One change required in both bunched_beam and sdds_beam namelists was separation of the beam-generation random numbers from other random numbers. This may produce a change in the exact coordinates used in a run, if you are doing detailed comparisons to older runs.
Using these changes, I've been able to run 1 million particles in elegant on a PC with 128MB of RAM.
2. Fixed a bug in ZTRANVERSE for BROAD_BAND=1: the impedance function had real and imaginary parts exchanged. Generally, using the broad-band mode of ZLONGIT and ZTRANSVERSE isn't recommended in any case, as it is much slower than RFMODE and TRFMODE.
3. Added BnL_units item to correction_matrix_output namelist. Allows for output of response matrix in terms of m/(T*m), which shows the effect of beam energy, for example. It is handy if you want to compare measured R12's in a linac to simulated values and don't want to scale from m/rad.
4. Floor coordinate calculations had a problem with bending magnets when the angle was zero. This was fixed.
5. The error_element namelist has a new qualifier called element_type. This allows specifying the element type(s) to which a error is applied. The element_type specification may contain wildcards. You may also now leave the name specification blank, provided you give an element_type. For example, to assign x errors to all monitors, you could use
&error_element
element_type = *MON*,
item = DX,
amplitude = 1e-4
&end
This change was suggested by P. Emma (SLAC).
6. The calculation of the loss factor from the shunt impedance in RFMODE and TRFMODE was fixed. Previously, the calculation used the loaded Q, which is wrong (should use the unloaded Q). This only made a difference if beta was not 1. This change and some others resulted in much improved "preloading" of rf modes, which reduces start-up transients. The "record" output from RFMODE was modified to provide data that allows restarts of runs using RFMODE elements.
7. The tReference parameter was added to the RFCA element. This permits specifying the reference time for the phase. By default, the first beam passage is used, but this is sometimes inconvenient, particularly if you are planning restarts and need a reference that is fixed over several runs.
8. The twiss command now loads the dispersion from the reference file. Previously, it only loaded the betas and alphas.
9. The RFDF (rf deflector) was reporting that PHASE had units of radians when it was really degrees. This was fixed.
10. You can now perform floor-coordinate optimization for interior points. As with Twiss parameters, just insert a MARK element with FITPOINT=1. You can then access the floor coordinates at this marker using the syntax #., where is X, Z, or theta.

Version 13.19

NOTE: To use elegant 13.19, you must first download and install version 1.15 or later of the SDDS toolkit.
This version includes several bug fixes, one of which is important for simulations where beams have "large" velocity spread.
1. The RFCA and RFCW elements had an omission in the code used when N_KICKS=0 (transverse matrix tracking instead of kick tracking). This resulted in incorrect time-of-flight computations. This bug is particularly bad if your beam is low energy and has significant energy spread. For the kind of things normally simulated with elegant, the effects are relatively small. For example, in the APS bunch compressor, I found a 3-10% change in peak current after fixing the bug, depending mostly on how much energy spread the beam had going into the chicane. However, if I simulate the APS thermoinic rf gun (few MeV and 10% energy spread), the effects are dramatic.
This impacts versions 13.15 and later. However, if you were using N_KICKS=1, there was never a problem.
2. The code that computes bunch length for the "sigma" and "final" output files was rewritten to avoid round-off problems that crop up in long accelerators. Previously, one could get significant errors in the "Ss" quantity. The other, related quantities, such as St, Dt, etc. (all time-based) did not show this problem as they were computed differently.
Although Ss is now computed more accurately, its interpretation is still not always straightforward. Because s=beta*c*t, if there is a spread in beta, < s^2 > is not necessarily proportional to < t^2 >. Only for beams with small velocity spread does the intuitive proportionality hold.
3. The "optimization_term" command was added, to allow easier input of optimization equations. Basically, with this command you can give individual terms in the optimization equation separately. As optimization proceeds, elegant reports the value of each term, so you can see which term is causing problems, for example. To use this feature, leave the "equation" entry in "optimization_setup" blank. Then, give one or more "optimization_term" commands. Syntax:
&optimization_term
STRING term = NULL;
&end
4. Lattice files may now include other files using the new "#include" command. For example, you could keep a set of files for elements and beamlines from different parts of you linac, then include just those you are interested in for a particular simulation. Syntax:
#include: ""
Note that the filename must be in quotes.
5. Previously, if all particles were lost, the sigma and centroid output files would contain incorrect values of the s coordinate for locations that the beam did not reach. This has been fixed.
6. The "record" file for the RFMODE element has been changed to make make the data more useful for reinitialization. The RFMODE element has a new parameter, INITIAL_T, which can be set from the record file when restarting a run. This feature has not been fully tested! However, due to point 1, above, I thought it advisable to release this version now.
7. SASE FEL computations (sase_fel command) now use the average momentum rather than the fiducial momentum. As a result, light wavelength will vary correctly with the beam energy.
8. The program "sddssasefel" (included in the elegant distribution) now supports commandline setting of undulator K, period, and beta. It also accepts elegant "final" files as input.

Version 13.18

This version has one bug fix and one improvement, so it isn't a big change except for users who simulate long linacs with wakes:
1. The bug fix is that the RFCW element now really accepts the longitudinal wake file. Before it refused to recognize it.
2. The improvement is that memory management for wake elements was changed to significantly reduce the amount of memory used for long linacs with many wake elements per section. If you find your elegant jobs are using lots of memory, this may help you.

Version 13.17

1. Added DX and DY parameters to RFCA, so that RFCA's can be misaligned. 2. Added RFCW element, which combines RFCA, TRWAKE, and WAKE elements. This was suggested by Paul Emma. The element automatically scales the per cell wake to the length of the element. Parameters of the element are the same as RFCA except:
Cell_Length --- Length of cell in meters.
WakeFile --- Wakefile for all wakes. (optional)
ZWakeFile --- Wakefile for longitudinal wake only. (optional)
TrWakeFile --- Wakefile for transverse wake only. (optional)
tColumn --- Column for t data.
WxColumn --- Column for Wx data.
WyColumn --- Column for Wy data.
WzColumn --- Column for Wz data.
N_Bins --- Number of bins for histograms (default is 0=autoscale).
Interpolate --- Interpolate between bins (0/1)?
Smoothing --- Smooth convolved wake (0/1)?
SG_HalfWidth --- Half-width of Savitzky-Golay filter for smoothing (default=4).
SG_Order --- Order of Savitzky-Golay filter (default=2)
If WxColumn, WyColumn, or WzColumn is not specified, then the corresponding wake is not included. If WakeFile is specified but ZWakeFile (TrWakeFile) is not, then longitudinal (transverse) wakes are taken from WakeFile, if needed.
3. Added after/before parameters to error_element. This permits restricting the locations of elements to which an error is applied. "after" specifies restricting to locations following a named element, while "before" specifies restricting to locations preceding another named element. For example, you could put markers around different parts of a beamline and misalign only items between the markers.
4. Added wild-card support to the link_elements command ("target" parameter), along with a new "exclusion" parameter which applies to the selected target elements. For example, you could link a group of quadrupole misalignments to the misalignment of another element. [In the next version, I plan to add the before/after parameters to link_elements as well.]
5. In the previous version, the average Twiss parameters were not computed correctly if the lattice had only one element. This has been fixed.
I regret to say that the HTML version of the manual on the Web is still not current. The problem with the Latex-to-HTML converter has not been fixed. The latex files distributed with the source code are, however, up-to-date.

Version 13.16

Significant upgrades and bug fixes
1. Added CSRDRIFT element, which does CSR computations in drift spaces following a CSRCSBEND element. Details of how this is done were reported at the APS/SLAC/LANL/BNL videoconference a few weeks ago.
Parameters of the element are:
L --- The length in meters. Default is 0.
N_KICKS --- The number of wakefield kicks to use. Default is 1.
DZ --- The distance between the wakefield kicks. The default is 0, indicating that N_KICKS should be used to compute the distance. If nonzero, then N_KICKS is ignored. I prefer using DZ instead of N_KICKS, since with DZ I can specify a kick every 1cm, for example.
SPREAD --- A flag indicating whether to modify the intensity of the wake according to the transverse spreading of the radiation. 0, the default, means no spreading, so the wake maintains its intensity for an arbitrary distance. I suggest setting this flag to 1.
ATTENUATION_LENGTH --- The exponential attenuation length for the wake, in meters. Default is 0, meaning no attenuation.
2. Added the "alter_elements" command, which allows altering the properties of elements from the command file on a one-time basis. This is sometimes much more convenient than having to edit the lattice file. When combined with the save_lattice command, you can use it to create an altered lattice file.
Command syntax:
&alter_elements
STRING name = NULL,
STRING item = NULL,
STRING exclude = NULL,
double value = 0,
long differential = 0,
long multiplicative = 0,
long verbose = 0,
long allow_missing_parameters = 0
&end
'name' may contain wildcards and is used to specify the name of the elements to alter (e.g., BC1B1). 'item' is the name of the parameter to alter (e.g., ANGLE). 'exclude' may also contain wildcards and is used to exclude elements (e.g., name=BC1B*, exclude=*B4). 'value' specifies the new value of the item; the exact meaning depends on the flags 'differential' and 'multiplicative'. By default, 'value' explicitly gives the new value of the item. If 'differential' is nonzero, then 'value' is added to the initial value. If 'multiplicative' is nonzero, then 'value' is used to multiply the initial value. You cannot use differential and multiplicative modes together (nor is it necessary).
3. Fixed misalignment code for CSBEND, CSRCSBEND, and SBEND elements. The misalignments are specified in the coordinates at the input to the dipole. This was implemented as pair of beam displacements, one at the entrance and one at the exit. The computation of the exit displacement was incorrect (typically too large). The new code has been checked on 45, 90, and 180 degree sector bends and gives the expected results.
4. The program will now correctly do trajectory correction for beamlines containing CSR elements.
5. I added the FIXPLIMITS parameter to PFILTER. If given, the absolute momentum values of the PFILTER are fixed after the first bunch is seen and analysed. This is nice for jitter studies, as it simulates fixed scrapers without one having to compute the actual position of the scrapers.
6. The "parameters" output file from the run_setup namelist now includes integer parameters. The previous version only included floating point parameters. This should guarantee that a configuration loaded from such a file is identical to the configuration previously simulated.
7. The CSBEND, CSRCSBEND, and SBEND elements accept parameters K1, K2, K3, and K4 for the multipole components of the dipole field. These elements now accept a flag "USE_BN" and parameters B1, B2, B3, and B4. If USE_BN=0 (the default), the K1, K2, K3, and K4 parameters are used. If USE_BN=1, then the B1, B2, B3, and B4 parameters are used. These specify the nonlinear terms in units of 1/m^n for b. Hence, the dipole field for y=0 is Bo*(1 + B1*x + B2*x^2 + B3*x^3 + B4*x^4), where Bo is the field at x=0. This is sometimes more convenient as K1, K2, K3, and K4 depend on beam energy.
Minor upgrades and bug fixes:
1. Revised the logic for trajectory/orbit correction and trajectory/orbit output in tracking section so that the program doesn't correct the trajectory twice.
2. The twiss output file now contains statistics on betas and etas.
3. Added once_only parameter to the CENTER element. This allows centering the first beam that is seen. Thereafter, it acts like a beam misalignment in x, x', y, and y', with the misalignment equal to whatever was required to center the first beam. You might use this, for example, to null out the effects of a centroid offset due to a beam shape distortion, without nulling out the effects to trajectory errors that are added in subsequent passes throught the beamline.
4. Normalized emittances are now computed using the average beam momentum, rather than the central momentum. The central momenum may be different from the average momentum if a fiducial beam was used.
5. When saving a lattice, continuation line breaks are now made just following a comma whenever possible.
6. Fixed bug that resulted in loading incorrect particle data when using spiffe beams with reuse_bunch=1 and one_random_bunch=0.
7. For the WAKE and TRWAKE elements, now detect if beam is longer than the wake function and abort, as this would cause unphysical results. Also abort if wake function doesn't begin at t=0 (used to just issue a warning).

Version 13.15

Bug fixes
1. Fixed bug in the analyze_map function, which resulted in the part of the map depending on y and y' being computed as 0. (This is a rarely used function that computes the first-order matrix from tracking. It is mostly a debugging aid to ensure consistency between tracking and matrix concatenation.)
2. The SCRAPER element had a bug that resulted in the scraper being inserted into the beam (at x=0) by default. It is now withdrawn by default.
3. Fixed a bug that may have resulted in runs with rf elements and phase/timing errors working incorrectly. I say "may" because the runs worked in the last release, but the code had an obvious logic error that should have made them not work. [I hate it when that happens.] If you have done such runs I suggest spot-checking them with the new version.
Improvements:
1. Added the echo_lattice flag to the run_setup command. If set to 1, then elegant echoes the lattice file input to the terminal as it reads it. This can help to diagnose lattice file problems that sometimes make elegant crash.
2. RFCA element:
a. Fixed the R65 matrix element. This wasn't actually used anywhere (tracking doesn't use the matrix for longitudinal motion) and the error was a small one, but it is fixed now.
b. Added end focusing effects per R. B. Neal (SLAC Two-Mile Linac, section 7-1). This was suggested by Paul Emma. To turn the effects on, use the two new flags END1_FOCUS and END2_FOCUS. It is off by default to give the previous behavior.
c. Added n_kicks parameter. If 0, a matrix is used for transverse coordinates during tracking, which is more accurate than the default kick method if a long RFCA is used. Presently n_kicks may be 0 or 1 only. If 1, the old method of one kick at the center of the RFCA is used. In the future, values greater than 1 will be implemented.
3. Collective effects elements: for these elements, elegant no longer recomputes the elements' private CHARGE parameter [use of which is now discouraged] based on the beam charge declared by the CHARGE element. This prevents some confusing and/or erroneous lattice files that occur in runs with saving/reloading of lattices. This applies to WAKE, TRWAKE, ZLONGIT, ZTRANSVERSE, RFMODE, TRFMODE, and IBSCATTER elements.
Also, if the user specifies charge per particle in the lattice file, the saved lattices and parameters will always reflect this. Previously, elegant would convert charge per particle into total beam charge and transfer that from run to run. If beam was lost during a run, this would erroneously increase the charge of each macroparticle to make the total charge constant.
4. Magnet profile output is now regenerated after every load_parameters command with change_defined_values=1 to make sure it is current. Elegant also recomputes the end positions of all elements (used for Twiss parameter and matrix output) after every such load_parameters command.
5. The 'final' output file now has parameters for the width of the central 80%, 90%, and 95% of the beam in time and fractional momentum offset. The names are Dt80, Ddelta80, etc.
These are also available in optimization. So, if you want to optimize your bunch compressor to have 300A current in the central 80% of the beam, you can use an optimization function like
"Charge 0.8 * Dt80 / 300 - abs"
(In non-rpn notation, that's abs((Charge*0.8)/Dt80-300).)
6. In saving lattices, elegant now prints element parameters to 16 figures to get a little better reproducibility (previously was 15 figures). For true reproducibility skip save_lattice and use the parameters file generated via run_setup.
7. The PFILTER element has to new parameters to allow more convenient filtering of momentum. The LOWERFRACTION and UPPERFRACTION parameters specify fractions of the beam to scrape away. For example, LOWER_FRACTION=0.05 and UPPER_FRACTION=0.01 would remove the least energetic 5% and the most energetic 1% of the beam. This is really handy for getting rid of tails when you don't know the energy distribution ahead of time.
8. The optimization_setup command has a output_sparsing_factor control. By default, it is 1, which means the 'final' file is updated every time the optimization function is evaluated. For greater speed, choose a higher number (e.g., 10 or 20). On PCs, this doesn't matter much, but on file-server systems, it can make a big difference.
9. WAKE and TRWAKE elements: Added an autoscaling feature for the number of bins. If n_bins is set to 0, then elegant automatically the minimum number of bins required to accomodate the beam given the time spacing of the points in the wake function. This is highly recommended for both convenience and performance.
10. The vary_element command now has a 'multiplicative' flag. If set to 1, then the variation is done by multiplying the starting value of the parameter by the number computed, rather than using the number itself. If combined with 'differential=1', one can vary a parameter in a fractional sense. E.g.,
&vary_element name=L1, item=VOLT, multiplicative=1, differential=1,
initial=-0.1, final=0.1, index_number=0, index_limit=11 &end
would vary the voltage of L1 by +/-10% in 2% steps, as would
&vary_element name=L1, item=VOLT, multiplicative=1,
initial=0.9, final=1.1, index_number=0, index_limit=11 &end

Version 13.14

New features include:
1. Ability to transfer Twiss parameters from a previous as the starting point of the current run. This is an augmentation of the twiss_output command. The new controls and their default values are
STRING reference_file = NULL;
STRING reference_element = NULL;
long reference_element_occurrence = 0;
To use the feature, give an elegant twiss output file (or any file with the same columns) as the reference_file. If you leave reference_element=NULL, then the twiss parameters at the end of the file are loaded. Otherwise, it loads the parameters for the named element. By default, the last occurrence of the named element is used, or you can specify the occurrence number (e.g., 1, 2).
2. Ability to transfer Twiss parameter starting point from the twiss_output command to the bunched_beam command. This (or something like it) was suggested by P. Emma. To use the new feature, give
use_twiss_command_values = 1
with the bunched_beam command. You have to have given twiss_output prior to this. It also doesn't work if you are matching to a periodic solution. 3. The optimize command has an additional control, n_restarts, to specify the number of times to restart the optimizer with the initial step-sizes. This can be very helpful if the optimizer doesn't converge in one run. The optimizer has three "looping" parameters now, with the following meaning
n_restarts: number of times to restart optimization routine afresh with the results of the last optmization but the same parameters (e.g., step size)
n_passes: number of times to run the simplex optimizer to convergence. The step-sizes (for determining the initial simplex) are recomputed before each pass.
n_evaluations: (approximate) number of function evaluations allowed per simplex pass.
4. The new version provides better control of rf phasing and momentum profile fiducialization, which is useful for linac simulations.
A. In the run_control namelist, there is a new variable called reset_rf_for_each_step. By default, it is 0, and elegant rephases the rf elements so that the bunch sees the phase specified in the lattice file, regardless of whether the bunch is explicitly delayed in time relative to the last bunch. If you don't want this (e.g., for phase jitter simulation), then set this control to 1.
B. Also in the run_control namelist, there is a new variable called first_is_fiducial. If set to 1, then the first bunch tracked is considered to establish the pCentral vs s profile for all subsequent runs. You still have to give reset_rf_for_each_step=0 in order to prevent rephasing of rf for each bunch; in that sense, the name of the new variable is a little misleading.
C. In the run_setup namelist, there is a new variable called always_change_p0. If set to 1, then the central momentum is recomputed at the end of each element. This is a convenience so you don't need to worry about giving it for each rf or wake element. If first_is_fiducial=1, then this feature only impacts the first beam through the lattice.
5. The error_control namelist has a new parameter, no_errors_for_first_step. By default, it is 0, so that all steps have errors as specified in the error_element namelists. If set to 1, the first step results in tracking the perfect machine. This allows elegant to get the rf phased for the perfect conditions. Subsequent beams will be perturbed about this point. Should be used with reset_rf_for_each_step=0 etc.
6. Zero-length correctors now contribute the proper dispersion. P. Emma found this bug.
7. RBEN elements are now properly implemented. Previously, I just treated them like SBEN elements (!). I guess no one ever used them until last week or I'd have known about it...
Thanks go to Paul Emma for suggestions leading to many of these changes.