APERTURE AND TOLERANCES

EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH

Defining aperture in MAD-X

The aperture for a particular element or class of elements can be set in MAD-X at the time of definition or instantiation of the element or class.
During tracking the particle excursion is then checked against the defined aperture and the particle is lost if it is outside the defined aperture.
The aperture can be specified for any element or class of elements, with the exception of drift spaces.
The definition of the aperture takes the following form and parameters:

..., APERTYPE=string, APERTURE={values}
APERTYPE defines the aperture type from a set of seven preselected types:
CIRCLE, RECTANGLE, ELLIPSE,
RECTCIRCLE, a superposition of an CIRCLE and a RECTANGLE,
LHCSCREEN, an alias for RECTCIRCLE, RECTELLIPSE, a superposition of an ELLIPSE and a RECTANGLE,
and RACETRACK.
Note that the MARGUERITE aperture type (two RECTCIRCLEs crossing at right angle) is no longer supported.

APERTURE is an array of values, the number and meaning of which depends on the APERTYPE:

APERTYPE # of values meaning of values

CIRCLE 1 radius of circle

ELLIPSE 2 horizontal and vertical semi-axes of ellipse

RECTANGLE 2 half width and half height of rectangle

RECTCIRCLE 3 half width and half height of rectangle, radius of circle

LHCSCREEN 3 half width and half height of rectangle, radius of circle

RECTELLIPSE 4 half width and half height of rectangle, horizontal and vertical semi-axes of ellipse

RACETRACK 3 horizontal and vertical offsets (g and s) of the circle center, radius (r) of the circular part (see figure below)

filename 0 where the file contains a list of x and y coordinates outlining the shape. This option is only supported by the aperture module, see below.

APERTYPE	# of values	meaning of values
CIRCLE	1	radius of circle
ELLIPSE	2	horizontal and vertical semi-axes of ellipse
RECTANGLE	2	half width and half height of rectangle
RECTCIRCLE	3	half width and half height of rectangle, radius of circle
LHCSCREEN	3	half width and half height of rectangle, radius of circle
RECTELLIPSE	4	half width and half height of rectangle, horizontal and vertical semi-axes of ellipse
RACETRACK	3	horizontal and vertical offsets (g and s) of the circle center, radius (r) of the circular part (see figure below)
filename	0	where the file contains a list of x and y coordinates outlining the shape. This option is only supported by the aperture module, see below.

Examples:

The following sets an ELLIPTICAL aperture for the main dipoles for the LHC.

MB: SBEND, L=l.MB, APERTYPE=ELLIPSE, APERTURE={0.02202,0.02202};

When the aperture is specified in a specific file the only aperture parameter is the filename:

MB: SBEND, L=l.MB, APERTYPE=myfile;

where "myfile" contains the list of x-y coordinates defining the aperture shape:

x0   y0
xi   yi
...
xn   yn

Notes:

There are inconsistencies in the parameter definition for the different aperture types. This is historical and is kept for backwards compatibility. Pay some attention to the parameters you introduce!
When MAKETHIN is called all thin slices inherit the aperture of their respective original thick lens version.
When the SIXTRACK command is called (see the SixTrack converter module C6T) the apertures are ignored by default. To convert the apertures as well the APERTURE flag has to be set in C6T.
Aperture parameters are like all parameters and are inherited by derived elements. Like other parameters they can also be overridden by the derived elements if necessary.

The APERTYPE and the APERTUREs themselves can be conveniently added to the TWISS table (see Twiss Module) by using the SELECT command. For example the command:

select,flag=twiss,clear;
select,flag=twiss,column=name,s,betx,alfx,mux,bety,alfy,muy,apertype,aper_1,aper_2;

and a subsequent TWISS command will put the aperture information together with the specified TWISS parameters into the TWISS table.

Defining tolerances in MAD-X

A parameter closely connected to the aperture is the sum of the mechanical and alignment tolerances. The mechanical tolerance is the maximal error margin of errors in the element body which causes a decrease of aperture, and the alignment tolerance is a mislignment of the element in the accelerator, which also causes a decrease of aperture. The tolerance is given in the transverse plane as a racetrack, like in the picture below.

