8 Input Language and Execution

OPALX reads a MAD-inspired, statement-oriented language. This page is the overview: it explains what can appear in an input file and directs readers to the maintained guide for each interface. Attribute-level details belong on the linked pages and in the Command Reference.

The catalog was checked against the parser and the registrations in opalx/src/OpalConfigure/Configure.cpp at OPALX revision d1e762f15a2a.

8.1 A simulation at a glance

Like the NumPy user guide, the manual first groups concepts by what readers are trying to accomplish and then provides a complete lookup catalog.

Reuse expressions

Values and variables

Define named real, Boolean, string, and vector values before using them in later attributes. See Command Format for expression syntax and Control Statements for executable language constructs.

Create particles

Beam and sources

Combine a distribution, one or more emission sources, and a beam definition.

Build the machine

Elements and lines

Create named elements, then assemble them into a LINE in tracking order.

Choose self-fields

Solver structures

Configure a field solver and, when needed, a reusable binning definition.

Run the model

Tracking block

Use TRACK, RUN, and ENDTRACK to bind the line, beam, sources, time step, and solver to one execution.

Control the run

Actions and options

Set global runtime options, compose input files, inspect values, and terminate parsing with the control statements.

8.2 Core syntax

Statements normally end with a semicolon. Names are case-insensitive in normal OPALX input, while string values and file paths retain their contents. The complete lexical, expression, array, selection, and constraint rules are in Command Format; the formal grammar is in Appendix B.

Form	Example	Meaning
Action	`OPTION, INFO=TRUE;`	Execute a registered command immediately.
Named definition	`Beam1: BEAM, PARTICLE=ELECTRON, ...;`	Clone a registered class, assign attributes, and store it under a name.
Typed value	`REAL length = 0.5;`	Define a scalar, string, Boolean, or vector value for later expressions.
Immediate assignment	`length = 0.5;`	Evaluate the right-hand expression when the assignment is parsed.
Expression assignment	`momentum := beta * gamma;`	Store an expression that can be reevaluated when its dependencies change.
Attribute assignment	`Beam1->BCURRENT = 0.1;`	Update an existing object’s attribute; `name->ATTR[n]` updates an array component.
Beamline	`L1: LINE=(D1, Q1, D2);`	Assemble named elements in traversal order.
Tracking block	`TRACK, ...; RUN, ...; ENDTRACK;`	Enter the tracking parser, execute a run, and return to the main parser.
Compound block	`{ statement; statement; }`	Group statements for `IF`, `WHILE`, or a macro body.

TITLE, STRING="Minimal beamline study";

REAL cell_length = 1.0;
D1: DRIFT, L=cell_length;
CELL: LINE=(D1);

TRACK, LINE=CELL, BEAM=BEAM1, MAXSTEPS={10}, DT={1.0e-11};
  RUN, METHOD="PARALLEL", FIELDSOLVER=FS1;
ENDTRACK;
QUIT;

This fragment illustrates ordering and syntax, not a complete runnable model. The Worked Input Files contain complete examples with beam, distribution, source, and field-solver definitions.

8.3 Parser-native structures

These forms are implemented directly by the parser rather than registered as simulation objects.

Structure	Short explanation
`BOOL name = expression;`	Define a Boolean value. `CONSTANT BOOL` and `CONST BOOL` are accepted equivalent forms.
`REAL name = expression;`	Define or update a real scalar variable. Omitting `REAL` is allowed only when the name already exists.
`CONST name = expression;`, `CONSTANT REAL name = expression;`	Define a real constant that cannot be redefined. `CONST` and `CONSTANT` are synonyms.
`STRING name = expression;`	Define a string value. `CONSTANT STRING` and `CONST STRING` are also accepted.
`VECTOR name = {...};`, `REAL VECTOR name = {...};`	Define a real-valued array. `CONSTANT VECTOR` and `CONSTANT REAL VECTOR` are also accepted.
`name->ATTRIBUTE = expression;`	Assign an existing object’s attribute; use `:=` to retain a non-constant expression.
`SHARED name: CLASS, ...;`	Set the defined object’s shared flag. This is an advanced ownership feature whose effect depends on the object class.
`name(arguments): MACRO { ... }`	Define a parameter-substitution macro; `name(actuals);` expands and executes it.
`IF (condition) statement ELSE statement`	Execute one of two statements. Use compound blocks for more than one statement per branch.
`WHILE (condition) statement`	Re-evaluate a Boolean condition and repeat one statement or compound block.
`{ ... }`	Group multiple statements into one compound statement.

8.4 Reusable simulation definitions

These named objects describe the bunch and the numerical structures used by a run. Define dependencies before the object that refers to them.

Definition	Short explanation	Maintained guide
`BEAM`	Defines particle species, reference energy or momentum, current, frequency, allocation, source list, and global processes.	Beam
`DISTRIBUTION`	Defines how initial positions, momenta, or emission times are sampled or read from a file.	Distribution
`EMISSIONSOURCE`	Couples one distribution to offsets, timing, emission energy, and image-charge settings.	Emission source
`EMISSIONSOURCELIST`	Stores an ordered, non-empty list of named emission sources for `BEAM.SOURCES` or `TRACK.SOURCES`.	Emission-source list
`FIELDSOLVER`	Selects the Poisson backend, mesh, decomposition, boundary conditions, optional binning, and image-charge mode.	Field solver
`BINNING`	Configures the longitudinal histogram used by binned space charge.	Binning

