11  Runtime Options

OPTION changes process-wide parser, tracking, output, and diagnostic settings.

OPTION, VERSION=10900, PSDUMPFREQ=10, STATDUMPFREQ=1,
        CHECKPOINTFREQ=0, BOUNDPDESTROY=10, QM_MODE=SINGLE;

Several attributes remain registered for input compatibility even though the current ParallelTracker does not consume them. Those attributes are listed separately so parser acceptance is not confused with runtime support.

The Boolean INFO option is distinct from the executable’s --info <level> argument. INFO gates a small set of parser messages; the command-line level controls the level1, level2, and more detailed runtime streams.

11.1 Command-line logging

Pass --info N after the input file to show messages through level N:

Level	Intended content
1	Essential run status and rare or critical events.
2	Normal progress and run summaries suitable for production.
3	Algorithm progress, including time-step, repartitioning, and binning setup.
4	Fine-grained implementation details for debugging.
5	Full trace-style output, including frequent step and solver details.

Use level 1 or 2 for production runs. Higher integer values are accepted, but OPALX currently defines no additional message categories above level 5.

11.2 Parser and messages

Option	Default	Effect
ECHO	FALSE	Echo input while parsing.
INFO	TRUE	Enable informational parser messages.
TRACE	FALSE	Print timing before and after traceable commands. Put this in the first OPTION statement.
WARN	TRUE	Enable warnings from expressions and selectors.
SEED	123456789	Random seed used by current samplers and stochastic physics. -1 requests time-based seeding where supported.
TELL	FALSE	Print all effective option values immediately. Put this in the last OPTION statement whose settings should be shown.

11.3 Output and diagnostics

Frequencies are measured in global tracking steps unless stated otherwise.

Option	Default	Effect
PSDUMPFREQ	10	Phase-space dump frequency. 0 is converted internally to an effectively disabled frequency.
STATDUMPFREQ	10	Statistics dump frequency. 0 is converted internally to an effectively disabled frequency.
CHECKPOINTFREQ	0	Write a restart checkpoint after every N completed global tracking steps. 0 disables checkpointing; negative values are rejected.
STEPINFOFQ	1	Per-step status frequency; values below zero become 0, which disables the lines.
PRINTRANKDISTRFQ	0	Per-rank particle-count table frequency; 0 disables it and negative values become 0.
RHODUMP	FALSE	Add the scalar charge-density field to supported HDF5 output.
EBDUMP	FALSE	Add the electric and magnetic field at each particle to phase-space HDF5 output.
RANKDUMP	FALSE	Add each particle’s current MPI rank to phase-space HDF5 output.
ENABLEHDF5	TRUE	Enable HDF5 phase-space and loss output.
ENABLEVTK	TRUE	Enable supported VTK geometry output.
ASCIIDUMP	FALSE	Make supported monitor and plug-in loss sinks write ASCII instead of HDF5.
BEAMHALOBOUNDARY	0	Halo boundary in rms beam sizes for statistics; values at or below zero disable this count.
HALOSHIFT	0	Constant subtracted from the reported halo parameter.
COMPUTEPERCENTILES	FALSE	Compute the configured beam-size and normalized-emittance percentiles; samples below 100 particles are skipped.

CHECKPOINTFREQ is independent of PSDUMPFREQ and ENABLEHDF5. OPALX atomically replaces <input-basename>_checkpoint.h5, so the file always holds the most recent completed checkpoint. See Checkpoint and restart.

11.4 Numerical linear transfer maps

OPTION, ENABLELINEARTRANSFERMAPS=TRUE,
        LINEARTRANSFERMAPRICHARDSON=1,
        LINEARTRANSFERMAPSTEPS={1e-3,1e-3,1e-3,1e-3,1e-3,1e-3},
        LINEARTRANSFERMAPINTEGRATOR="BORIS";

Option	Default	Effect and constraints
ENABLELINEARTRANSFERMAPS	FALSE	Calculate and attach external-field maps during the design-reference OrbitThreader pass. Print the complete LINE or one-turn RING map and diagnostics.
LINEARTRANSFERMAPRICHARDSON	0	Integer refinement level from 0 through 4. Zero retains centered differences. Level 1 gives formally fourth-order differentiation, level 2 sixth-order, and so on, assuming a sufficiently smooth map.
LINEARTRANSFERMAPSTEPS	Six values of 1e-3	Starting amplitudes in (x,x',y,y',zeta,delta) order. Exactly six finite positive values; the delta amplitude must be less than 1. Position/zeta amplitudes are in metres; slopes/delta are dimensionless.
LINEARTRANSFERMAPINTEGRATOR	BORIS	Map reference and perturbed-ray stepping: BORIS (alias LF2), fixed-step RK4, or fixed-step DOP853 (eighth-order formula). Unknown methods are rejected. No effect on particle TRACK, disabled-map or secondary-species threading.