A tolerance can be assigned to each element in a MAD-X sequence as a vector:

Syntax: APER_TOL = {r, g, s};

MB : SBEND, L := l.MB, APER_TOL={1.5, 1.1, 0};

APERTURE MODULE

The APERTURE module was developped specifically for the LHC. Default parameter values are LHC values and the physics in APERTURE assumes ultra-relativistic particles.

The APERTURE module computes the n1 values for a piece of machine. Each element is sliced into thick subelements at given intervals, and the available aperture is computed at the end of each slice. The computation is based on the last Twiss table, so it is important to run the Twiss and aperture commands on the same period or sequence, see the aperture example below. Also showed in the example is how n1 values can be plotted.

The minimum n1 for each element is written to the last Twiss table, to allow for matching by aperture.

APERTURE, RANGE=range,
          EXN=real, EYN=real, DQF=real, DPARX=real, DPARY=real, 
          BETAQFX=real, BBEAT=real, DP=real, 
          COR=real,  NCO=integer, 
          HALO={real,real,real,real}, HALOFILE=filename,
          INTERVAL=real, SPEC=real, NOTSIMPLE=logical, 
          TRUEPROFILE=filename, OFFSETELEM=filename, 
          FILE=filename;

where the parameters have the following meaning:

RANGE: Range given by elements. Default = #s/#e
EXN: Normalised horizontal emittance. Default = 3.75*e-6
EYN: Normalised vertical emittance. Default = 3.75*e-6
DQF: Peak linear dispersion [m]. Default = 2.086
DPARX: Fractional horizontal parasitic dispersion. Default = 0.273
DPARY: Fractional vertical parasitic dispersion. Default = 0.273
BETAQFX: Beta x in standard qf [m]. Default = 170.25
BBEAT: Beta beating coefficient applying to beam size. Default = 1.1
DP: Bucket edge at the current beam energy. Default = 0.0015
COR: Maximum radial closed orbit uncertainty [m]. Default = 0.004
NCO: Number of azimuth for radial scan. Default = 5
HALO: Halo parameters: {n, r, h, v}. n is the radius of the primary halo, r is the radial part of the secondary halo, h and v is the horizontal and vertical cuts in the secondary halo. Default = {6, 8.4, 7.3, 7.3}
HALOFILE: Input file with halo polygon coordinates. Will suppress an eventual halo parameter. Default = none
INTERVAL: Approximate length in meters between measurements. Actual value: nslice = nodelength/interval, nslice is rounded down to closest integer, interval = nodelength/nslice. Default = 1.0
SPEC: Aperture spec, for plotting only. Gives the spec line in the plot. Default = 0.0
NOTSIMPLE: Use only if one or more beamscreens in the range are considered not to be a "simply connex". Since all MAD-X apertypes are simply connex, this is only possible if an input file with beam screen coordinates are given. See below for a graphical example. Default = false.
TRUEPROFILE: A file containing a list of magnets, and for each magnet a list of horizontal and vertical deviations from the ideal magnet axis. These values may come from measurements done on the magnet. See below for example. Default = none.
OFFSETELEM: A file containing a reference point in the machine, and a list of magnets with their offsets from this point described as a parabola. See below for example. Default = none.
Note that the reference point should be within the range of elements given for the offsets to be taken into account.
FILE: Output file with aperture table. Default = none

Important note regarding emittances:
The APERTURE module sets the actual emittance from the normalized values given as input using
ex = exn / gamma,
while the BEAM command in MAD-X uses the definition
ex = exn / (4 * beta * gamma)

Not simply connex beam pipes

