19 Tracking

A tracking block selects a lattice and beam, defines its step schedule, starts the tracker, and returns to normal input processing:

TRACK, LINE=Line1, BEAM=Beam1,
       DT={5e-11}, MAXSTEPS={100}, ZSTOP={1.0};
  RUN, METHOD=PARALLEL, FIELDSOLVER=FS1;
ENDTRACK;

19.1 `TRACK`

TRACK enters tracking mode. Only tracking commands such as RUN and ENDTRACK are accepted until the block closes.

Parameter	Default	Current behavior
`LINE`	required	Name of the `LINE` to track.
`BEAM`	`UNNAMED_BEAM`	Single beam name. Set it explicitly for normal runs.
`BEAMS`	empty	Ordered beam-name array. A non-empty array takes precedence over `BEAM`.
`SOURCES`	empty	Accepted for compatibility but ignored; sources come from each selected `BEAM`.
`DT`	`{1e-12}` s	Time-step schedule. Use positive values.
`MAXSTEPS`	`{10}`	Maximum-step schedule. Negative values are rejected; values are converted to integers.
`ZSTART`	`0` m	Starting reference position.
`ZSTOP`	`{1e6}` m	Stop-position schedule.
`T0`	`0` s	Accepted and stored, but not currently forwarded to `ParallelTracker`; source timing uses `EMISSIONSOURCE.T0`.
`DTSCINIT`	`1e-12` s	Accepted adaptive-integrator setting; not used by the current parallel path.
`DTAU`	`-1`	Accepted adaptive-integrator accuracy setting; not used by the current parallel path.
`TIMEINTEGRATOR`	`RK4`	Accepts `RK-4`, `RK4`, `LF-2`, `LF2`, or `MTS`, but does not currently select the `ParallelTracker` integration kernel.
`STEPSPERTURN`	`720`	OPAL-CYCL compatibility attribute; inactive in OPALX tracking.
`MAP_ORDER`	`1`	Stored compatibility value for map tracking; inactive in the current parallel path.

DT, MAXSTEPS, and ZSTOP may contain different numbers of entries. OPALX extends each shorter array by repeating its final value until all three have the same length. This defines consecutive tracking segments.

19.1.1 Beam selection

TRACK, LINE=Line1, BEAMS={ElectronBeam, PositronBeam},
       DT=1e-10, MAXSTEPS=2000, ZSTOP=60.0;

BEAMS takes precedence whenever it is non-empty. Each entry must resolve to a BEAM, and OPALX creates one particle container per entry. The order is significant: the first beam supplies the reference state used to construct the tracking block. Photon beams are rejected when RUN starts.

See Beam Definitions for per-container properties and source selection.

Before tracking starts, a LINE and a BEAM must be selected. The compact legacy form is:

TRACK, LINE=name, BEAM=name, DT={...}, MAXSTEPS={...}, ZSTOP={...};

Parameter	Legacy OPAL behavior
`LINE`	Beamline or sequence to track.
`BEAM`	Beam definition providing particle mass, charge, and reference momentum.
`T0`	Initial simulation time in seconds; default `0`.
`DT`	Time-step array; default `{1e-12}` s.
`MAXSTEPS`	Maximum-step array; default `{10}`.
`ZSTART`	Starting reference-particle position in metres.
`ZSTOP`	Longitudinal thresholds at which the next schedule segment becomes active.

If the schedule arrays have different lengths, the final supplied value is reused for the remaining segments.

19.2 `RUN`

RUN starts or continues particle tracking with the current bunch state.

Parameter	Default	Current behavior
`METHOD`	required	Only `PARALLEL` is accepted.
`FIELDSOLVER`	required	Name of the `FIELDSOLVER` used for the run.
`BOUNDARYGEOMETRY`	`NONE`	Optional named boundary geometry.
`TURNS`	`1`	Accepted compatibility value; inactive in the current parallel path.
`TRACKBACK`	`FALSE`	Accepted compatibility value; reverse tracking is not currently applied.

RUN does not register BEAM, BEAMS, SOURCES, or DISTRIBUTION. Selection belongs on TRACK and each BEAM; distribution objects are reached through the beam’s emission-source list.

The retained non-CYCL OPAL form is:

RUN, METHOD="PARALLEL-T", BEAM=beam1, FIELDSOLVER=Fs1,
     BOUNDARYGEOMETRY=Geometry1, TRACKBACK=FALSE,
     DISTRIBUTION=Dist1;

Parameter	Legacy OPAL behavior
`METHOD`	`PARALLEL-T` selects OPAL-T tracking.
`FIELDSOLVER`	Field-solver definition used for the run.
`DISTRIBUTION`	One distribution or a distribution list.
`BEAM`	Beam definition used for the run.
`BOUNDARYGEOMETRY`	Boundary geometry used for particle termination.
`TRACKBACK`	Selects OPAL-T reverse-time tracking.

A later RUN continues from the current bunch state unless the input explicitly reinitializes the bunch.

19.3 `ENDTRACK`

ENDTRACK;

ENDTRACK closes the tracking parser after RUN and releases the temporary tracking communication object.

ENDTRACK leaves track mode and returns the parser to ordinary command mode.

19.4 Current OPALX step sequence

At each step ParallelTracker performs a half position push, assembles space-charge and external fields, emits particles, applies the Boris momentum update and second half push, advances time, and updates the reference state. The Physics Overview describes this split.

The time step must resolve the shortest relevant field, geometry, emission, and collective-effect scale. Establish convergence by repeating a calculation with smaller steps and comparing physical observables.

19.5 Current OPALX parallel execution

OPALX combines MPI with the selected Kokkos backend. GPU runs normally use one MPI rank per GPU and pass --kokkos-map-device-id-by=mpi_rank so ranks select distinct devices.

19.1 TRACK