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. 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.`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 and 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 , where was the local fractional momentum deviation. 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 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.`dI`*n*-- Contribution to radiation integral`I`*n*. 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 .`dnux/dp2`and`dnuy/dp2`-- The horizontal and vertical 2nd-order chromaticities, defined as . Will be zero if`higher_order_chromaticity`

is zero.`dnux/dp3`and`dnuy/dp3`-- The horizontal and vertical 3rd-order chromaticities, defined as . 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 .`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 . 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 , with or . 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 .`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.`I`*n*-- The 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.

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 |

h30000 | drives |

h10110 | drives |

h10020 | drives |

h10200 | drives |

h22000 | drives |

h11110 | drives |

h00220 | drives |

h31000 | drives |

h40000 | drives |

h20110 | drives |

h11200 | drives |

h20020 | drives |

h20200 | drives |

h00310 | drives |

h00400 | drives |