Richardson level \(L\) uses \(L+1\) centered maps with amplitudes reduced successively by two, costing \(12(L+1)\) private rays per segment. The four-level limit bounds this at 60 rays. Higher levels do not guarantee a better answer: integration error, field interpolation, boundary resolution and subtraction noise remain. Smooth-field time-integration orders are 2 for Boris, 4 for RK4 and 8 for DOP853; Richardson changes differentiation order only. DOP853 here has no adaptive error controller or dense output: DT is the nominal step for all three methods, subdivided at field-support transitions. These controls do not select the production-particle integrator. Higher order is more expensive per step and does not guarantee a symplectic map or better accuracy for nonsmooth fields.

The effective settings are printed before the combined matrix. Each element-owned segment map also records the starting/finest amplitudes, refinement level, integrator, and last refinement change (not a certified error estimate). A later OPTION statement preserves values it does not override. Settings are copied when the OrbitThreader is constructed.

See Numerical linear transfer maps for coordinates, overlap composition, supported physics and diagnostic limitations.

11.4.1 OrbitThreader performance diagnostics

Run with --info 1 (or a higher information level) to enable the diagnostic log and timing.dat output, for example opalx --info 1 ring.in. At information level zero the current IPPL output layer suppresses both, leaving an empty timing file even when tracking completes successfully.

OrbitThreader prints its effective time step, integrator, map enablement, Richardson level, and ring period for each species pass. Reference and perturbed map rays run serially on the host; OpenMP thread capacity reported at startup applies to the runtime and does not imply parallel ray tracking. Startup also records the loaded executable path (where supported), build configuration, compiler, configure-time CMake C++ flags, assertion status, MPI ranks, and Kokkos host concurrency. CMake flags are not a complete compile command: target/dependency options may add flags, and multi-configuration builds select their configuration at build time.

The existing OrbThreader total in timing.dat includes these accumulated phase timers, plus constructor and surrounding tracker setup:

Timer	Included work
OT reference	Backward pre-roll, forward reference integration, support index construction, reference samples, and design-path row writes.
OT segmentation	Reference clipping, nominal-body queries and boundary localization, and segment partitioning.
OT maps	Perturbed-ray tracking, finite differences/Richardson, contributor queries, map composition, and attachment to elements.
OT output	Combined-map printing, support-index/geometry output, and closing the design-path log.

Phase timers accumulate across species and repeated tracking calls. The printed work summaries instead describe one OrbitThreader pass on rank zero, without MPI reductions. They report:

• nominal_steps: outer reference or perturbed-ray tracking iterations; advances: all support-resolved advance calls, including localization retries.
• trials and accepted_steps: evaluated integration trials and accepted substeps. Accepted substeps include work subsequently discarded by enclosing path/plane localization; they are not a count of unique steps on the final orbit.
• cap_splits, support_splits, max_depth, min_accepted_dt_s, and step_cap_s: subdivision counts by cause, deepest recursion, smallest accepted duration, and the smallest geometric time-step cap encountered, in seconds.
• support_lookups, body_lookups, and element_tests: full-lattice selections and the number of elements scanned by those selections. field_samples counts summed-field evaluations; element_fields counts individual element field applications in reference/map ray integration. Cavity-autophaser internals are not covered by these ray-work counters, although their time remains in OT reference.
• membership_reuses: full support lookups avoided by reusing an already evaluated membership set at an identical recursive start or accepted endpoint. Reuse is limited to one ray advance; field values and trajectories are not cached.
• reference_samples, segments, and rays: recorded reference states, unique map intervals, and perturbed trajectories. At Richardson level \(L\), each map interval normally launches \(12(L+1)\) rays.
• ray_tracking_s: time inside perturbed-ray tracking, already included in OT maps. Its subsets ray_transport_s and ray_exit_s separate ordinary tracking through the first bracketed exit crossing from exit-plane localization. exit_iterations counts the localization reintegrations. These subset clocks introduce no additional synchronization or per-step clock reads.
• log_rows and log_write_s: design-path rows and their write time, already included in OT reference. Do not add subsets to their enclosing phase totals.

An unused measurement is printed as zero. Inner-loop diagnostics use counters; wall-clock reads occur at phase, trajectory, and log-row boundaries. Phase timers retain the configured IPPL timer-fence policy. Diagnostics do not change integration tolerances, field selection, or the production-particle integrator.

11.5 Tracking, particles, and solvers

Option	Default	Effect and constraints
REPARTFREQ	10	Check particle repartitioning at this frequency. Values at or below zero disable periodic repartitioning.
LOADBALANCINGTHRESHOLD	0.05	Imbalance threshold for load balancing; must lie in [0,1].
BOUNDPDESTROY	10	Delete particles outside this many rms beam sizes. Values at or below zero disable the cut.
MINBINEMITTED	10	Delay space-charge calculation until the primary container has more particles than this threshold.
MINSTEPFORREBIN	200	Earliest step at which the current tracker may collapse emission bins.
AUTOPHASE	6	Number of RF phase-search refinements; 0 disables autophasing.
QM_MODE	SINGLE	SINGLE stores one charge and mass per container; ATTRIBUTES allocates per-particle Q and M views.
AGGRESSIVE_STATE_SYNC	FALSE	MPI-allreduce every shared bunch-state mutation. Intended for diagnosing rank-local state divergence; adds collective overhead.
VERSION	10000	OPAL input-version code. RUN reports incompatible changes when the value predates registered input changes.

