twiss_output

• type: action/setup command.
• function: compute and output uncoupled Twiss parameters, or set up to do so.

&twiss_output
    STRING filename = NULL;
    long matched = 1;
    long output_at_each_step = 0;
    long output_before_tune_correction = 0;
    long final_values_only = 0;
    long statistics = 0;
    long radiation_integrals = 0;
    long concat_order = 3;
    long higher_order_chromaticity = 0;
    long higher_order_chromaticity_points = 5;
    double higher_order_chromaticity_range = 4e-4;
    double chromatic_tune_spread_half_range = 0;
    double beta_x = 1;
    double alpha_x = 0;
    double eta_x = 0;
    double etap_x = 0;
    double beta_y = 1;
    double alpha_y = 0;
    double eta_y = 0;
    double etap_y = 0;
    STRING reference_file = NULL;
    STRING reference_element = NULL;
    long reference_element_occurrence = 0;
&end

• 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.
• output_at_each_step -- A flag indicating, if set, that output is desired at each step of the simulation.
• 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.
• 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 $\delta$ over the full range higher_order_chromaticity_range.

• chromatic_tune_spread_half_range -- Half range of $\delta$ 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.

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 $\alpha = -\frac{d \beta}{2 ds}$.
• 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 0.
• pCentral0 -- The central momentum ($\beta\gamma$) 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\nu/d\delta$.
• dnux/dp2 and dnuy/dp2 -- The horizontal and vertical 2nd-order chromaticities, defined as $d^2\nu/d\delta^2$. Will be zero if higher_order_chromaticity is zero.
• dnux/dp3 and dnuy/dp3 -- The horizontal and vertical 3rd-order chromaticities, defined as $d^3\nu/d\delta^3$. Will be zero if higher_order_chromaticity is zero.
• Ax and Ay -- The horizontal and vertical acceptance. These will be zero if no apertures are defined.
• dbetax/dp and dbetay/dp -- Chromatic derivatives of the horizontal and vertical beta functions, defined as $\frac{d\beta}{d\delta}$.
• 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 $\delta$ according to $x = \eta_x\delta + \eta_{x2} \delta^2 + \eta_{x3}\delta^3$. This differs from the chromaticity expansion, which is given in terms of successive derivatives of $\nu(\delta)$.
• dnux/dAx, dnux/dAy, dnuy/dAx, dnuy/dAy -- Tune shifts with amplitude. These will be zero unless the tune_shift_with_amplitude command is given.
• alphac, alphac2 -- First- and second-order momentum compaction. The path length is $s = s_o + \alpha_c\delta + \alpha_{c2}\delta^2$.
• In -- The $n^{\rm th}$ radiation integral.
• taux, tauy, taudelta -- Radiation damping times for x, y, and $\delta$.
• Jx, Jy, Jdelta -- Damping partition factors for x, y, and $\delta$.
• 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.