Marker

This module introduces the marker element Marker in PASS, used to mark a specific longitudinal position in the beamline without altering any particle coordinates.

The marker code is located in PASS/commands/element/marker.py, with class name Marker and registration name marker. The core features of the marker are as follows:

Zero-length element (length = 0.0, not configurable), occupies no physical beamline space
Performs no particle coordinate transformation; all phase space coordinates remain unchanged when particles pass through the marker
Supports aperture checking via aperture_type and aperture_value parameters; execute_cpu only calls the check_aperture_cpu function
GPU tracking is a no-op (execute_gpu is pass), performing no computation

The main purposes of the marker include:

Marking key positions in the beamline sequence (e.g., measurement points, interaction points, injection points) for subsequent analysis
Serving as sorting reference points; other elements can be laid out relative to marker positions
Identifying physical positions in output and logs without participating in particle tracking

Physical Description

The marker produces no electromagnetic field, exerts no force, and does not change particle state. When a particle passes through the marker, all six phase space coordinates (\(x, p_x, y, p_y, z, \delta\)) remain unchanged:

\[x \leftarrow x\]

\[p_x \leftarrow p_x\]

\[y \leftarrow y\]

\[p_y \leftarrow p_y\]

\[z \leftarrow z\]

\[\delta \leftarrow \delta\]

The marker only records its longitudinal position \(s\) in the beamline for sequence sorting and position annotation.

When aperture checking is configured (aperture_type is not off), the marker calls the check_aperture_cpu function in execute_cpu to perform aperture boundary checking on the transverse coordinates (\((x, y)\)) of alive particles (\(\text{tag} > 0\)). Particles exceeding the aperture boundary are marked as lost (tag set to negative), and the loss position and turn number are recorded. The detailed principles and type definitions of aperture checking are described in the Aperture chapter.

Interface Parameters

All interface parameters of the marker are shown in the table below:

Property	JSON key	Type	Unit	Description
`s`	`S (m)`	float	m	Longitudinal position of the element in the beamline
`length`	(fixed 0.0, not configurable)	float	m	Element length (always 0, not configurable)
`name`	`name`	str		Element name (automatically filled from the key name of the sequence JSON)
`aperture_type`	`Aperture Type`	str		Aperture type, default `off`, case-insensitive
`aperture_value`	`Aperture Value`	list		Aperture parameter values, default `[]`, meaning varies by type

Aperture Type Options

aperture_type is case-insensitive and is internally converted to lowercase before matching. The available values are:

Type	aperture_value	Description
`off`	ignored	No aperture checking (default)
`default`	ignored	Default ±1m rectangular aperture
`circle`	`[r]`	Circle, \(r\) is the radius
`rectangle`	`[w, h]`	Rectangle, \(w\) is the half-width, \(h\) is the half-height
`ellipse`	`[a, b]`	Ellipse, \(a\) is the semi-major axis, \(b\) is the semi-minor 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 shape (rectangle + elliptical ends)
`octagon`	`[w, h, d]`	Octagon (rectangle with 45° corners cut)
`polygon`	`[[x1,y1], ...]`	Polygon vertex list, automatically closed

Note

The marker does not require a Length (m) field; the length is fixed at 0 in the code.

The Command field should be set to Marker.

The off and default types ignore aperture_value. The detailed physical descriptions and conditions for each aperture type are in the Aperture chapter.

Usage Examples

Basic Usage

The following example places a marker at \(s = 12.5\) m to mark the interaction point position, without enabling aperture checking:

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker"
    }
}

"IP" is the element name, automatically read by CommandSequence and assigned to the name property.

Marker with Aperture Checking

The marker can also be configured with aperture checking to detect particles exceeding the beam pipe boundary at that position. The following example places a marker with a circular aperture (radius 0.05 m) at \(s = 12.5\) m:

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker",
        "Aperture Type": "circle",
        "Aperture Value": [0.05]
    }
}

Multiple Marker Combination

Multiple markers can be used repeatedly in the same beamline, for example to mark the interaction point, injection point, and measurement point:

{
    "IP": {
        "S (m)": 12.5,
        "Command": "Marker"
    },
    "Injection_Point": {
        "S (m)": 0.0,
        "Command": "Marker"
    },
    "Measurement_Point": {
        "S (m)": 105.3,
        "Command": "Marker",
        "Aperture Type": "rectangle",
        "Aperture Value": [0.05, 0.03]
    }
}

Application Scenarios

Interaction point marking: Marks the beam collision position in colliders, facilitating luminosity calculation and beam-beam interaction element positioning
Injection point marking: Marks the position of injection elements, facilitating the interface between the injector and the main ring
Measurement point marking: Marks the location of monitors, facilitating data analysis and physics quantity extraction
Sequence sorting reference: Uses the marker’s s position as a reference to organize the arrangement of other elements in the beamline
Aperture monitoring: Configures aperture checking at key positions (e.g., interaction point, injection point) to monitor beam loss without adding additional physical elements