7.80 twiss_output

• type: action/setup command.
• function: compute and output uncoupled Twiss parameters, or set up to do so.
• sequence: must follow run_setup.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.
• N.B.: the output of this command is strictly correct only when the beamline has vanishingly small x-y coupling. For rings, use of coupled_twiss_output is an option when that requirement is not sufficiently well satisfied.

• filename — The (incomplete) name of an SDDS file to which the Twiss parameters will be written. Recommended value: “%s.twi”.
• matched — A flag indicating, if set, that the periodic or matched Twiss parameters should be found. If zero, calculations are performed in transport line mode starting from the given initial values of betax, alphax, etc. As a special case, if matched=-1 the solution is for a half periodic cell, with mirror symmetry; this will probably cause problems for higher-order calculations.

  N.B.: This may give different values for the chromaticity even if the initial values are identical to those for a periodic solution. The reason has to do with different assumptions about the initial conditions for particles in a transport line vs a ring.

• output_at_each_step — A flag indicating, if set, that 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.
• statistics — A flag indicating, if set, that minimum, maximum, and average values of Twiss parameters should be computed and included in output.
• radiation_integrals — A flag indicating, if set, that radiation integrals should be computed and included in output. N.B.: Radiation integral computation is not correct for systems with vertical bending, nor does it take into account coupling. See the moments_output command if you need such computations.

  When radiation_integrals=1 is set, the output also includes the Sokolov-Ternov[24] self-polarization time and equilibrium polarization for a planar ring, computed automatically alongside the existing radiation integrals. Expressions in the form used here are collected in the review by Mane, Shatunov, and Yokoya [25]. The new parameters are:

  • I3pos, I3neg — the sign-resolved third radiation integral, I_3,± ≡ ∫ ds∕|ρ|³ taken separately over the positive- and negative-bending regions. By construction I3pos + I3neg = I3. Dipoles bin by sign of their bend angle; wigglers, undulators and similar symmetric insertion devices contribute half to each side since their net polarizing contribution is zero.
  • tauP — Sokolov-Ternov self-polarization time τ_p in seconds, τ_p^-1 = (5∕8)r_eℏγ⁵I₃∕(m_eC), with C the ring circumference.
  • Peq — equilibrium polarization (planar-ring reduction of the Derbenev-Kondratenko formula), P_eq = (8∕(5))(I_3,+ - I_3,-)∕I₃. For a planar ring whose dipoles all curve the same way, P_eq = ±P_ST,limit, with the sign indicating the direction of polarization relative to the lattice’s bend-angle convention. Anti-bends and wigglers reduce |P_eq| below P_ST,limit.
  • PstLimit — the ideal Sokolov-Ternov polarization limit 8∕(5) ≈ 0.92376 for a uniform planar guide field.

  These quantities assume a planar ring with predominantly vertical guide field; spin-orbit depolarization from horizontal field components, resonance crossings, and beam-beam effects is not included.

