18  Tracking

View:

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.

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

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

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

18.2 Current OPALX Track Mode

The current OPALX TRACK implementation is narrower than the legacy OPAL manual path and is best described from source.

The parser-side TRACK attributes currently implemented are:

  • LINE
  • SOURCES
  • BEAM
  • BEAMS
  • DT
  • DTSCINIT
  • DTAU
  • T0
  • MAXSTEPS
  • ZSTART
  • ZSTOP
  • STEPSPERTURN
  • TIMEINTEGRATOR
  • MAP_ORDER

18.2.1 Beam selection

OPALX accepts either:

  • BEAM=name for a single beam
  • BEAMS={name1, name2, ...} for several beams

BEAMS takes precedence over BEAM. The current code resolves the full beam list, but the tracker still uses only the first beam in that list as the active tracking beam while the broader multi-container path is being developed.

Photon beams are explicitly rejected during tracking even though BEAM, PARTICLE=PHOTON can be defined for future work.

18.2.2 Sources

TRACK,SOURCES=... is currently optional and ignored by the OPALX path. The effective emission sources are resolved from the selected beam via its attached EMISSIONSOURCELIST.

18.2.3 Time-step controls

DT, MAXSTEPS, and ZSTOP are still array-valued and are normalized to a common segment count internally by repeating the last provided value.

Additional OPALX-specific control knobs exposed on TRACK are:

DTSCINIT
initial space-charge timestep for the adaptive path.
DTAU
alternative accuracy-style control for space-charge stepping.
MAP_ORDER
truncation order of maps for the thick tracker. The default is first order.

18.2.4 Default values

The current OPALX defaults from code are:

  • DT = {1e-12}
  • MAXSTEPS = {10}
  • ZSTART = 0.0
  • ZSTOP = {1e6}
  • STEPSPERTURN = 720
  • TIMEINTEGRATOR = RK4
  • DTSCINIT = 1e-12
  • DTAU = -1.0
  • T0 = 0.0
  • MAP_ORDER = 1

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

18.3.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;

18.4 Current OPALX RUN

The current OPALX RUN command is much smaller than the legacy OPAL form. From source, the implemented attributes are:

  • METHOD
  • TURNS
  • FIELDSOLVER
  • BOUNDARYGEOMETRY
  • TRACKBACK

The method set is currently a single predefined value:

  • PARALLEL

So the minimal OPALX form is:

TRACK, LINE=myLine, BEAM=myBeam, DT={1e-12}, MAXSTEPS={100};
  RUN, METHOD=PARALLEL, FIELDSOLVER=myFieldSolver;
ENDTRACK;

18.4.1 Important OPALX differences from legacy OPAL

RUN does not currently take:

  • BEAM
  • DISTRIBUTION
  • MBMODE
  • PARAMB
  • PARALLEL-T
  • CYCLOTRON-T

Beam selection comes from the enclosing TRACK block through BEAM or BEAMS, not from RUN.

Distribution setup is also no longer taken from RUN. Instead, it is resolved from the beam’s EMISSIONSOURCELIST, which links each EMISSIONSOURCE to a named DISTRIBUTION.

18.4.2 Field solver and boundary geometry

FIELDSOLVER is mandatory in OPALX RUN. If it is missing, tracking throws.

BOUNDARYGEOMETRY is accepted and defaults to NONE.

TRACKBACK is accepted and defaults to FALSE, but the current OPALX path is still centered on forward parallel tracking.

18.4.3 What RUN does internally

At execution time, the current OPALX path:

  1. validates the input-file version
  2. resolves the field solver
  3. resolves the beam list from TRACK
  4. rejects photon beams
  5. resolves each beam’s EMISSIONSOURCELIST
  6. computes per-beam particle allocations
  7. builds the particle containers and global processes
  8. constructs the distribution samplers for each emission source
  9. creates the ParallelTracker
  10. executes the tracking loop

That is the key architectural difference from the legacy manual: RUN no longer directly owns the beam-distribution wiring.

18.5 Leaving Track Mode

Tracking mode ends when the parser sees:

ENDTRACK;

After ENDTRACK, the input returns to ordinary command mode.

18.6 Leaving Track Mode

OPALX uses the same ENDTRACK; terminator. Internally, the command parser returns after the RUN block has been executed and the temporary Track communication object has been cleaned up.