Aperture

Aperture checks identify and record losses from transverse particle positions. Apertures are configured as element attributes, with dimensions in metres. Ordinary elements default to disabled aperture checks; the default SpaceCharge aperture follows its field grid, as described in Space-Charge Effect (SpaceCharge). CPU and NVIDIA GPU support the same aperture settings.

Interface Parameters

The aperture system is controlled by two parameters:

Property	JSON key	Type	Description
`aperture_type`	`Aperture type`	str	Aperture type, case-insensitive; available values are listed below
`aperture_value`	`Aperture value`	list	Aperture parameter values; meaning varies by type

Note

aperture_type is case-insensitive and is internally converted to lowercase before matching. The off and default types ignore aperture_value .

Parameter Summary Table

Type	aperture_value	Description
`off`	ignored	No aperture checking
`default`	ignored	Ordinary elements: ±1 m rectangle; SpaceCharge: configuration grid rectangle
`circle`	`[r]`	Circular, \(r\) is the radius
`rectangle`	`[w, h]`	Rectangular, \(w\) is the half-width, \(h\) is the half-height
`ellipse`	`[a, b]`	Elliptical, \(a\) is the horizontal semi-axis, \(b\) is the vertical semi-axis
`rectcircle`	`[w, h, r]`	Intersection of rectangle and circle
`rectellipse`	`[w, h, a, b]`	Intersection of rectangle and ellipse
`racetrack`	`[w, h, a, b]`	Racetrack (rectangle + elliptical ends)
`octagon`	`[w, h, d]`	Octagonal (rectangle with 45° chamfers)
`polygon`	`[[x1,y1], ...]`	Polygon vertex list, automatically closed

Usage Example

The following JSON snippets show the configuration of each aperture type. Aperture parameters are element properties, placed alongside fields such as S (m) , Command , Length (m) , etc.:

Circular aperture :

"Drift1": {
    "S (m)": 10.0,
    "Command": "Drift",
    "Length (m)": 0.5,
    "Aperture type": "circle",
    "Aperture value": [0.1]
}

Rectangular aperture :

"Drift2": {
    "S (m)": 10.5,
    "Command": "Drift",
    "Length (m)": 0.3,
    "Aperture type": "rectangle",
    "Aperture value": [0.06, 0.04]
}

Elliptical aperture :

"Drift3": {
    "S (m)": 11.0,
    "Command": "Drift",
    "Length (m)": 0.2,
    "Aperture type": "ellipse",
    "Aperture value": [0.06, 0.04]
}

Racetrack aperture :

"Drift4": {
    "S (m)": 11.5,
    "Command": "Drift",
    "Length (m)": 0.4,
    "Aperture type": "racetrack",
    "Aperture value": [0.03, 0.05, 0.02, 0.05]
}

Octagonal aperture :

"Drift5": {
    "S (m)": 12.0,
    "Command": "Drift",
    "Length (m)": 0.3,
    "Aperture type": "octagon",
    "Aperture value": [0.05, 0.03, 0.01]
}

Polygon aperture :

"Drift6": {
    "S (m)": 12.5,
    "Command": "Drift",
    "Length (m)": 0.2,
    "Aperture type": "polygon",
    "Aperture value": [[0.05, 0.0], [0.025, 0.043], [-0.025, 0.043], [-0.05, 0.0], [-0.025, -0.043], [0.025, -0.043]]
}

Disable aperture checking :

"Drift7": {
    "S (m)": 13.0,
    "Command": "Drift",
    "Length (m)": 0.5,
    "Aperture type": "off"
}

Lost Particle Handling

Only strict aperture interiors survive on both CPU and GPU. Particles touching any physical wall are lost, including polygon edges and vertices; rectangular loss does not require both coordinates to reach their limits.

When a particle is determined to be lost, the system performs the following operations:

tag negation : \(\text{tag} \leftarrow -|\text{tag}|\) , preserving the particle ID information and only negating the sign to mark it as lost
lost_position : records the longitudinal coordinate \(s\) of the first check that detects the loss, such as an internal SC node or the element exit; this is not an interpolated wall-intersection position
lost_turn : records the turn number at the time of loss

Particles already lost ( \(\text{tag} < 0\) ) are skipped in subsequent aperture checks and are not marked again. Aperture checking is performed only on surviving particles ( \(\text{tag} > 0\) ).

Check locations and limitations

For each bunch passage through an ordinary element, including Bump, an enabled aperture is checked once at the exit if no internal space charge is active. With \(K\) active internal SC nodes, it is checked once before each SC source evaluation and once at the exit, for \(K+1\) checks. Other external integration slice boundaries do not add checks. An independent SpaceCharge command checks at its own position. Setting the aperture to off disables these aperture losses; PIC field-domain validation and transport momentum-validity checks remain independent. ElSeparator retains its separate first-contact collision checks along particle trajectories; see ElSeparator.

