tune_shift_with_amplitude

- type: setup command.
- function: prepare for computation of tune shifts with amplitude.
- note: must be given prior to the
`twiss_output`

command. - methods:
- Method 1
- : tune shifts with amplitude are computed via tracking a series of particles at different amplitudes or by a matrix method. NAFF is used to determine the tunes from the tracking data. It is the user's responsbility to optimize the parameters to ensure that results are reasonable.
- Method 2
- : tune shifts are computed using a concatenated multi-turn third-order matrix. This appears to be reliable for many cases we've tested.
- Method 3
- : tune shifts can be computed quickly using Bengtsson's formulae [29] by
setting
`compute_driving_terms=1`

in`twiss_output`

. For cases where all methods are valid, the results will differ by a factor of 2 from the results obtained with this command. Also, the present command has more general validity because it includes dipole curvature effects.

The quantities computed are , where and are integers and is or . , with or .

&tune_shift_with_amplitude long turns = 2048; double x0 = 1e-6; double y0 = 1e-6; double x1 = 3e-4; double y1 = 3e-4; long grid_size = 6; long lines_only = 0; long sparse_grid = 0; long spread_only = 0; double nux_roi_width = 0.02; double nuy_roi_width = 0.02; double scale_down_factor = 2; double scale_up_factor = 1.05; double scale_down_limit = 0.01; double scale_up_limit = 1e-4; long scaling_iterations = 10; long use_concatenation = 0; long verbose = 0; long order = 2; STRING tune_output = NULL; &end

`turns`

-- The number of turns to track. If zero, then the concatenated matrix is used instead of tracking, and all other parameters of this command are irrelevant. The matrix method doesn't work well with all lattices. The order of the concatenated matrix is given by the`concat_order`

control in`twiss_output`

.`x0`

,`y0`

-- The initial x and y amplitudes to use for determining the small-amplitude tunes.`x1`

,`y1`

-- The initial x and y amplitudes to user for determining the tune shifts. These values should be small enough to ensure linearity in the tune shift.`grid_size`

-- Size of the grid of points in x and y.`lines_only`

-- If nonzero, then instead of a full set of`grid_size`

particles, only two lines of particles with and/or are tracked. In this case, no terms are computed (except for or ). However, in addition to being faster, the results may be more reliable, e.g., may be more closely satisfied.`sparse_grid`

-- If nonzero, then instead of a full set of`grid_size`

particles, a sparse grid of particles is tracked. Will save time at some expense in accuracy.`spread_only`

-- Compute the tune spread only and don't bother with the tune shift coefficients. These tune spreads can be optimized and appear in the twiss output file under the names`nuxTswaLower`

,`nuxTswaUpper`

, and similarly for the y plane. This is the recommended way to reduce tune shift with amplitude, as the tune spread is more reliable than the coefficients of the expansion. (Particles that get lost are automatically ignored in both types of computations.)`nux_roi_width`

,`nuy_roi_width`

-- Widths of the region of interest for x and y tunes. As the grid is filled in,`elegant`finds the tune for each tracked particle on the grid. Successive tune values are looked for in the region of the given width around the previous tune value. This prevents jumping from the main tune peak to another peak, which can happen when the tune spectrum has many lines.`scale_down_factor`

,`scale_up_factor`

,`scale_down_limit`

,`scale_up_limit`

,`scaling_iterations`

-- These control automatic scaling of the amplitudes. If`elegant`sees a tune shift larger than`scale_down_limit`

it will decrease`x0`

(or`y0`

) by the factor`scale_down_factor`

. If`elegant`sees a tune shift smaller than`scale_up_limit`

it will increase`x0`

(or`y0`

) by the factor`scale_up_factor`

. Suggestion: if you find yourself playing with these values and the initial amplitudes in order to get reliable TSWA coefficients, try just using the tune spread.`verbose`

-- If nonzero, information about the progress of the algorithm is printed to the screen.`use_concatenation`

-- If nonzero, then tracks with the concatenated matrix instead of element-by-element. The order of the concatenated matrix is given by the`concat_order`

control in`twiss_output`

. The user should experiment with this option to see if the results are reliable for a particular lattice.