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;
    long quick_higher_order_chromaticity = 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;
    long reflect_reference_values = 0;
    long cavities_are_drifts_if_matched = 1;
    long compute_driving_terms = 0;
    long leading_order_driving_terms_only = 0;
    long local_dispersion = 1;
&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. See the moments_output command if you need such computations.
• 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. 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 $\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.
• reflect_reference_values -- If nonzero, reference values of $\alpha_{x,y}$ and $\eta^\prime_{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).
• compute_driving_terms -- If nonzero, then resonance driving terms [29,36,37] 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.
• local_dispersion -- Normally, elegant will ignore acceleration in computing the dispersion. That is, the dispersion would be the ``local'' dispersion $\frac{\partial x}{\partial \delta}$, where $\delta$ was the local fractional momentum deviation. In a linac or other systems with rf elements, one might also be interested in the ``global'' dispersion $\frac{\partial x}{\partial \delta_0}$, where $\delta_0$ 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 $\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 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 ($\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.
• 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, where amplitude is defined as $A_q = (1 + \alpha_q) q^2/\beta_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[29]. 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 [29]. 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 -- First- and second-order momentum compaction. The path length is $s = s_o + \alpha_c L \delta + \alpha_{c2} L \delta^2$.
• couplingIntegral, couplingDelta, and emittanceRatio -- These quantities are defined in section 3.1.4.4 of [19]. 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^{\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.

Table 2: Meaning of the various driving terms[29].

Term Name	Explanation
h11001	drives x chromaticity
h00111	drives y chromaticity
h20001	drives synchro-betatron resonances
h00201	drives momentum-dependence of beta functions
h10002	drives second order dispersion
h21000	drives $\nu_x$
h30000	drives $3 \nu_x$
h10110	drives $\nu_x$
h10020	drives $\nu_x - 2 \nu_y$
h10200	drives $\nu_x + 2 \nu_y$
h22000	drives $d\nu_x/dJ_x$
h11110	drives $d\nu_x/dJ_y$
h00220	drives $d\nu_y/dJ_y$
h31000	drives $2 \nu_x$
h40000	drives $4 \nu_x$
h20110	drives $2 \nu_x$
h11200	drives $2 \nu_y$
h20020	drives $2 \nu_x - 2 \nu_y$
h20200	drives $2 \nu_x + 2 \nu_y$
h00310	drives $2 \nu_y$
h00400	drives $4 \nu_y$