MINBINEMITTED and MINSTEPFORREBIN affect runtime bin handling. The definition of the adaptive histogram itself is documented under Structures / Binning.

11.6 Accepted compatibility options

The following names are accepted and stored, but have no current consumer in the OPALX ParallelTracker source. Do not rely on them to change a simulation.

Option	Default	Historical or intended role
PSDUMPEACHTURN	FALSE	OPAL-CYCL phase-space dump after each turn.
PSDUMPFRAME	GLOBAL	OPAL-CYCL dump frame: GLOBAL, BUNCH_MEAN, or REFERENCE.
SPTDUMPFREQ	1	Single-particle trajectory dump frequency. 0 is converted to an effectively disabled frequency.
SCSOLVEFREQ	1	Requested space-charge solve frequency; parsed values below one become one.
MTSSUBSTEPS	1	Small-step count intended for multiple-time-stepping integration.
REMOTEPARTDEL	0	Historical remote-particle rms deletion threshold.
REBINFREQ	100	Historical frequency for resetting energy-bin identifiers.
CSRDUMP	FALSE	Historical CSR field and line-density output.
NUMBLOCKS	0	Recycled-CG Krylov-space vector limit.
RECYCLEBLOCKS	0	Recycled-CG recycle-space vector count.
NLHS	1	Old solutions retained for a solver starting-vector extrapolation.
CZERO	FALSE	Historical request for a distribution with zero centroid.
RNGTYPE	RANDOM	Accepts RANDOM, HALTON, SOBOL, or NIEDERREITER; current distribution samplers do not select their engine through it.
CLOTUNEONLY	FALSE	OPAL-CYCL closed-orbit and tune-only mode.
IDEALIZED	FALSE	Historical hard-edge path-length compatibility mode.
LOGBENDTRAJECTORY	FALSE	Historical request to write each bend trajectory.
MEMORYDUMP	FALSE	Historical SDDS memory output request; the current OPTION execution path does not apply it.
DELPARTFREQ	1	Historical particle-deletion frequency.

The legacy OPAL form is:

OPTION, VERSION=integer, ECHO=logical, INFO=logical, TRACE=logical,
        WARN=logical, SEED=real, PSDUMPFREQ=integer,
        STATDUMPFREQ=integer,
        REPARTFREQ=integer, REBINFREQ=integer, TELL=logical;

The most frequently used controls are:

Option	Legacy OPAL meaning
VERSION	Input-file compatibility tag, conventionally encoded as major, minor, and patch digits.
ECHO, INFO, TRACE, WARN	Control input echo, information, trace, and warning streams.
TELL	Print the effective option settings.
SEED	Random-number seed; -1 requests time-dependent seeding.
RNGTYPE	RANDOM, HALTON, SOBOL, or NIEDERREITER.
ASCIIDUMP	Select ASCII output for supported loss and diagnostic elements.
AUTOPHASE	Number of auto-phasing refinements; 0 disables auto-phasing.
PSDUMPFREQ, STATDUMPFREQ	Phase-space and statistics output frequencies.
REPARTFREQ, REBINFREQ	Particle repartition and energy-bin reset frequencies.
SCSOLVEFREQ	Space-charge solve reuse frequency for supported integrators.
ENABLEHDF5, ENABLEVTK	Enable or disable the corresponding output families.

11.6.1 Legacy defaults

Option	Default	Option	Default
AMR	FALSE	AMR_REGRID_FREQ	10
AMR_YT_DUMP_FREQ	10	ASCIIDUMP	FALSE
AUTOPHASE	6	BEAMHALOBOUNDARY	0.0
COMPUTEPERCENTILES	FALSE	CSRDUMP	FALSE
CZERO	FALSE	DELPARTFREQ	1
DUMPBEAMMATRIX	FALSE	EBDUMP	FALSE
ECHO	FALSE	ENABLEHDF5	TRUE
ENABLEVTK	TRUE	HALOSHIFT	0.0
IDEALIZE	FALSE	INFO	TRUE
LOGBENDTRAJECTORY	FALSE	MEMORYDUMP	FALSE
MINBINEMITTED	10	MINSTEPFORREBIN	200
NLHS	1	NUMBLOCKS	0
PSDUMPFREQ	10
RECYCLEBLOCKS	0	REBINFREQ	100
REMOTEPARTDEL	0.0	REPARTFREQ	10
RHODUMP	FALSE	RNGTYPE	RANDOM
SCSOLVEFREQ	1	SEED	123456789
STATDUMPFREQ	10
TELL	FALSE	TRACE	FALSE
VERSION	unset	WARN	TRUE

Legacy defaults varied by OPAL release and mode. Preserve the version tag and the exact executable revision when reproducing an older calculation.