8.5 Beamline definitions

LINE is the lattice container. The remaining entries are every element class registered by the current executable. Only source-audited element pages are linked; plain-text entries are registered but do not yet have a maintained user-guide section.

Definition	Short explanation	Maintained guide
`LINE`	Orders named elements into the lattice selected by `TRACK.LINE`.	Beam Lines
`DRIFT`	Field-free propagation over a finite length.	DRIFT
`CONSTANTEFIELDCAVITY`	Applies a spatially uniform, constant electric field inside the element.	CONSTANTEFIELDCAVITY
`QUADRUPOLE`	Defines a thick normal or skew quadrupole.	QUADRUPOLE
`MULTIPOLE`	Defines a thick hard-edge multipole from normal and skew strength arrays.	MULTIPOLE
`MULTIPOLET`	Defines a combined-function multipole with fringe and placement controls.	MULTIPOLET
`SOLENOID`	Defines a solenoid from normalized strength or a field map.	SOLENOID
`RFCAVITY`	Defines a standing-wave or single-gap RF cavity, normally from a field map.	RFCAVITY
`TRAVELINGWAVE`	Defines a traveling-wave RF structure with cell and phase-advance controls.	TRAVELINGWAVE
`RBEND`	Defines a rectangular bending magnet.	RBEND
`SBEND`	Defines a sector bending magnet.	SBEND
`VERTICALFFAMAGNET`	Defines a vertical fixed-field alternating-gradient magnet.	VERTICALFFAMAGNET
`VARIABLE_RF_CAVITY`	Defines an RF cavity whose phase, amplitude, and frequency are provided by named time models.	VARIABLE_RF_CAVITY
`LASER`	Defines a passive analytic laser pulse with direction and polarization.	LASER
`MONITOR`	Records beam diagnostics at an element location.	MONITOR
`PROBE`	Records particle crossings over a configured probe span and accumulates peak diagnostics.	PROBE
`MARKER`	Marks a named lattice location without applying a field.	MARKER

8.6 Time-dependence definitions

These registered definitions provide named functions used by time-dependent RF and scaling attributes. Dedicated parameter pages have not yet been written.

Definition	Short explanation
`POLYNOMIAL_TIME_DEPENDENCE`	Defines a polynomial in time from coefficients.
`SINUSOIDAL_TIME_DEPENDENCE`	Defines a sum of sinusoidal components with frequency, phase, amplitude, and offset arrays.
`SPLINE_TIME_DEPENDENCE`	Defines linear or smoothed cubic interpolation through time-value samples.

8.7 Tracking-block structures

The TRACK action switches to a small nested command set. RUN and ENDTRACK are valid only inside that block.

Structure	Short explanation	Maintained guide
`TRACK`	Selects the lattice, beam or beams, source list, stepping limits, time integrator, and tracking interval.	Tracking
`RUN`	Constructs and executes the selected parallel tracking method and field solver.	Tracking
`ENDTRACK`	Leaves tracking mode and returns input processing to the main parser.	Tracking

8.8 Executable actions

Actions run when the parser encounters them; unlike named definitions, they do not merely describe a later simulation object.

Action	Short explanation	Maintained guide
`OPTION`	Sets global logging, output, random-number, space-charge, load-balancing, and synchronization behavior.	Runtime options
`TITLE`	Sets the calculation title.	Control statements
`CALL`	Temporarily reads and executes another input file, then resumes the caller.	Control statements
`ECHO`	Writes a message to the OPALX echo stream.	Control statements
`HELP` or `CLASS?`	Prints parser help for a registered class or object.	Control statements
`VALUE`	Evaluates and prints one or more real expressions.	Control statements
`SELECT`	Selects lattice positions by range, class, type, or name pattern for subsequent selection-aware commands.	Control statements
`DUMPEMFIELDS`	Schedules electromagnetic-field sampling on a Cartesian or cylindrical space-time grid.	Diagnostics and output
`SYSTEM`	Runs an operating-system command on rank zero.	Control statements
`PSYSTEM`	Runs an operating-system command on every rank. Use with particular care in MPI jobs.	Control statements
`STOP`	Stops further input processing.	Control statements
`QUIT`	Stops input processing; conventionally the final statement in an input file.	Control statements

8.9 Execution order and name resolution

OPALX processes input in order. Values, objects, and macros must normally be defined before a later statement refers to them. Named definitions are stored in the main object directory; actions are cloned, parsed, and executed immediately. Before an action executes, OPALX updates objects whose expression dependencies changed.

Within a normal simulation the practical order is:

Set OPTION and define reusable values.
Define distributions, emission sources, an emission-source list, and a beam.
Define elements and assemble a LINE.
Define optional BINNING and the selected FIELDSOLVER.
Enter TRACK, issue RUN, and close the block with ENDTRACK.
Finish with QUIT.