• beta_X, alpha_X, eta_X, etap_X — If matched is zero, the initial values for the X plane.
• concat_order — Order of matrix concatenation to use for determining matrix for computation of Twiss parameters. Using a lower order will result in inaccuracy for nonlinear lattices with orbits and/or momentum errors. However, for on-momentum conditions with zero orbit, it is much faster to use concat_order=1.
• higher_order_chromaticity — If nonzero, requests computation of the second- and third-order chromaticity. To obtain reliable values, the user should use concat_order=3 in this namelist and the highest available order for all beamline elements. elegant computes the higher-order chromaticity by finding the trace of off-momentum matrices obtained by concantenation of the matrix for higher_order_chromaticity_points values of δ over the full range higher_order_chromaticity_range. If quick_higher_order_chromaticity is nonzero, then a quicker concatenation method is used that gives the second-order chromaticity only.
• chromatic_tune_spread_half_range — Half range of δ for which the chromatic tune spread is computed. The results are available in for optimization and in the twiss output file under the names nuxChromUpper, nuxChromLower, and similarly for the y plane. This computation uses the chromaticities.
• reference_file — If given, the name of a file from which twiss parameter data will be taken to give the starting values. Ignored if matched is nonzero. The file should have the beta and alpha functions with the same names as the file created by this command.
• reference_element — Element in reference_file at which to take the twiss parameter values. If not given, the values at the last element in reference_file are used.
• reference_element_occurrence — Ignored if reference_element is not given. Otherwise, the occurence number of reference_element to use. If 0, the last occurence is used.
• reflect_reference_values — If nonzero, reference values of α_x,y and η_x,y^′ are multiplied by -1. This permits matching backwards from the reference point.
• cavities_are_drifts_if_matched — By default, if matched=1, elegant treats rf cavities as drift spaces, allowing the user to have a cavity in the ring definition without it affecting the lattice functions. By setting cavities_are_drifts_if_matched=0, one can force elegant to use the actual matrix for the rf cavity. The differences between the results are generally small, but the default behavior disagrees with the results of moments_output. This feature is not available for cavities that change the beam energy (CHANGE_P0=1 in element definition or always_change_p0=1 on run_setup). Setting this to 0 for a ring is unusual, but allows computing the effect of energy modulation around a ring if combined with the SR_IN_ORDINARY_MATRIX=1 on CSBEND, KQUAD, and other elements.
• compute_driving_terms — If nonzero, then resonance driving terms [26, 27, 28] and tune shifts with amplitude are computed by summing over dipole, quadrupole, sextupole, and octupole elements. For dipoles, only the effects of gradients and sextupole terms are included; curvature effects are not present in the theory. In addition, these quantities may be optimized by using those names in optimization terms (see list below).
• leading_order_driving_terms_only — If nonzero, only the leading order driving terms are computed. I.e., terms involving double sums over sextupole and quadrupole strengths are not computed. However, leading-order octupole terms are computed, even though they affect the same terms as the second-order sextupole and quadrupole terms. This option is provided because computing the higher-order terms is time-consuming and not always worthwhile.
• s_dependent_driving_terms_file — The (incomplete) name of a SDDS file to which magnitude, real and imaginary parts of s-dependent driving terms will be written. If you wish to compute s-dependent driving terms, be sure to set this parameter. The following first order resonant driving terms are implemented as defined in [29]: f10010, f10100, f30000, f12000, f10200, f01200, f01110, f00300, f00120, f20100, f20010 and f11010. Please note that the notation and meaning of the driving terms differs from those computed when compute_driving_terms=1!
• local_dispersion — Normally, elegant will ignore acceleration in computing the dispersion. That is, the dispersion would be the “local” dispersion , where δ was the local fractional momentum deviation. In a linear system, the local dispersion is related to the beam moments by η_x = ⟨xδ⟩∕⟨δ²⟩. In a linac or other systems with rf elements, one might also be interested in the “global” dispersion , where δ₀ is the energy deviation at the beginning of the system. In this case, set local_dispersion=0. Alternatively, one may look at the R_i6 elements of the matrix from matrix_output.

The output file from this command contains the following columns, giving values of quantities at the exit of each element, unless otherwise noted.

• s — The arc length.
• ElementName — The name of the element.
• ElementType — The type name of the element.
• betax and betay — The horizontal and vertical beta functions.
• alphax and alphay — The horizontal and vertical alpha functions, where α = -.
• psix and psiy — The horizontal and vertical betatron phase advance in radians.
• etax and etay — The horizontal and vertical dispersion functions.
• etaxp and etayp — The slopes of the horizontal and vertical dispersion functions.
• xAperture and yAperture — The horizontal and vertical apertures. If undefined, will have a value of 10m. If the beam trajectory is non-zero, then the aperture will be changed (usually reduced) accordingly. Hence, these are best understood as the effective apertures. They are used in determining the horizontal and vertical acceptance parameters, Ax and Ay.
• pCentral0 — The central momentum (βγ) at the entrance to the element.
• dIn — Contribution to radiation integral In. Radiation integrals take account of horizontal bending only.

