20  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;

20.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 or RING to track.
INITIALORBIT	omitted	Name of a completed COF result; see orbit handover.
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}	Per-segment integration-step limits. Negative values are rejected; values are converted to integers.
ZSTART	0 m	Starting reference position.
ZSTOP	{1e6} m	Stop-position schedule.
T0	0 s	With INITIALORBIT, inherited from COF; an explicit value must match. Otherwise stored but not forwarded to ParallelTracker; source timing uses EMISSIONSOURCE.T0.
DTSCINIT	1e-12 s	Accepted adaptive-integrator setting; not used by current parallel tracking.
DTAU	-1	Accepted adaptive-integrator accuracy setting; not used by current parallel tracking.
TIMEINTEGRATOR	RK4	Accepts RK-4, RK4, LF-2, LF2, or MTS, but does not currently select the ParallelTracker integration kernel.
STEPSPERTURN	720	Nominal steps per turn for spectral tune analysis; otherwise inactive in normal tracking.
EKINSTOP	0 (disabled)	Positive reference kinetic-energy target in GeV for single-gap cyclotron acceleration.

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. After expansion, the values at index \(i\) form one tracking segment: DT[i] is its time step, MAXSTEPS[i] is its independent step budget, and ZSTOP[i] is its path-length target. OPALX orders these segment triples by increasing ZSTOP.

A segment ends when all active particle containers reach its ZSTOP or when its own MAXSTEPS budget is exhausted, whichever happens first. Unused steps are not transferred to the following segment. The maximum number of steps for the complete schedule is therefore the sum of the expanded MAXSTEPS array; the actual number can be smaller when a ZSTOP is reached early.

For example:

TRACK, LINE=Line1, BEAM=Beam1,
       DT={1e-11, 2e-12},
       MAXSTEPS={10, 20},
       ZSTOP={0.006, 0.05};

The first segment may take at most 10 steps to reach 0.006 m. The second then has a new budget of 20 steps to reach 0.05 m, so the complete schedule permits at most 30 steps. If the first segment reaches its target after two steps, the second starts at global step two and still has its full 20-step budget.

With two-entry DT and ZSTOP arrays, a scalar MAXSTEPS=10 is expanded to MAXSTEPS={10, 10} and permits at most 20 steps in total.

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

20.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	omitted; 1 for spectral tunes	Optional RING return-count stopping condition.
TRACKBACK	FALSE	Accepted compatibility value; reverse tracking is not currently applied.
SCFIELDUPDATE	MIDPOINT	Space-charge evaluation point within the drift–kick–drift step: MIDPOINT or PRESTEP.
SPECTRALTUNES	FALSE	Run the separate spectral tune diagnostic.
TUNESAMPLE	50	Positive integer sampling stride for spectral tune rays.
TUNEINTEGRATOR	RK4	Spectral-ray integrator: BORIS, LF2, RK4, or DOP853.
TUNESECTOR	SM0	Cyclotron sector defining the spectral launch plane and centre.

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.

20.2.1 Space-charge field update point

SCFIELDUPDATE controls when an active particle self-field is calculated:

RUN, METHOD="PARALLEL", FIELDSOLVER=FS1,
     SCFIELDUPDATE="PRESTEP";

Value	Space-charge positions	Step ordering
MIDPOINT	\(R_{n+1/2}\)	Half drift, self-field solve, external-field evaluation, Boris kick, half drift
PRESTEP	\(R_n\)	Self-field solve, half drift, external-field evaluation, Boris kick, half drift

MIDPOINT is the default OPALX ordering. PRESTEP reproduces the historical OPAL space-charge sampling point: the gathered self-fields are carried with their particles through the first half drift and then combined with external fields evaluated at the midpoint. Both values use the same particle deposition, Poisson solver, Green function, Boris momentum update, and position drifts.

The option applies to normal parallel bunch tracking on a LINE or RING; it is not specific to cyclotrons. It has no physical effect when FIELDSOLVER.TYPE=NONE. Treat a change of update point as a numerical-method change and repeat the timestep-convergence study for the observables of interest.

20.2.2 TURNS

TURNS is an optional stopping condition for tracking a RING.

When TURNS=N is specified explicitly, OPALX counts directed crossings of the ring return plane and stops at the Nth complete return of the reference particle. N must be a positive integer.

The fixed return plane passes through the launch reference position and is normal to the initial reference momentum. The initial point and an opposite-direction crossing do not count. Earlier turns are counted at integration endpoints. For the final requested return, OPALX locates the forward crossing by reintegrating the reference from the start of the last step, then advances the whole bunch through that shortened timestep. The reference, particle coordinates, and final statistics/HDF5 output therefore share the same time. The reference’s signed distance from the plane must be below 1 nm.

This localizes the reference crossing; it does not force the reference or each particle back to its launch coordinates. Transverse orbit error and bunch motion remain independent quantities.

