10  Control Statements

These statements control OPALX parsing, variables, file inclusion, and simple flow. Global runtime settings are documented separately under OPTION.

10.1 Getting Help

10.1.1 HELP Command

The HELP command prints information about a command or object type.

HELP;                 // Help on the HELP command itself
HELP, label;          // Show help for label
label?;               // Equivalent parser help form

Examples:

HELP;
HELP, FIELDSOLVER;
FIELDSOLVER?;

10.2 STOP / QUIT

STOP;
QUIT;

STOP and QUIT terminate execution of the current input stream. In a nested CALL file they return to the caller; in the main input file they end the run. Any statements after STOP or QUIT in the same file are ignored.

10.3 Parameter Statements

10.3.1 Variable Definitions

OPALX supports real scalars, real vectors, logical variables, and string constants.

Real Scalar Variables

REAL variable-name = real-expression;

The expression form

REAL variable-name := real-expression;

retains the expression tree so it can be reevaluated. With =, the right-hand side is evaluated immediately.

Circular expression definitions are not allowed.

Examples:

REAL GEV = 100;
P0 = GEV;

P0 is a reserved global reference momentum in \(\mathrm{GeV}/c\) used to normalize magnetic-field coefficients. Its default is 1.0; set it consistently with the intended reference rigidity.

Real Vector Variables

REAL VECTOR variable-name = vector-expression;

This creates a real vector. VECTOR without REAL is also accepted by the current parser.

Examples:

REAL VECTOR A = TABLE(10, #);
REAL VECTOR B = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};

Logical Variables

BOOL variable-name = logical-expression;

Example:

BOOL FLAG = X != 0;

10.3.2 Symbolic Constants

Built-in mathematical and physical constants are provided. Additional constants can be defined with:

REAL CONST label = real-expression;

The value is evaluated immediately when the line is read and cannot be redefined later.

Example:

CONST IN = 0.0254;

10.3.3 Vector Values

Vectors can also be defined directly from expressions:

REAL VECTOR vector-name = vector-expression;

Examples:

VECTOR A_AMPL = {2.5e-3, 3.4e-2, 0, 4.5e-8};
VECTOR A_ON = TABLE(10, 1);

10.3.4 Assignment to Variables

= already evaluates the right-hand side immediately. EVAL(...) can also freeze a subexpression when it appears within a deferred (:=) expression:

variable-name := EVAL(real-expression);

The assigned variable remains assignable; EVAL makes its argument’s value constant within the stored expression.

Example:

REAL X = 0;
WHILE (X <= 0.10) {
  VALUE, VALUE={X};
  X = EVAL(X + .01);
}

10.3.5 VALUE: Output of Expressions

VALUE, VALUE = expression-vector;

VALUE evaluates its arguments with the current variable state and prints the result. It is useful for debugging and tabulating expressions.

Example:

REAL A = 4;
VALUE, VALUE = TABLE(5, #*A);
REAL P1 = 5;
REAL P2 = 7;
VALUE, VALUE = {P1, P2, P1*P2-3};

10.4 Miscellaneous Commands

10.4.1 ECHO Statement

ECHO, MESSAGE=message;
ECHO, message;

The given string is written immediately to the echo stream.

10.4.2 SYSTEM

SYSTEM, CMD=string;
SYSTEM, string;

SYSTEM executes an operating-system command on rank zero, then returns control to OPALX.

Example:

SYSTEM, "ls -l";

It can also be used to generate helper files externally and then include them with CALL.

10.4.3 PSYSTEM

PSYSTEM is the parallel counterpart to SYSTEM: the command is executed on all ranks instead of only one.

10.5 TITLE Statement

TITLE, STRING=page-header;
TITLE, page-header;
TITLE, STRING="";

TITLE stores the calculation title used by subsequent output.

10.6 File Handling

10.6.1 CALL Statement

CALL, FILE=file-name;
CALL, file-name;

CALL switches input processing to another file. Reading continues there until end-of-file or a STOP / QUIT, after which control returns to the caller.

Example:

CALL, FILE="structure";
CALL, "structure";

10.6.2 init.opal

Before the main input file is processed, OPALX executes $HOME/init.opal if it exists. This behaves like an implicit

CALL, FILE="$HOME/init.opal";

at the beginning of every run.

Typical uses are:

  • shared OPTION settings
  • reusable MACRO definitions
  • global physics constants

Because it is implicit, it can also be a source of confusion when switching machines. For portable input decks, an explicit CALL is often easier to manage.

10.7 IF: Conditional Execution

The input language supports C-like conditional execution:

IF (logical) statement;
IF (logical) statement; ELSE statement;
IF (logical) { statement-group; }
IF (logical) { statement-group; }
  ELSE { statement-group; }

Statements inside the block still end with semicolons, but the closing brace does not.

10.8 WHILE: Repeated Execution

Repeated execution is expressed as:

WHILE (logical) statement;
WHILE (logical) { statement-group; }

The logical condition is re-evaluated on every iteration. Some variable inside the loop must change in a way that allows termination.

10.9 MACRO: Macro Statements

Macros provide subroutine-like token substitution.

Definitions:

name(formals): MACRO { token-list }
name(): MACRO { token-list }

Calls:

name(actuals);
name();

Each call must supply the same number of actual arguments as formal names. Formal names must be unique, and actual arguments must not be empty. Use name() for a macro with no arguments.

Substitution replaces whole name tokens throughout the body, including names on the left side of assignments. Text inside quoted strings is unchanged. Macros do not introduce a local variable scope: assignments and definitions in the body use the normal input environment.

Commas separate arguments only outside balanced parentheses, square brackets, and braces. A vector literal such as {1, 2, 3} or a function call such as MAX(1, 2) therefore counts as one argument. Missing or mismatched delimiters, duplicate formal names, empty arguments, and argument-count mismatches are errors.

Arguments are inserted as tokens without evaluation or automatic parentheses. For example, substituting 1+2 into 2*X produces 2*1+2, which evaluates to 4. Write 2*(X) in the body, or pass (1+2), when grouping is required. Macro bodies may contain nested macro calls and compound blocks; a definition can be called repeatedly with different arguments.

Example:

SHOWIT(X): MACRO {
   VALUE, VALUE={X};
}

KS(X,Y): MACRO {
   Y = 3e-3*X + 0.5e-3;
}

SHOWIT(PI);
REAL X = 2;
REAL Y;
KS(X,Y);

A macro can accept a vector as a single argument:

SAVE(V): MACRO {
   VECTOR SAVED = V;
}
SAVE({1, 2, 3});