momentum_aperture

- type: major action command.
- function: determine momentum aperture as a function of position in the lattice by tracking

&momentum_aperture STRING output = NULL; double x_initial = 0; double y_initial = 0; double delta_negative_start = 0.0; double delta_positive_start = 0.0; double delta_negative_limit = -0.10; double delta_positive_limit = 0.10; double delta_step_size = 0.01; long steps_back = 1; long splits = 2; long split_step_divisor = 10; long skip_elements = 0; long process_elements = 2147483647; double s_start = 0; double s_end = DBL_MAX; STRING include_name_pattern = NULL; STRING include_type_pattern = NULL; long fiducialize = 0; long verbosity = 1; long soft_failure = 0; long output_mode = 0; long forbid_resonance_crossing = 0; &end

`output`

-- The (incomplete) name of a file to which the momentum aperture results will be written. Recommended value: ``%s.mmap''.`x_initial`

,`y_initial`

-- The initial x and y coordinate values for tracking. It is essential that`y_initial`

be nonzero if one wants to see losses due to vertical resonances.`delta_negative_start`

,`delta_positive_start`

-- Starting values of scans in the negative and positive directions.`delta_negative_limit`

,`delta_positive_limit`

-- Limiting values of scans in the negative and positive directions.`delta_step_size`

-- Initial size of steps in . This should be fairly large in order to save time.`steps_back`

-- Number of steps to back up after a particle is lost, relative to the last surviving , before continuing with a smaller step size. If this is set to zero, there is a risk of finding a too-large momentum aperture (a stable island).`splits`

-- Number of times to split the step size in order to refine the location of the maximum surviving momentum offsets. When a particle is lost, the algorithm steps back to a momentum offset where a particle survived, subdivides the step size, and continues searching.`split_step_divisor`

-- Factor by which to subdivide the step size for each split.`skip_elements`

-- Number of elements to skip before starting to compute momentum apertures.`process_elements`

-- Number of elements for which to compute momentum aperture.`s_start`

,`s_end`

-- Limiting s coordinates of the elements from which tracking will start. The default values will exclude no elements.`include_name_pattern`

-- If given, tracking will start only at the entrance to elements that match the given wildcard pattern.`include_type_pattern`

-- If given, tracking will start only at the entrance to elements whose type matches the given wildcard pattern.`fiducialize`

-- If given, an initially on-energy particle is tracked before the momentum aperture search begins, in order to fiducialize the reference momentum. This is useful if there are synchrotron radiation losses or energy gain due to cavities in the system.`verbosity`

-- Larger values result in more detailed printouts as calculations proceed. Mostly for debugging.`soft_failure`

-- Normally, if`elegant`fails to find the momentum aperture, it aborts. If`soft_failure`

is non-zero, it instead assigns a momentum aperture equal to the search limit.`output_mode`

-- Normally,`elegant`puts the values for positive and negative momentum aperture in different columns. Each element thus has a single row of data in the output file. If`output_mode=1`

,`elegant`instead puts the values for positive and negative apertures in successive rows, with a reduced number of columns. This is mostly advantageous for the parallel version, since it allows using twice as many simultaneous processors. If`output_mode=2`

,`elegant`tracks many more probe particles simultaneously, which is better for massively parallel systems. The number of particles tracked is the number of elements selected times the number of probe points between`delta_negative_limit`

and`delta_positive_limit`

.`forbid_resonance_crossing`

-- Normally,`elegant`allows the momentum aperture search to cross integer and half-integer resonances if no unstable particles are found. If this is undesirable, this flag can be set to 1.

The idea for this command is from M. Belgroune *et al.*, ``Refined
Tracking Procedure for the SOLEIL Energy Acceptance Calculation,''
Proceedings of PAC 2003, p 896, as implemented for TRACYII. In
particular, the energy aperture as a function of position around the
ring is determined by tracking. Starting at the beginning of the
lattice and working downstream, particles are tracked starting from
the exit of each selected element. The betatron coordinates are
initially zero (or very small), while the momentum deviation is
gradually increased until loss of the particle is observed. This
defines the momentum aperture at that location.

In `elegant` version 19.0 and later, the algorithm is as follows. For simplicity in
wording, we'll assume the momentum deviations are positive values,
although the method is applied separately for negative values as well:

- Start with , i.e., zero momentum offset.
- Track a particle to see if it gets lost. If so, proceed to step 4.
- Increase by step size and return to step 2.
- If no splitting steps remain, proceed to the next step. Otherwise:
- Change to
., where is
the largest for which the particle survived, and is the
`steps_back`

parameter. - Divide the step size by
`split_step_divisor`

to get a new step size . - Set .
- Decrement the ``splits remaining'' counter by 1.
- Continue from step 2.

- Change to
., where is
the largest for which the particle survived, and is the
- Stop. The momentum aperture is

This command can be used for both rings and transport lines. For
rings it is most appropriate to have an rf cavity (i.e., an `RFCA`
element) in the lattice. One should also include radiation loss using
either of two methods:

`SREFFECTS`element, with`QEXCITATION=0`. To set up this element more easily, one can include a`twiss_output`

command with`radiation_integrals=1`

.- Use
`CSBEND`and`KQUAD`elements with`SYNCH_RAD=1`

and`ISR=0`

.