7.69 tune_footprint

• type: action/setup command.
• function: compute frequency map from tracking and use it to determine the chromatic and amplitude tune footprints.
• sequence: must follow run_control.
• can use parallel resources (Pelegant)
• N.B.: the number of turns tracked is set by the run_control command.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• delta_output — The optional (incomplete) name of an SDDS file to send tune and diffusion rate vs δ output to. Recommended value: “%s.dtf”. If optimization is done, this file is written only at the end of optimization.
• xy_output — The optional (incomplete) name of an SDDS file to send tune and diffusion rate vs (x, y) output to. Recommended value: “%s.atf”. If optimization is done, this file is written only at the end of optimization.
• xmin, xmax — Limits of grid of initial x coordinates for tracking.
• ymin, ymax — Limits of grid of initial y coordinates for tracking. ymin should typically be a small, positive value so that there is some betatron oscillation from which to get the tune.
• delta_min, delta_max — Limits of grid of initial δ coordinates for tracking. Not that particles are not centered around the dispersive closed orbit.
• ndelta — Number of values of δ coordinate in the grid. If zero, chromatic footprint is not determined.
• separate_xy_for_delta — If nonzero, tracking for the x and y momentum-dependent tunes will be done separately, so that when x-plane tracking is performed, y = 0 initially. This might be helpful if nonlinear coupling of y motion into the x plane causes the x tune to be poorly determined for small x amplitudes. Increase the tracking time by a factor of two.
• nx — Number of values of x coordinate in the grid. If zero, amplitude footprint is not determined.
• ny — Number of values of y coordinate in the grid. If zero, amplitude footprint is not determined.
• verbosity — If nonzero, prints possibly useful information while running.
• quadratic_spacing — If nonzero, points are spaced “quadratically,” which actually means that their squares are spaced linearly. It is highly recommended to keep this turned on, since otherwise problems determining the tune when x ≈ 0 may result in invalid results.
• compute_diffusion — If nonzero, diffusion is computed, which requires tracking twice as many turns.
• diffusion_rate_limit — Value of the diffusion rate d_r above which the particle is considered unstable, where

  (13)

  where N is the number of turns tracked to determine each tune (equal to half of n_passes).

• immediate — If nonzero, the calculations take place immediately. If zero, then two modes are possible
  • If you wish to compute parameters on a closed orbit or after other calculations, be sure to set this control to zero and ask for an output file with xy_output or delta_output.
  • If you want to use this command to create quantities for optimization (see below), be sure to set this control to zero and do not ask for an output file with xy_output or delta_output.
• filtered_output — If nonzero, output is only provided for particles inside the stable footprint.
• ignore_half_integer — If nonzero, half-integer resonances are ignored in determining the tune footprint.
• chromaticity_fit_order — Order of polynomial fits used to obtain chromaticities.

This command makes available the following quantities for optimization. All quantities are limited by particle survival, crossing of integer and half-integer resonances, and the diffusion rate limit.

• FP.nuxSpreadChrom,FP.nuySpreadChrom — Spread in tunes due to chromaticity.
• FP.nuxChromMin, FP.nuxChromMax, FP.nuyChromMin, FP.nuyChromMax — Minimum and maximum values of the x and y tunes from chromatic tune footprint.
• FP.deltaLimit — Minimum of absolute values of positive and negative δ limits.
• FP.nuxSpreadAmp, FP.nuySpreadAmp — Spread in tunes due to amplitude.
• FP.nuxAmpMin, FP.nuxAmpMax, FP.nuyAmpMin, FP.nuyAmpMax — Minimum and maximum values of the x and y tunes from amplitude tune footprint.
• FP.xSpread, FP.ySpread — Spread in x and y values.
• FP.xyArea — Area of the limited x-y region, comparable to a dynamic acceptance. However, this area is determined from a fixed grid and is not suitabl to optimization by itself.
• FP.diffusionRateMaxChrom, FP.diffusionRateMaxAmp — Maximum diffusion rates in chromatic and amplitude scans.
• FP.chromx1, FP.chromy1 — Linear chromaticities from fits to data.

Typically, one strives to minimize FP.nuxSpreadChrom,FP.nuySpreadChrom, FP.nuxSpreadAmp, FP.nuySpreadAmp, FP.diffusionRateMaxChrom, and/or FP.diffusionRateMaxAmp while maximizing FP.deltaLimit, FP.xSpread, and/or FP.ySpread, and ensuring that FP.xyArea, at minimum, doesn’t decrease. I.e., one wants the maximum stable region for momentum and position deviations with the minimum spread in tunes and minimum diffusion.