Ordinary aperture checks sample discrete positions. A particle that leaves and re-enters the aperture between these positions can escape detection; increasing only the external slice count does not automatically add aperture checks.

Detailed Aperture types

The following describes the parameter definitions and loss conditions for each of the 10 aperture types.

off (Disabled)

Parameters : none ( aperture_value is ignored)

Description : No aperture checking is performed; all particles are retained.

default (Default Rectangle)

Parameters : none ( aperture_value is ignored)

Description : Ordinary elements use the default ±1m rectangle, equivalent to aperture_value = [1.0, 1.0]. SpaceCharge instead resolves default to the rectangle defined by its configuration’s grid extent; see Space-Charge Effect (SpaceCharge).

Loss condition :

\[|x| \ge 1.0 \quad \text{or} \quad |y| \ge 1.0\]

circle (Circular)

Parameters : aperture_value = [r] , where \(r\) is the circle radius.

Loss condition :

\[x^2 + y^2 \ge r^2\]

rectangle (Rectangular)

Parameters : aperture_value = [w, h] , where \(w\) is the half-width and \(h\) is the half-height.

Loss condition (particle is lost if either condition is met):

\[|x| \ge w\]

\[|y| \ge h\]

ellipse (Elliptical)

Parameters : aperture_value = [a, b] , where \(a\) is the horizontal semi-axis (x direction) and \(b\) is the vertical semi-axis (y direction).

Loss condition :

\[\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 \ge 1\]

rectcircle (Rectangle Inscribed Circle)

Parameters : aperture_value = [w, h, r] , where \(w\) is the rectangle half-width, \(h\) is the rectangle half-height, and \(r\) is the circle radius.

The aperture region is the intersection of the rectangle and the circle (particles must be inside both the rectangle and the circle to survive).

Loss condition (particle is lost if either condition is met):

\[|x| \ge w \quad \text{or} \quad |y| \ge h\]

\[x^2 + y^2 \ge r^2\]

Note

The red dashed line is the rectangle boundary, and the blue solid line is the circle boundary. The aperture region is the intersection of the two.

rectellipse (Rectangle Inscribed Ellipse)

Parameters : aperture_value = [w, h, a, b] , where \(w\) is the rectangle half-width, \(h\) is the rectangle half-height, \(a\) is the ellipse horizontal semi-axis (x direction), and \(b\) is the ellipse vertical semi-axis (y direction).

The aperture region is the intersection of the rectangle and the ellipse (particles must be inside both the rectangle and the ellipse to survive).

Loss condition (particle is lost if either condition is met):

\[|x| \ge w \quad \text{or} \quad |y| \ge h\]

\[\left(\frac{x}{a}\right)^2 + \left(\frac{y}{b}\right)^2 \ge 1\]

Note

The red dashed line is the rectangle boundary, and the blue solid line is the ellipse boundary. The aperture region is the intersection of the two.

racetrack (Racetrack)

Parameters : aperture_value = [w, h, a, b] , where \(w\) is the rectangle half-width, \(h\) is the rectangle half-height, \(a\) is the x-direction semi-axis of the elliptical ends, and \(b\) is the y-direction semi-axis of the elliptical ends.

The racetrack aperture consists of a central rectangle and two semi-elliptical ends. The centers of the elliptical ends are located at \((\pm w, 0)\) .

Survival condition (particle survives if either condition is met):

Strictly inside the rectangular region:

\[|x| < w \quad \text{and} \quad |y| < h\]

Inside the elliptical end region (when \(|x| > w\) ):

\[\left(\frac{|x| - w}{a}\right)^2 + \left(\frac{y}{b}\right)^2 < 1\]

At the internal seams \(|x|=w\), a particle survives only when \(|y|<\min(h,b)\); these seams are not physical walls. All other points outside the strict regions are lost.

Note

The orange dots mark the centers of the elliptical ends at \((\pm w, 0)\) .

octagon (Octagonal)

Parameters : aperture_value = [w, h, d] , where \(w\) is the half-width, \(h\) is the half-height, and \(d\) is the half-diagonal clearance (chamfer distance).

The octagon is the shape obtained by cutting 45° corners off a rectangle. The larger \(d\) , the larger the chamfer; when \(d = 0\) , it degenerates into a rectangle.

Loss condition (particle is lost if either condition is met):

\[|x| \ge w \quad \text{or} \quad |y| \ge h\]

\[|x| + |y| \ge w + h - d\]

polygon (Polygon)

Parameters : aperture_value = [[x1, y1], [x2, y2], ...] , a list of vertices, automatically closed (the last vertex connects back to the first vertex).

Loss condition : The point lies on an edge or vertex, or outside the polygon. The edge check precedes ray casting; it uses a small floating-point tolerance shared by CPU and GPU.

The ray casting method is used to determine whether a point is inside the polygon: a ray is cast from the test point in the horizontal direction, and the number of intersections with the polygon edges is counted:

Odd number of intersections → the point is inside the polygon (survives)
Even number of intersections → the point is outside the polygon (lost)