17 Tracking

The TRACK command enters tracking mode. In that mode the input accepts only tracking-related commands such as RUN and ENDTRACK. The command selects the lattice, the beam, timestep arrays, and stopping conditions that define a tracking block.

17.1 Track Mode

Before tracking starts, a LINE and a BEAM must be selected. The timestep array DT and the maximal number of steps MAXSTEPS, or alternatively the position thresholds ZSTOP, control how long the tracking block runs.

The commands accepted in track mode are:

Command	Purpose
`TRACK`	Enter tracking mode.
`LINE`	Select the `LINE` or `SEQUENCE` to track.
`BEAM`	Select the beam definition.
`T0`	Initial simulation time in seconds.
`DT`	Array of timestep sizes.
`MAXSTEPS`	Array of maximal step counts.
`ZSTART`	Starting reference-particle position in `m`.
`ZSTOP`	Array of `z` thresholds at which the next `DT` / `MAXSTEPS` segment becomes active.
`STEPSPERTURN`	Time steps per revolution, for OPAL-cycl.
`TIMEINTEGRATOR`	Time integrator selection for OPAL-cycl.
`RUN`	Start or continue tracking.
`ENDTRACK`	Leave tracking mode.

The compact format is

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

If arrays have different lengths, the last provided value is reused for the remaining segments.

17.1.1 Main attributes

LINE: beamline or sequence to track.
BEAM: beam definition that provides particle mass, charge, and reference momentum.
T0: initial time in seconds. The default is 0.
DT: timestep array. If omitted, the default is a single value 1 ps.
MAXSTEPS: maximum number of steps for each segment. If omitted, the default is 10.
ZSTART: starting reference-particle position along the reference path.
ZSTOP: array of longitudinal stopping thresholds. If omitted, the default is effectively a single large value.
STEPSPERTURN: time steps per turn in OPAL-cycl. The default is 720.
TIMEINTEGRATOR: OPAL-cycl time integrator. Valid choices are RK4, LF2, and MTS.

17.1.2 OPAL-cycl integrators

RK4: fourth-order Runge-Kutta. This is the default for OPAL-cycl.
LF2: second-order Boris-Buneman / leapfrog-style integrator.
MTS: multiple-time-stepping integrator. Space charge is solved less frequently than the external-field updates, and the number of substeps is controlled by MTSSUBSTEPS.

When switching from RK4 or LF2 to MTS, all step-count based options such as PSDUMPFREQ, REPARTFREQ, and SPTDUMPFREQ must be rescaled consistently with the chosen MTSSUBSTEPS.

17.2 Track Particles

The RUN command starts or continues the actual tracking. In the legacy OPAL manual its main form is:

RUN, METHOD=string, FIELDSOLVER=label, DISTRIBUTION=label-vector, BEAM=label,
     TURNS=integer, MBMODE=string, PARAMB=float,
     BOUNDARYGEOMETRY=string, TRACKBACK=logical;

The current bunch state is used as the initial condition, so a later RUN continues from the result of the previous track unless the input explicitly reinitializes the bunch.

17.2.1 Main attributes

METHOD

tracking method. The classic manual documents:

PARALLEL-T for OPAL-T
CYCLOTRON-T for OPAL-cycl

FIELDSOLVER

field solver definition used for the run.

DISTRIBUTION

one distribution or a distribution list.

BEAM

beam definition used for the run.

TURNS

number of turns or, in OPAL-cycl multi-bunch mode, number of bunches to inject.

MBMODE

multi-bunch mode, typically AUTO or FORCE.

PARAMB

threshold parameter used with automatic multi-bunch switching.

MB_BINNING, MB_ETA

cyclotron multi-bunch energy-binning controls.

BOUNDARYGEOMETRY

boundary geometry used for particle termination.

TRACKBACK

OPAL-T reverse-time tracking mode.

Example:

RUN, FILE="table", TURNS=5, MBMODE=AUTO, PARAMB=10.0,
     METHOD="CYCLOTRON-T", BEAM=beam1, FIELDSOLVER=Fs1,
     DISTRIBUTION=Dist1;

17.3 Leaving Track Mode

Tracking mode ends when the parser sees:

ENDTRACK;

After ENDTRACK, the input returns to ordinary command mode.