When TURNS is omitted, no turn-count stopping condition is enabled. Tracking instead follows the ZSTOP and MAXSTEPS schedule defined by TRACK. Consequently, omitting TURNS is intentionally different from specifying TURNS=1.

Explicit turn-count tracking currently has the following restrictions:

• Directed turn counting is implemented only for a RING. On a LINE, an explicit TURNS value currently does not activate a turn-count stop.
• Exactly one DT, MAXSTEPS, and ZSTOP segment must be defined.
• Restart tracking is not supported.
• One beam/container and FIELDSOLVER, TYPE=NONE are required. Space-charge and multiple-container terminal events are not yet supported.
• Emission must already be complete when tracking starts.
• The lattice may contain static drifts, markers, monitors, multipoles, SBENDs, RBENDs, solenoids, and cyclotron sectors. RF cavities and other time-dependent elements are not supported for localized TURNS.
• TURNS cannot be combined with EKINSTOP.

For an explicit turn count, OPALX disables the ZSTOP limit and may increase the single MAXSTEPS value using N times the design circumference to estimate the step budget. The circumference is not the completion criterion. The run reports an error if any active container does not complete the requested returns within the resulting step budget or field bounds.

When SPECTRALTUNES=TRUE, TURNS instead specifies the nominal number of turns used for spectral analysis. In that mode, its default value is 1, the run takes TURNS * STEPSPERTURN integration steps, and geometric return crossings are not used.

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.

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

20.4 Closed-orbit command (experimental)

COF finds a four-dimensional, fixed-energy orbit of a static magnetic RING. It is separate from TRACK; it emits no particles, runs no collective physics, and does not change the selected BEAM. A named command executes at its terminating semicolon and retains its result in memory. There is no inner RUN or ENDCOF:

// MYRING is a geometrically closed RING; B0 is a fully defined BEAM.
ic: COF, LINE=MYRING, BEAM=B0, DT=4.113195129977025e-11,
     MAXSTEPS=8000, MAXPATH=40, TIMEINTEGRATOR="RK4",
     METHOD="NEWTON", X=0, PX=-0.00024, Y=0, PY=0,
     FDSTEP={1e-5,1e-6,1e-5,1e-6}, SCALES={1,0.4,1,0.4},
     XTOL=1e-10, PTOL=1e-10;

The numerical values above illustrate the 72 MeV cyclotron, not universal ring settings. Set the beam’s energy explicitly, for example ENERGY=PMASS+0.072 for a 72 MeV proton: BEAM ENERGY is total energy in GeV, not kinetic energy. Existing BEAM requirements (NALLOC, SOURCES, etc.) still apply, but COF does not load or emit the linked source distributions.

20.4.1 Tracking controls on COF

Attribute	Default	Meaning
LINE, BEAM	required	Root RING and one charged massive BEAM with explicit PC, ENERGY or GAMMA.
DT	1e-12 s	One positive scalar ray timestep, not a schedule.
MAXSTEPS	200000	Positive integer budget per return, at most 1e9; reaching it without a return fails.
MAXPATH	required	Positive maximum search path in metres; normally greater than one circumference.
TIMEINTEGRATOR	RK4	Ray integrator: RK4, DOP853, BORIS, or alias LF2. DOP853 uses a fixed-step formula, without adaptive step selection.
T0	0 s	Initial ray time. Fields must nevertheless be static.
SECTION	root RING frame	Optional global {X,Y,Z,THETA,PHI,PSI} in metres and radians, using element-pose rotation conventions.
GEOMTOL	1e-9 m	Nominal last-element exit to first-element entrance position tolerance.
ANGLETOL	1e-10 rad	Maximum mismatch angle between corresponding nominal frame axes.

Each ray starts on the section’s local z=0 plane and returns in the local positive-z direction after a negative-side excursion. There is no teleportation, fixed-time turn, or energy projection. MAXPATH and MAXSTEPS are failure guards, not turn definitions. The nominal geometry test is independent of the particle’s orbit and ignores misalignments; tracked fields retain native misalignments. The user must choose a meaningful section and sufficiently small DT, especially for self-intersecting trajectories.

20.4.2 Solver controls on COF

Attribute	Default	Meaning
METHOD, DIMENSION, JACOBIAN	NEWTON, 4, CENTRAL	Only these choices are supported.
X, PX, Y, PY	0	Initial section-frame guess; positions in metres, mechanical momenta in p/(mc), not slopes.
MAXIT	20	Positive integer maximum of accepted Newton iterations, at most 1e9.
XTOL, PTOL	1e-10, 1e-10	Componentwise position and momentum tolerances for both residual and undamped correction.
FDSTEP	{1e-6,1e-6,1e-6,1e-6}	Four positive absolute derivative steps in the coordinate units.
SCALES	{1,1,1,1}	Four positive coordinate scales for Newton and eigenanalysis.
DAMPING	TRUE	Backtracking; when false only a residual-reducing full Newton step is accepted.
OUTPUT	omitted	Optional exact JSON filename. No file is written when omitted; existing files are rejected.

