7.49 moments_output

• type: action/setup command.
• function: compute periodic or propagate non-periodic beam moments without tracking, optionally including radiation and intrabeam scattering.
• sequence: must follow run_setup.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• filename — The (incomplete) name of a file to which the moments results will be written. Recommended value: “%s.mom”.
• output_at_each_step — A flag indicating, if set, that computations and/or output is desired at each step of the simulation. If you wish to compute Twiss parameters on a closed orbit or after other calculations, be sure to set this control to a nonzero value.
• output_before_tune_correction — A flag indicating, if set, that output is desired both before and after tune correction.
• final_values_only — A flag indicating, if set, that only the final values of the Twiss parameters should be output, and not the parameters as a function of s.
• verbosity — Larger numbers result in an increasing amount of informational output to the standard output stream.
• matched — A flag indicating, if set, that the periodic or matched moments should be found.
• equilibrium — A flag indicating, if set, that the equilibrium moments should be found. If matched=1 and equilibrium=0, then the initial twiss parameters are computed from the periodic solution for the beamline.
• force_e1_gt_e2 — Sometimes the two transverse modes are misidentified, leading to e₁ < e₂. If set, this flag exchanges the two modes to force e₁ > e₂.
• radiation — A flag indicating, if set, that synchrotron radiation effects should be included. N.B.: this flag is all that needs to be set if the lattice contains no kick elements. However, if the lattice contains CSBEND, CSRCSBEND, KQUAD, or KQUAD elements (or other elements with SYNCH_RAD and ISR parameters), then the SYNCH_RAD andISR must be set to 1 as well.
• ibs_iterations, ibs_output_iterations, ibs_iteration_fraction, ibs_coulomb_log — If ibs_iterations is non-zero, intrabeam scattering computations will be performed using the diffusion matrix [20]. Because IBS depends on the beam dimensions, the computation is iterative. A suggested minimum value of ibs_iterations is 10. By default, the output file contains only the results of the final iteration; if ibs_output_iterations is non-zero, results are output for each iteration, which can be used to check convergence. There are several parameters in the output file that can also be used, namely, e1Convergence, e2Convergence, and e3Convergence, which give the fractional change in the normal-mode emittances from the final step. If the Coulomb log is not positive, it will be computed using the method outlined in [20].
• n_slices — The number of slices into which to cut individual dipoles, quadrupoles, and sextuoples for computations. 10 has been found to work for all rings tested, but users are advised to ensure it is sufficient for their cases.
• tracking_based_diffusion_matrix_particles — For most elements, the diffusion matrix determined by moments_output is computed used matrix concatenation. For some elements, this doesn’t work well because of possible internal coordinate transformations. For these elements, the diffusion matrix is determined approximately by tracking an ensemble of tracking_based_diffusion_matrix_particles particles. Setting this parameter to 0 will disable this feature.
• emit_x, beta_x, alpha_x, eta_x, etap_x, and related quantities for y and z — If matched=0, then these specify the starting beam ellipses in all three planes.
• pressure_data — The name of an optional SDDS file giving the residual-gas pressure profile along the lattice. If provided, the effect of elastic (Coulomb) scattering of the beam from residual-gas nuclei is included as a diffusive growth of the transverse divergences. The format of this file is described below.
• pressure_factor — A factor by which all pressure values read from pressure_data are multiplied as the file is read. This is convenient for scaling an entire pressure profile, for example to model a different base pressure or to apply a safety margin, without editing the data file. The default is 1.0.

This command performs several functions. In the most basic form, it propagates beam moments, i.e., the 6x6 sigma matrix, from the beginning to the end of a transport line, including coupling from rotated elements or offset sextupoles. This can be performed with or without synchrotron radiation effects in dipoles, quadrupoles, and sextupoles. These computations include the evolution of the trajectory due to errors and (if included) synchrotron radiation.

If desired, the command will instead compute the periodic beam moments. In this case, the user must include an appropriate rf cavity in the lattice in order to get valid results. (By “appropriate rf cavity” we mean that it must have the right voltage, frequency, and phase to support stored beam.) It is also suggested that the user compute the closed orbit using closed_orbit so that the computations are performed on the closed orbit.

The results of moments computation may be subjected to optimization using values at marker elements. See the documentation for MARK for more details.

If a pressure_data file is supplied, moments_output includes the emittance growth due to elastic (Coulomb) scattering of the beam from residual-gas nuclei. At each element a diffusion term is added to ⟨x^′2⟩ and ⟨y^′2⟩ based on the local partial pressures, the gas species, the gas temperature, and the beam momentum. The same physics is available during tracking with the MATTER element when FORCE_MCS=1.

The pressure-data file is an SDDS file with the following structure:

• Column s (units m) — the location along the lattice. The values must be monotonically increasing and uniformly spaced (to within 0.1%). The program sddsinterp with the -equispaced or -sequence option can be used to transform data that is not equispaced.
• One floating-point column per gas species, named for that species (see the list below), giving the partial pressure of the species as a function of s. The units must be Torr (or equivalently T) or nT (or equivalently nTorr); values given in nT are converted to Torr automatically. Each value is also multiplied by pressure_factor.
• Optional parameter Gasses (an SDDS string) — a comma- or space-separated list of the species to use, e.g. "H2O H2 N2 O2 CO2 CO CH4". If this parameter is absent, every column whose name matches a recognized species is used automatically.
• Optional parameter Temperature (units K) — the gas temperature, used with the ideal-gas law to convert pressure to number density. If absent, 293 K is assumed.

The recognized gas species are H2, H2O, N2, O2, CO2, CO, CH4, C, CH3, OH, C2H2, C2H4, COH, C2H6, C2H5, and CF3. When Gasses is absent, columns whose names are not in this list are ignored; if a species named in Gasses is not recognized, a warning is issued.

Notes:

• When using CSBEND, KQUAD, and KSEXT elements, one may find that the calculations of moments_output do not make sense. This is because, by default, synchrotron radiation is disabled on these elements. To resolve the issue, set ISR=1 and SYNCH_RAD=1 on CSBEND at a miminum. If a closed orbit is present, making the same setting on the KQUAD and KSEXT is also suggested. It is essential to do this if there is an rf frequency offset.
• When bending magnets are tilted, elegant has problems computing the moments and closed orbit self-consistently when the bending radius is small. To address this, the n_slices parameter is set to 1 for tilted bending magnets when slice_etilted=0. This reduces the accuracy of the calculations. Users are strongly advised to check that this is acceptable.
• The program sddsmatchmoments is available to transform a particle distribution so that its 6x6 beam moments match those given in a moments_output output filename. In addition, the bunched_beam command provides a similar capability for generating a distribution from computed moments.