- type: setup/major action command.
- function: find the aperture in (x, y) space for an accelerator.
- N.B.: can use parallel resources (Pelegant). Recommend using n-line mode with nx*n_splits
greater than the number of cores (e.g., a factor of 10).
- Command syntax, including use of equations and subcommands, is discussed in 7.2.
STRING output = NULL;
STRING search_output = NULL;
STRING boundary = NULL;
STRING mode = "many-particle";
double xmin = -0.1;
double xmax = 0.1;
double xpmin = 0.0;
double xpmax = 0.0;
double ymin = 0.0;
double ymax = 0.1;
double ypmin = 0.0;
double ypmax = 0.0;
long nx = 21;
long ny = 11;
long n_splits = 0;
double split_fraction = 0.5;
double desired_resolution = 0.01;
long assume_nonincreasing = 0;
long verbosity = 0;
long offset_by_orbit = 0;
long n_lines = 11;
long optimization_mode = 0;
long full_plane = 0;
- output — The (incomplete) name of an SDDS file to send output to. Recommended value:
- mode — May be “many-particle”, “single-particle”, “one-line, “three-lines”, or “n-lines”.
Many-particle searching is much faster than single-particle, but does not allow interval
splitting to search for the aperture boundary. Both “many-particle” and “single-particle”
modes involve searching from the outside inward, which improves speed but may result in
The line modes avoid this by searching form the origin outward. Of these, the one-line and
three-line modes are special: one-line mode searches the line from the origin to (xmax,ymax).
three-line mode searches this line, plus the lines from the origin to (xmax,0) and (0,ymax).
For n-line mode, the number of lines is set with the n_lines parameter. With n > 3, n lines
are explored from (0,0) to (xmax * sin(θ),ymax * cos(θ)), where θ takes values from -pi∕2 to
π∕2. In these modes, the output file contains a parameter called “Area,” which gives the area
of the dynamic aperture.
Also still recognized are other modes, namely, “five-line”, “seven-line”, “nine-line”, and
- search_output — The (incomplete) name of an SDDS file for output of detailed information
on each tracked particle (single-particle mode only). Recommended value: “%s.apso”.
- boundary — The (incomplete) name of an SDDS file for the boundary points of the aperture
search. Recommended value: “%s.bnd”. Valid for many- and single-particle modes.
- xmin, xmax, ymin, ymax — Region of the aperture search, in spatial coordinates. The minimum
values are relevant only for many- and single-particle modes.
- xpmin, xpmax, ypmin, ypmax — Region of the aperture search, in slope coordinates. The
minimum values are relevant only for many- and single-particle modes. Ignored unless
xmin=xmax and ymin=ymax.
- nx — For many- and single-particle modes, the number of x values to take in initial search.
For line modes, this determines the initial x and y step sizes via Δx = xmax∕nx and
Δy = ymax∕nx.
- ny — For many- and single-particle modes, the number of y values to take in search. Ignored
for line modes.
- n_splits — If positive, the number of times to do interval splitting. Interval splitting refers
to searching between the original grid points in order to refine the results. This is done only
for single-particle and line modes.
- split_fraction — If interval splitting is done, how the interval is split.
- desired_resolution — If interval splitting is done, fraction of xmax-xmin to which to resolve
the aperture. Ignored for all but single-particle mode.
- assume_nonincreasing — If this variable is non-zero, the search assumes that the aperture
at y + sign(y) * Δy is no larger than that at y. This results in tracking of fewer particles but
may give a pessimistic result. Used only for single- and multi-particle modes.
- offset_by_orbit — A flag indicating whether to offset the transverse beam coordinates by
the closed orbit before tracking. The default value is zero for backward compatibility, but the
recommended value is 1.
- verbosity — A larger value results in more printouts during computations.
- n_lines — In “n-lines” mode, the number of lines to search.
- optimization_mode — If non-zero, then find_aperture is a setup command and can be
used with elegant’s internal optimizer. The quantity DaArea is defined, giving the area of
the dynamic aperture for use in the penalty function. This is available only for the line search
- full_plane — If non-zero, then the search covers both positive and negative y values. Only
available in line-search modes.