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

&moments_output

STRING filename = NULL;

long output_at_each_step = 0;

long output_before_tune_correction = 0;

long final_values_only = 0;

long verbosity = 0;

long matched = 1;

long equilibrium = 1;

long radiation = 1;

long n_slices = 10;

long tracking_based_diffusion_matrix_particles = 1000;

long slice_etilted = 1;

double emit_x = 0;

double beta_x = 0;

double alpha_x = 0;

double eta_x = 0;

double etap_x = 0;

double emit_y = 0;

double beta_y = 0;

double alpha_y = 0;

double eta_y = 0;

double etap_y = 0;

double emit_z = 0;

double beta_z = 0;

double alpha_z = 0;

&end

STRING filename = NULL;

long output_at_each_step = 0;

long output_before_tune_correction = 0;

long final_values_only = 0;

long verbosity = 0;

long matched = 1;

long equilibrium = 1;

long radiation = 1;

long n_slices = 10;

long tracking_based_diffusion_matrix_particles = 1000;

long slice_etilted = 1;

double emit_x = 0;

double beta_x = 0;

double alpha_x = 0;

double eta_x = 0;

double etap_x = 0;

double emit_y = 0;

double beta_y = 0;

double alpha_y = 0;

double eta_y = 0;

double etap_y = 0;

double emit_z = 0;

double beta_z = 0;

double alpha_z = 0;

&end

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

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.

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.

momentum_aperture