45  File Formats

OPALX consumes statement-oriented .in files plus model-specific field maps and particle distributions. It produces statistics, particle, field, loss, and diagnostic data through several writers.

The audited formats currently documented are:

Other output formats remain planned until each reader or writer has been traced in the current source. A legacy OPAL variant is not an OPALX compatibility guarantee.

Each completed format page will specify:

45.1 Spectral tune files

RUN,SPECTRALTUNES=TRUE writes one summary CSV and two detailed CSV files for each TUNEINITIAL row. The basename is the input basename used by the run. Row indices start at zero.

File Rows Columns
<base>-tunes.csv One row per TUNEINITIAL triple. energy_MeV, radius_m, pr, nu_r, nu_y, grid_spacing, legacy_turns, samples, max_relative_energy_drift
<base>-tune-<row>-samples.csv One row per retained sample for that tune row. time_s, delta_r_m, y_m, reference_angle_rad
<base>-tune-<row>-spectrum.csv One row per tune grid point. tune, radial_power, vertical_power

The summary energy is written in MeV even though BEAM.TUNEINITIAL uses GeV. pr is radial momentum in units of mc. legacy_turns is the nominal turn count used by the spectral analysis, and samples is the number of sampled signal values. Sample rows contain pre-step signal values and the accumulated reference angle used for turn-context diagnostics.

These files are rank-zero text diagnostics for the spectral tune calculation. They are independent of normal particle phase-space output.

45.2 COF result JSON

The closed-orbit command writes one JSON object when OUTPUT="orbit.json" is specified. OUTPUT is the exact filename: OPALX adds no extension and rejects an existing target or an explicitly empty filename. Omitting OUTPUT produces no COF result file. Only rank zero writes, after successful convergence; there are no text or orbit-CSV sidecars.

Let \(u=(x,p_x,y,p_y)\) be the section coordinates and \(T(u)\) the directed fixed-energy return map. Positions use metres and momenta use mechanical \(p/(mc)\), rather than slopes.

Key Shape or value Meaning
converged Boolean true for a successfully written result.
dt_s Number Configured ray timestep in seconds.
energy_MeV Number Reference kinetic energy in MeV.
coordinates Four numbers Solved section coordinates \(u\), ordered \((x,p_x,y,p_y)\).
residual Four numbers \(T(u)-u\), in the same order and units.
matrix Four rows of four numbers \(M=\partial T/\partial u\) at the solution, not the Newton matrix \(M-I\). Entry \((i,j)\) has units \(u_i/u_j\).
eigenvalues Four [real, imaginary] pairs Eigenvalues of the full coupled matrix.
stability String STABLE, UNSTABLE, NON_UNIT_CIRCLE, or MARGINAL.
near_integer Boolean Whether the eigenanalysis flags a phase near an integer.
fractional_modes Array of objects Each object contains tune and complement; both are null for an off-unit-circle mode. No integer branch or transverse-plane label is assigned.
relative_energy_drift Number Signed relative kinetic-energy change from launch to return.
time_s Number Laboratory launch time in seconds, not the return time or revolution period.
position_m Three numbers Full laboratory launch position \((X,Y,Z)\).
momentum_mc Three numbers Full laboratory launch momentum \((p_X,p_Y,p_Z)/(mc)\).
line String Selected RING name.
species String Particle species name.
mass_eV Number Rest-mass energy in eV.
charge_e Number Charge in units of the elementary charge.
section_origin_m Three numbers Laboratory position of the section origin.
section_rotation_wxyz Four numbers Unit quaternion (w,x,y,z) rotating laboratory vectors into the section frame.

The section frame is distinct from the orbit-local bunch frame used by TRACK.INITIALORBIT: the latter is centred at the solved launch and aligned with its momentum. The JSON format is experimental and has no schema-version field. It is a diagnostic export, not a checkpoint or an import interface for INITIALORBIT; handover uses the named result held in memory. Iteration details and return timing are available in the solver’s console report.

45.3 Checkpoint and restart

Enable periodic checkpoints in the input file:

OPTION, CHECKPOINTFREQ=1000;

After each 1000 completed global tracking steps, OPALX writes <input-basename>_checkpoint.h5. It first writes a same-directory .tmp file and replaces the checkpoint only after every MPI rank closes it. Each new checkpoint replaces the previous one.

Restart with the input file that defines the continuation and the saved checkpoint:

opalx --restart simulation_checkpoint.h5 simulation.in

The checkpoint file may be given either before or after the input file. For example, the following forms are equivalent:

opalx simulation.in --restart simulation_checkpoint.h5
opalx --restart simulation_checkpoint.h5 simulation.in
opalx --restart simulation_checkpoint.h5 simulation.in --info 1

If --restart is given without a checkpoint filename, OPALX derives the checkpoint name from the input filename by removing the extension and appending _checkpoint.h5. For example, opalx simulation.in --restart reads simulation_checkpoint.h5.

The input file still defines the beamline, beams, field solver, emission-source lists, and complete TRACK step-size schedule. OPALX restores the saved particle and tracker state instead of sampling the initial distributions. A restart may use a different number of MPI ranks; saved global particle tables are repartitioned over the ranks in the new run.

The checkpointed step-size segment and completed-step offset within that segment are the authoritative restart position. OPALX selects that segment directly and executes only the part of its MAXSTEPS budget that remains. This is distinct from the completed global step: an earlier segment may reach its ZSTOP without consuming all of its MAXSTEPS, so the global step alone cannot identify the current segment. The global step remains the cumulative counter used for diagnostics and checkpoint frequency.

The restart input must provide a compatible TRACK schedule. The saved segment must exist, its completed-step offset must be valid for that segment’s MAXSTEPS, and its DT must match the time step stored in the checkpoint. Changing MAXSTEPS in an earlier segment does not remap the checkpoint to a different schedule position.

The checkpoint contains:

  • Format version, completed global step, simulation time, and time step.
  • Current step-size segment and the completed-step offset within it. Restart positioning uses these values directly.
  • Every particle container’s position, momentum, per-particle time step, ID, bin, charge, mass, species, and optional spin.
  • Per-container path position, reference position and momentum, reference-to-lab transform, and current segment-stop state.
  • Autophased RF-cavity phases.

Checkpoint writing does not depend on phase-space output: ENABLEHDF5=FALSE and PSDUMPFREQ=0 do not disable it. On restart, OPALX rewinds the original per-container .stat files to the saved path positions and appends the continuation. Corresponding later .lbal rows are also removed before appending. Existing phase-space .h5 files are likewise rewound to the saved simulation time and appended under their original names. If an original output file is unavailable, OPALX creates it and writes the restarted portion. Restart also selects the process-wide APPEND output mode, which is used by monitor, loss, design-path, and other output writers that support continued output.

Current restrictions:

  • A restart cannot execute COF, use TRACK.INITIALORBIT, or enable explicit turn-count stopping or EKINSTOP. See Tracking.
  • Time-dependent emission, delayed one-shot sources, and EMITTEDFROMFILE cannot yet be restarted because sampler progress and random state are not stored.
  • Stochastic global processes such as DECAY cannot yet be restarted because their random-pool state is not stored.
  • Iterative field-solver history is rebuilt after restart. Results remain a valid continuation, but the last bits can differ from an uninterrupted run or when the MPI rank count changes because reduction order and solver initial guesses can change.
  • Checkpoint schema compatibility is explicit: an unsupported format version is rejected instead of being interpreted as a normal diagnostic HDF5 file.

OPALX reports the saved global step and time after a successful restore. A checkpoint already at the end of the configured step schedule is accepted as a completed run with no remaining integration steps.