4 Run a First Simulation
Start with an input file from the maintained OPALX regression suite. Those inputs are executable specifications and are checked continuously against the current parser and physics implementation.
If you already have an OPAL, ASTRA or Elegant model, toOPALX.py can prepare an OPALX input file. See Section 4.4 for the download, supported inputs, conversion commands and model-review requirements.
4.1 Run a small regression input
From the root of the OPALX checkout, after building the serial executable:
export OPALX_EXE="$PWD/build_serial/src/opalx"
git clone https://github.com/OPALX-project/regression-tests-x.git
mkdir -p run-drift
cp regression-tests-x/RegressionTests/Drift-1-fromfile/Drift-1-fromfile.in run-drift/
cp regression-tests-x/RegressionTests/Drift-1-fromfile/distr-gauss.txt run-drift/
cd run-drift
"$OPALX_EXE" Drift-1-fromfile.in --info 2This case tracks 1,000 electrons through a drift with self-fields disabled (FIELDSOLVER, TYPE=NONE). Keep distr-gauss.txt beside the input: the particle distribution is read from that file. The run writes Drift-1-fromfile.stat; check that it completes successfully and produces statistics.
This is a smoke test, not an automated numerical regression comparison. The regression repository also supplies a .rt file defining checked metrics and tolerances, and a reference/ directory with reference results. See the regression repository for its structure and the dashboard below for current results. Do not regenerate references merely to make a failing check pass.
The regression repository evolves independently of OPALX releases. Record its revision with git -C ../regression-tests-x rev-parse HEAD when reporting a result; its default branch is not a frozen 1.0.0 test suite.
4.2 Launch on a GPU
For a multi-GPU run, map each MPI rank to a device:
srun /path/to/build_cuda/src/opalx example.in \
--info 2 --kokkos-map-device-id-by=mpi_rank4.3 What to check
- The startup banner identifies the build and execution backend.
- Parser errors name the statement and location that could not be read.
- Statistics and particle outputs depend on the input-file options and output commands.
- A nonzero exit status means the run did not complete successfully.
The regression-test dashboard shows which inputs currently pass. Input-file compatibility is still being cataloged, so a regression input is safer than copying an example from the historical OPAL manual. Continue with the three complete Worked Input Files for progressively more detailed starting points.
4.4 Convert OPAL, ASTRA and Elegant inputs
toOPALX.py converts supported OPAL, ASTRA and Elegant input files into OPALX inputs. It prepares the input and its companion files, but does not run a simulation.
The purpose is to help in converting and not to prepare a bullet-proved input file.
4.4.1 Download and requirements
Download toOPALX.py, version 1.4.2 (SHA-256 checksum). This is the frozen release of 1 November 2026.
The single script requires Python 3.9 or newer and uses only the Python standard library.
4.4.2 Prepare the source model
Keep the source entry file, included lattice files, particle data and field maps in one case directory. References must be literal relative filenames inside that directory; computed filenames, absolute or escaping references and symbolic links are rejected. The converter preserves the source files and copies the dependencies needed by the candidate.
Choose the source format explicitly with --mode:
| Mode | Required inputs | Main supported scope |
|---|---|---|
opal |
An entry .in file and its recursive CALL includes, particle files and maps |
Recognized legacy syntax, beam/distribution/source attachments, supported elements and guarded PSI ring/RF placement rules. Unknown commands and explicitly blocked settings stop conversion. |
astra |
An ASTRA input, an injected equal-weight electron snapshot with a common clock, and referenced maps | Straight RF/solenoid/quadrupole models with circular apertures, plus restricted single-plane dipole-only beamlines. Cathode emission and arbitrary mixed lattices are outside this release. |
elegant |
A supported .ele command file, a literal .lte lattice and one counted SDDS1 ASCII particle page |
One injected electron bunch and one pass through supported drifts, aligned quadrupoles, markers, zero-gap/zero-edge sector bends and restricted standing-wave RFCA models. Binary or multipage SDDS, RPN and general Elegant workflows are unsupported. |
ASTRA and Elegant conversions always write FIELDSOLVER, TYPE=NONE, even when the source enables space charge. OPAL conversions retain the source solver settings. Review the solver and boundary conditions before using a converted input for a space-charge study.
The element list and its restrictions are available directly from the frozen script. For example:
python3 toOPALX.py --help --more --mode opal
python3 toOPALX.py --help --more --mode astra
python3 toOPALX.py --help --more --mode elegant4.4.3 Convert an input
Save the downloaded script beside your case directories. Create a separate output directory, then use the command for your source format:
mkdir -p converted
python3 toOPALX.py --mode opal \
--infile opal-case/lattice.in --outfile converted/opal.in
python3 toOPALX.py --mode astra \
--infile astra-case/model.in --outfile converted/astra.in
python3 toOPALX.py --mode elegant \
--infile elegant-case/run.ele --outfile converted/elegant.inReplace the example filenames with your own. The output parent directory must exist. The output entry file, companion directory and report must all be new; existing destinations are never overwritten. Use a new output name or directory for each attempt.
To inspect an OPAL case without writing files:
python3 toOPALX.py --mode opal --infile opal-case/lattice.in --inspectInspection prints diagnostic JSON and returns a nonzero status for an unsupported case. Normal conversion prints a short status and the output and report filenames. Add --json to a conversion command when a script needs the full report on stdout. Unsupported input or invalid arguments return status 2; a completed conversion returns 0, including cases that require review. No candidate is published after a refused conversion.
4.4.4 Output files and the conversion report
For --outfile converted/opal.in, keep these outputs together in converted/:
| Output | Contents |
|---|---|
opal.in |
Candidate OPALX entry file. |
opal.in.assets/ |
Copied maps, particle files, included inputs and companion metadata. Relative references in the candidate point here. |
opal.in.report.json |
Complete conversion report, source locations, changes, review notes, approximations, dependency relocation and output fingerprints. |
The full JSON report is saved even when terminal JSON is suppressed. The asterisk-framed terminal summary highlights drift replacements, model approximations, particle-file changes and cyclotron placement warnings. Check the report’s status, unavailable_elements, model_approximations, asset_migrations, placement_warnings and backend review notes.
4.4.5 Model changes and current limits
Conversion can change the model. In particular:
- Some element types outside the verified converter scope become drifts when their length and placement can be retained. Their fields, kicks or other interactions are omitted; every replacement is reported. A drift replacement is not an implementation of the original element.
- Legacy
SELECTand particle-matter declarations/attachments are removed. Their interaction physics is not retained. Gas stripping andUNDULATORremain unsupported. - A legacy
BINOMIALdistribution becomesGAUSSwith a reported approximation. Its binomial shape exponents are removed, while other width and correlation expressions are retained without rescaling. Tails and higher moments are not preserved. - SBEND
DESIGNENERGYand nonzero or unprovedE1/E2remain rejected. Provably zero faces can be omitted. Newer RBEND features do not provide a general replacement for these sector-bend settings. - PSI cyclotron sector expansion and RF-gap placement require review of the common centre, map orientation, seams and RF poses. Legacy initial conditions and RF timing still need migration; retained report metadata does not configure those settings in OPALX. Native single-gap tracking is currently limited to one unpolarized positive proton in one container on one MPI rank, with
FIELDSOLVER, TYPE=NONEand no restart. See the cyclotron gap model.
A review-required result therefore needs checking before tracking. Compare particle species, charge, population, units and source coordinates; then check field strengths, map orientation, geometry, RF phase/timing and solver settings. Retain the original code’s results or another trusted reference for a numerical comparison. A successful conversion alone is not a regression test pass, and references or tolerances should not be changed merely to make the comparison pass.
After that review, launch OPALX from the output directory so its relative asset references resolve. For the OPAL example, using the executable set in the regression smoke test:
cd converted
"$OPALX_EXE" opal.in --info 2