7.24 coupled_twiss_output

• type: setup/action command.
• function: set up or execute computation of coupled twiss parameters and beam sizes
• sequence: must follow run_setup.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• filename — The (incomplete) name of the SDDS file to which coupled twiss parameters and beam sizes will be written. Suggested value: “%s.ctwi”.
• output_at_each_step — If nonzero, then this is a setup command and results in computations occurring for each simulation step (e.g., for each perturbed machine if errors are included). If zero, then this is an action command and computations are done immediately (e.g., for the unperturbed machine). 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.
• emittances_from_twiss_command — If nonzero, then the values of the horizontal emittance and the momentum spread are taken from the uncoupled computation done with the twiss_output command. In this case, the user must issue a twiss_output command prior to the coupled_twiss_output. If zero, then the values of the horizontal emittance and the momentum spread are taken from the parameters emit_x and sigma_dp, respectively.
• emit_x — Gives the horizontal emittance, if emittances_from_twiss_command=0.
• emittance_ratio — Gives the ratio of the x and y emittances. Used to determine the vertical emittance from the horizontal emittance. Note that the computation is not self-consistent. I.e., the user is free to enter any emittance ratio desired, whether it is consistent with the machine optics or now.
• sigma_dp — Gives the momentum spread, if emittances_from_twiss_command=0.
• calculate_3d_coupling — If nonzero (and an rf cavity is present so that the longitudinal motion is stable), the eigenvector decomposition is done in full 6-D phase space, producing three modes and a meaningful longitudinal-mode contribution to the sigma matrix (bunch length, dispersion). If zero, only the two transverse modes are computed. Forced to zero when matched=0, since the longitudinal initial conditions cannot be specified in transport-line mode.
• verbosity — Controls the amount of diagnostic information printed to standard output. Higher values produce more detail (eigenvalues, normalized eigenvectors, per-element A and sigma matrices).
• concat_order — Order at which transfer matrices are concatenated when forming the one-turn (or transport) map used to find the eigenvectors.
• output_sigma_matrix — If nonzero, the full upper-triangular sigma matrix is written to the output file as columns named Sij (1-indexed), in addition to the standard beam-size columns.
• matched — A flag indicating, if set, that the periodic (matched) coupled-twiss solution should be found, by diagonalizing the one-turn matrix. If zero, calculations are performed in transport-line mode starting from the user-supplied initial values beta_x1, alpha_x1, etc. (or from a reference_file). The longitudinal mode is not available in this case, so calculate_3d_coupling is forced to zero.
• beta_x1, beta_x2, beta_y1, beta_y2 — If matched is zero, the contributions of each transverse eigenmode to the corresponding plane β functions at the start of the beamline. By convention mode 1 is the x-like mode (dominant projection in x) and mode 2 is the y-like mode. In an uncoupled lattice beta_x2 and beta_y1 are zero. These values are the diagonal entries (A_k)_xx, (A_k)_yy of each mode matrix A_k at the start.
• alpha_x1, alpha_x2, alpha_y1, alpha_y2 — Initial values of the per-mode α functions (sign-flipped off-diagonal entries -(A_k)_xx′, -(A_k)_yy′).
• gamma_x1, gamma_x2, gamma_y1, gamma_y2 — Initial values of the per-mode γ functions ((A_k)_x′x′, (A_k)_y′y′). If left at the default -1, the code computes γ = (1+α²)∕β for the mode’s primary plane and γ = α²∕β for the secondary plane. This rank-2 heuristic is exact for an uncoupled initial condition; for a coupled initial condition the user should supply γ explicitly (e.g. via reference_file), since γ is then an independent quantity not determined by (β,α) alone.
• A_xy_1, A_xpy_1, A_xyp_1, A_xpyp_1, A_xy_2, A_xpy_2, A_xyp_2, A_xpyp_2 — Initial values of the four cross-plane entries of each A_k matrix, i.e. the per-mode contributions to ⟨xy⟩, ⟨x′y⟩, ⟨xy′⟩, ⟨x′y′⟩ (each per unit mode emittance). Default zero (block-diagonal A_k). Required, along with gamma_*, to fully reconstruct a coupled A_k at the start of the beamline.
• eta_x, etap_x, eta_y, etap_y — If matched is zero, the initial dispersion and dispersion slope, used as the transverse part of the dispersion 6-vector d(0) = (η_x,η_x′,η_y,η_y′,0,1)^T that is propagated through the lattice independently of the transverse mode matrices.
• reference_file — If given, the name of a previously-produced coupled_twiss_output file from which the 24 initial-condition values (beta_*, alpha_*, gamma_*, the eight A_* cross terms, and the four eta*) are loaded, overriding values supplied in the namelist. Incompatible with matched=1. The file must contain all of the standard coupled_twiss_output columns (in particular the gamma* and A_* columns, which were added so that a periodic solution can be reproduced exactly by a downstream non-periodic propagation).
• reference_element — Element in reference_file at which to take the initial values. If not given, the values from the last row of reference_file are used.
• reference_element_occurrence — Ignored if reference_element is not given. Otherwise, the occurrence number of reference_element to use. If 0, the last occurrence is used.
• reflect_reference_values — If nonzero, the loaded values of α_x,y ^(k) , η_x,y ′, and the cross-plane entries A_xpy_k, A_xyp_k are multiplied by -1 (the entries involving exactly one momentum index). This corresponds to time-reversal of the reference state and permits matching backwards from the reference point.

This feature was added to elegant using code supplied by V. Sajaev, based on Ripkin’s method. The code computes the coupled lattice functions, then uses the supplied emittance, emittance ratio, and momentum spread to compute the beam sizes, bunch length (if rf is included), and beam tilt.