The output file contains the following parameters. Note that chromatic quantities depend on the order settings of the individual elements, the default order (in run_setup), and the concatenation order given in the twiss_output command. These quantities pertain to the end of the lattice or to the lattice as a whole.

• nux and nuy — The horizontal and vertical tunes.
• dnux/dp and dnuy/dp — The horizontal and vertical chromaticities, defined as dν∕dδ.
• dnux/dp2 and dnuy/dp2 — The horizontal and vertical 2nd-order chromaticities, defined as d²ν∕dδ². Will be zero if higher_order_chromaticity is zero.
• dnux/dp3 and dnuy/dp3 — The horizontal and vertical 3rd-order chromaticities, defined as d³ν∕dδ³. Will be zero if higher_order_chromaticity is zero.
• dbetax/dp and dbetay/dp — Chromatic derivatives of the horizontal and vertical beta functions, defined as .
• dalphax/dp and dalphay/dp — Chromatic derivatives of the horizontal and vertical alpha functions, defined as .
• etax2, etax3, etay2, etay3 — Higher order dispersion in the horizontal and vertical planes. For example, for the horizontal plane, the closed orbit at the end of the lattice depends on δ according to x = η_xδ + η_x2δ² + η_x3δ³. This differs from the chromaticity expansion, which is given in terms of successive derivatives of ν(δ).
• dnux/dAx, dnux/dAy, dnuy/dAx, dnuy/dAy — Tune shifts with amplitude, where amplitude is defined as A_q = (1 + α_q)q²∕β_q, with q = x or q = y. These will be zero unless the tune_shift_with_amplitude command is given.
• h11001, h00111, h20001, h00201, h10002, h21000, h30000, h10110, h10020, h10200, h22000, h11110, h00220, h31000, h40000, h20110, h11200, h20020, h20200, h00310, h00400— Resonance driving terms[26]. These will be zero unless compute_driving_terms is nonzero. See table 2 for an explanation of each term.
• dnux/dJx, dnux/dJy, and dnuy/dJy — Tune shifts with amplitude from Bengtsson’s theory [26]. Note that J_q = , where q is x or y. See documentation for tune_shift_with_amplitude for discussion and comparison with dnux/dAx etc. These will be zero unless compute_driving_terms is nonzero.
• Ax and Ay — The horizontal and vertical acceptance. These will be zero if no apertures are defined.
• alphac, alphac2, alphac3 — First-, second, and third-order momentum compaction. The path length is s = s_o + α_cLδ + α_c2Lδ² + α_c3Lδ². Regarding α_c3, users are cautioned that the analytical matrices for most elements are limited to second-order, so using tracking-derivce matrices is necessary where supported, and gives limited accuracy.
• couplingIntegral, couplingDelta, and emittanceRatio — These quantities are defined in section 3.1.4.4 of [21]. The computations include tilted quadrupoles, vertical orbit in sextupoles, vertical sextupole displacement, and solenoids. Note that the emittance ratio does not include the effect of vertical dispersion.
• In — The n^th radiation integral.
• taux, tauy, taudelta — Radiation damping times for x, y, and δ.
• Jx, Jy, Jdelta — Damping partition factors for x, y, and δ.
• ex0, enx0 — Horizontal equilibrium geometric and normalized emittances.
• Sdelta0 — Equilibrium fractional rms energy spread.
• U0 — Energy loss per turn.

N.B.: the higher-order dispersion and higher-order chromaticity are computed using the concatenated third-order matrix. However, elegant only has third-order matrices for three elements: alpha magnets, quadrupoles, and sextupoles. This may be acceptable if any dipoles (for example) have large bending radius. Users who are concerned about these effects should perform off-energy tracking using canonical elements (i.e., CSBEND, KQUAD, KSEXT, and MULT), which include energy dependence to all orders.

Also, note that by default all elements are computed to second order only. You must change the default\_order parameter on run\_setup to 3 in order to use the third-order matrices for alpha magnets, quadrupoles, and sextupoles. You may also use the ORDER parameter on individual element definitions.