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
OPTIONsettings - reusable
MACROdefinitions - 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});