find_aperture

• type: setup/major action command.
• function: find the aperture in (x, y) space for an accelerator.

&find_aperture
    STRING output = NULL;
    STRING search_output = NULL;
    STRING boundary = NULL;
    STRING mode = "many-particle";
    double xmin = -0.1;
    double xmax =  0.1;
    double ymin =  0.0;
    double ymax =  0.1;
    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;
&end

• output -- The (incomplete) name of an SDDS file to send output to. Recommended value: ``%s.aper''.

• 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 including islands.

  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 $(x_{max}, y_{max})$. three-line mode searches this line, plus the lines from the origin to $(x_{max}, 0)$ and $(0, y_{max})$.

  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 $(x_{max}*sin(\theta), y_{max}*cos(\theta))$, where $\theta$ takes values from $-pi/2$ to $\pi/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 ``eleven-line''.

• 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. The minimum values are relevant only for many- and single-particle modes.

• 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 $\Delta x = x_{max}/n_x$ and $\Delta y = y_{max}/n_x$.
• 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 ${\rm y+sign(y)*\Delta y}$ is no larger than that at ${\rm 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 Area is defined, giving the area of the dynamic aperture for use in the penalty function. This is available only for the line search modes.