Methodically, the algorithm for finding the largest possible halo is fairly simple. The distance from halo centre to the first apex (i = 0) in the halo is calculated (l_i), and the equation for a line going through these points is derived. This line is then compared with all lines making the pipe polygon to find their respective intersection coordinates. The distance h_i between halo centre and intersection are then divided by l_i, to find the maximal ratio of enlargement, as seen below. This procedure is then repeated for all apexes i in the halo polygon, and the smallest ratio of all apexes is the maximal enlargement ratio for this halo to just touch the pipe at this particular longitudinal position.

There is one complication to this solution; polygons which are not simple connexes. (Geometrical definition of ``simply connex'': A figure in which any two points can be connected by a line segment, with all points on the segment inside the figure.) The figure below shows what happens when a beam pipe polygon is not a simple connex. The halo is expanded in such a way that it overlaps the external polygon in the area where the latter is dented inwards.

To make the module able to treat all kinds of polygons, notsimple must be activated. With this option activated, apexes are strategically added to the halo polygon wherever the beam pipe polygon might have an inward dent. This is done by drawing a line from halo centre to each apex on the pipe polygon. An apex with its coordinates on the intersection point line-halo is added to a table of halo polygon apexes. The result is that the halo polygon has a few ``excessive'' points on straight sections, but the algorithm used for expansion will now never miss a dent in the beam pipe. The use of the notsimple option significantly increases computation time.

Trueprofile file syntax

This file contains magnet names, and their associated displacements of the axis for an arbitrary number of S, where So is the start of the magnet and Sn the end. The interval between each S must be regular, and X and Y must be given in meters. The magnet name must be identical to how it appears in the sequence. The displacements are only valid for this particular magnet, and cannot be assigned to a family of magnets. n1 is calculated for a number of slices determinated by the number of Si.

Layout of file:

magnet.name1
So   X   Y
Si   X   Y
Si   X   Y
Sn   X   Y

magnet.name2
So   X   Y
Si   X   Y
Si   X   Y
Sn   X   Y

...

Example of file:

!This is the start of the file.
!Comments are made with exclamation marks.

mb.a14r1.b1
0        0.0002        0.000004
7.15     1.4e-5        0.3e-3
14.3     0.0000000032  4e-6

!further comments can of course be added

mq.22r1.b1
0      0.3e-5     1.332e-4
1.033  0.00034    0.3e-9
2.066  0          0.00e-2
3.1    4.232e-4   0.00000003

!This is the end of the file.

OFFSETELEM file syntax

This file contains parameters describing how certain elements are actually located in space with respect to a given reference element in the machine.
The basis for this file is a pair of coordinate systems, {s,x} and {s,y} with the origin at the reference point. The units for s, x and y are meters.
The actual location of the magnetic axis of a given element can be described, in each plane, as a parabola defined with three coefficients:

X_act(s) = DDX_OFF * s^2  +  DX_OFF * s  +  X_OFF

and

Y_act(s) = DDY_OFF * s^2  +  DY_OFF * s  +  Y_OFF

The reference position for the element, X_ref(s) and Y_ref(s), is calculated by MAD-X via an internal call to the SURVEY module, taking the reference element as the origin.

The resulting offset, in each plane, which is taken into account in the aperture calculation, is the difference between reference position and actual position:

X_offset(s) = X_ref(s) - X_act(s)

and

Y_offset(s) = Y_ref(s) - Y_act(s)

The offsets are only calculated for elements for which actual positions have been given through the OFFSETELEM file mechanism.

The file must be given in TFS format according to the following template, with mandatory header and any number of data lines, one per element.

@ NAME             %06s "OFFSET" 
@ TYPE             %06s "OFFSET" 
@ REFERENCE        %10s "reference-element-name" 
* NAME          S_IP       X_OFF     DX_OFF    DDX_OFF    Y_OFF    DY_OFF     DDY_OFF
$ %s            %le        %le       %le       %le        %le      %le        %le
"elementname"	real       real      real      real       real     real       real

Note that the column S_IP is actually not used, and the values are ignored, but the column and values are parsed nevertheless and must be present. The absence of this column will trigger an error.

Example:

@ NAME             %06s "OFFSET" 
@ TYPE             %06s "OFFSET" 
@ REFERENCE        %10s "mq.12r1.b1" 
* NAME          S_IP       X_OFF     DX_OFF    DDX_OFF    Y_OFF    DY_OFF     DDY_OFF
$ %s            %le        %le       %le       %le        %le      %le        %le
"mq.12r1.b1"	0.0        -3.0      -2.56545   0.0       0.0      -2.3443666 0.0
"mcbxa.3r2"     0.0        -0.84     32.443355  0.3323    0.0      32.554363  0.2522

As an example we see in the picture below how the horizontal axes of elements m1 and m2 does not coincide with the reference trajectory.

Note that prior to MAD-X version 4, the layout of the file was different and not formatted as TFS file:

reference-element-name

elementname
DDX_OFF   DX_OFF   X_OFF
DDY_OFF   DY_OFF   Y_OFF

Example:

!comment can be given anywhere with an exclamation mark

mq.12r1.b1

!Then we give a list of elements and their displacement 
!w.r.t. the reference point.
mcbxa.3l2
0   -2.56545   -3
0   -2.3443666  0

!The next element use the same reference point.
!Elements offset w.r.t. another point must be given in another file,
!together with the new reference point.
mcbxa.3r2
0.3323  32.443355 -0.84
0.2522  32.554363 0.0

!This is the end of the file.

Aperture command example

The aperture module needs a Twiss table to operate on. It is important not to USE another period or sequence between the Twiss and aperture module calls, else aperture looses its table. One can choose the ranges for Twiss and aperture freely, they need not be the same.

Use, period=lhcb1;
Select, flag=twiss, range=mb.a14r1.b1/mb.a17r1.b1, column=keyword,name,parent,k0l,k1l,s,betx,bety,n1;
Twiss, file=twiss.b1.data, betx=beta.ip1, bety=beta.ip1, x=+x.ip1, y=+y.ip1, py=+py.ip1;
Plot, haxis=s, vaxis=betx,bety, colour=100;

Select, flag=aperture, column=name,n1,x,dy;
Aperture, range=mb.b14r1.b1/mb.a17r1.b1, spec=5.235;
Plot, table=aperture, noline,vmin=0, vmax=10, haxis=s, vaxis=n1, spec, on_elem, style=100;

The select command can be used to choose which columns to print in the output file.
Column names: name, n1, n1x_m, n1y_m, apertype, aper_1, aper_2, aper_3, aper_4, rtol, xtol, ytol, s, betx, bety, dx, dy, x, y, on_ap, on_elem, spec

n1 is the maximum beam size in sigma, while n1x_m and n1y_m is the n1 values in SI units in the x- and y-direction.

Note that specifying the apertype column automatically selects also the aper_1, aper_2, aper_3 and aper_4 columns.
The statement
Select, flag=aperture, column=apertype;
is equivalent to
Select, flag=aperture, column=apertype, aper_1, aper_2, aper_3, aper_4;

aper_# means for all apertypes but racetrack:
aper_1 = half width rectangle
aper_2 = half heigth rectangle
aper_3 = horizontal semi-axis ellipse (or radius if circle)
aper_4 = vertical semi-axis ellipse

For racetrack, the aperture parameters will have the same meaning as the tolerances:
aper_1 and xtol = horizontal displacement of radial part
aper_2 and ytol = vertical displacement of radial part
aper_3 and rtol = radius
aper_4 = not used

On_elem indicates whether the node is an element or a drift, and on_ap whether it has a valid aperture. The Twiss parameters are the interpolated values used for aperture computation.

When one wants to plot the aperture, the table=aperture parameter is necessary. The normal line of hardware symbols along the top is not compatible with the aperture table, so it is best to include noline. Plot instead the column on_elem along the vaxis to have a simple picture of the hardware. Spec can be used for giving a limit value for n1, to have something to compare with on the plot. This example provides a plot,

where we see the n1, beta functions and the hardware symbolized by on_elem.

Ivar Waarum, 24.02.05 - Mark Hayes, 19.06.02 - Ghislain Roy, June 2014