Currently supported field elements are DRIFT, MARKER, static MULTIPOLE (including its quadrupole/sextupole definitions), native SBEND, RBEND, and CYCLOTRONSECTOR. Passive monitors are skipped without initialising their output files. Other types, including RF even at zero voltage, are rejected. Native element aperture-loss predicates are checked at accepted substep start, midpoint and end; timestep convergence is still necessary to resolve narrow interceptions. For conventional elements, the check selects the nearest finite design centreline independently of aperture size. This prevents a drift on the opposite ring arm from rejecting a valid particle merely because it lies between that drift’s extended entrance and exit planes. Equal-distance segments are checked together; sector bends use circular design arcs, while straight and rectangular-bend bodies use their straight axes. This assumes a local orbit neighbourhood with an unambiguous nearby design path, not intersecting beam-pipe solids. Cyclotron sectors retain their native domain predicates. Field selection is unchanged. The selected beam cannot have global processes. No RF/6D closure, space charge, restart, energy continuation, or automatic integer tune and plane assignment is provided. Unsupported attributes such as ZSTOP, BEAMS, FIELDSOLVER, and ENERGYSTART are errors, not ignored compatibility settings.

20.4.3 Results and parallel behavior

Each named solve retains its full laboratory launch position [m], momentum [p/(mc)], section, time, species, energy and numerical diagnostics independently. OUTPUT="orbit.json" writes exactly that JSON file; there are no text or orbit-CSV sidecars. With OUTPUT omitted, COF writes no files. Standalone COF inputs also suppress the process timing file; ordinary TRACK output remains unchanged. Solver failures stop execution before a result can be consumed. The COF JSON format specifies the coordinates, matrix and launch metadata. No filename extension is added.

The solve runs on rank zero. The launch state, diagnostics and failure status are broadcast before returning. Only rank zero writes an explicit result file. See the COF architecture for implementation details.

20.4.4 Initialise TRACK from a named orbit

// ic is a completed named COF; B0 has a generated, orbit-local distribution.
FS0: FIELDSOLVER, TYPE=NONE, NX=16, NY=16, NZ=16;
TRACK, LINE=MYRING, BEAM=B0, INITIALORBIT=ic,
       DT=1e-12, MAXSTEPS=200000;
  RUN, METHOD="PARALLEL", FIELDSOLVER=FS0, TURNS=1;
ENDTRACK;

TRACK checks the lattice name, particle species, mass, charge and reference momentum against the stored result. Keep the lattice and field definitions unchanged between solve and handover; recompute COF after changing them. The name check does not detect changes to fields or geometry under the same name. TRACK inherits the COF time; an explicit conflicting T0 is an error. INITIALORBIT refers to the result held in memory by that named command; it does not read a JSON file.

Generated particle positions and source offsets are in the orbit-local frame, whose origin is the solved position and whose +z axis follows the solved momentum. Particle momenta are full p/(mc) vectors in that frame, including their longitudinal reference momentum. The distribution spread and centroid offsets are retained; they do not replace the solved reference.

The initial handover supports one fresh beam, ZSTART=0, and completed emission. FROMFILE and EMITTEDFROMFILE are rejected because their existing absolute coordinate convention would make placement ambiguous. Restart and spectral tune mode cannot use INITIALORBIT. Space-charge matching is not performed by COF; an orbit-centred bunch is not necessarily a self-consistently matched bunch. For space-charge tracking, omit TURNS and use the TRACK stopping schedule.

The handover transfers the launch state, not COF’s timestep or integration settings. COF’s ray integrator and TRACK’s production Boris integration can give different closure errors at the same DT. Check TRACK convergence independently. Their return planes can also differ: COF uses the selected section normal, while TRACK uses the solved launch momentum as its normal.

Several COFs may precede TRACK. INITIALORBIT=ic1 selects ic1 even if ic2 was computed later. Existing input blocks must move their local RUN attributes onto the named COF statement, remove ENDCOF, and use an exact filename for OUTPUT.

Convergence proves closure of the numerical return map, not physical stability. Off-unit-circle eigenpairs have null stable-tune values in JSON. Fractional modes are unlabelled and do not determine an integer or conjugate branch. In particular, the cyclotron radial modulus sensitivity remains under investigation; the command does not suppress this warning or relax the unit-circle tolerance. See the return-map and solver physics.

20.5 Current OPALX step sequence

With the default SCFIELDUPDATE="MIDPOINT", 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. With SCFIELDUPDATE="PRESTEP", it assembles the self-field before the first half push while retaining midpoint external-field evaluation. See Space-charge field update point. 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.

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