7.25 find_aperture

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

• 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”, “n-lines”, or “grid”. 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(θ),y_max * 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 “eleven-line”.

  The grid mode simply tracks a grid of particles. The algorithm for finding the aperture contour handles the effect of stable islands (i.e., they are not considered in computing the aperture). It also allows searches for negative and positive vertical coordinates. In addition to the normal (x,y) search, grid mode allows (δ,x) and (δ,y) searches when the deltamin, deltamax, and ndelta parameters are set appropriately.

• 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, deltamin, deltamax — Region of the aperture search, in spatial coordinates. The minimum values are relevant only for many-particle. single-particle, and grid modes. The delta values are recognized only in grid mode; in that case, the user must not set both x parameters and y parameters, but only one or the other.
• 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 = x_max∕n_x and Δ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.
• ndelta — For grid mode with deltamin and deltamax not equal, gives the number of δ points.
• 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 modes.
• full_plane — If non-zero, then the search covers both positive and negative y values. Only available in line-search modes.