9 Control Statements

View: OPAL OPALX Both

This chapter collects the commands that control OPAL and OPALX execution, global options, variables, file inclusion, and simple flow control inside the input language.

9.1 Getting Help

9.1.1 `HELP` Command

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

HELP;                 // Help on the HELP command itself
HELP, NAME=label;     // Show attribute types of label
HELP, label;          // Shortcut form

Examples:

HELP;
HELP, NAME=FIELDSOLVER;
HELP, FIELDSOLVER;

9.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.

9.3 `OPTION` Statement

The OPTION command controls global execution behavior and a small set of global runtime parameters.

OPTION, VERSION=integer, ECHO=logical, INFO=logical, TRACE=logical,
        WARN=logical, SEED=real, PSDUMPFREQ=integer,
        STATDUMPFREQ=integer, SPTDUMPFREQ=integer,
        REPARTFREQ=integer, REBINFREQ=integer, TELL=logical;

The full set of supported options is larger than the compact syntax line above. In practice, the most important ones are:

VERSION: required input-file compatibility tag. The common encoding is Mmmpp, where M is the major version, m the minor version, and p the patch version.
ECHO: echo input lines to standard error.
INFO: enable or suppress informational messages.
TRACE: enable execution tracing.
WARN: enable or suppress warnings.
TELL: print the current option settings.
SEED: select the random-number seed. SEED=-1 uses the current time and is not portable.
RNGTYPE: random-number generator selection. The default is RANDOM; quasi-random generators such as HALTON, SOBOL, and NIEDERREITER are also supported.
ASCIIDUMP: switch loss and diagnostic element output from HDF5 to ASCII for the supported element families.
AUTOPHASE: controls the accuracy of the cavity auto-phasing search. Setting it to 0 disables the search.
PSDUMPFREQ: phase-space dump frequency.
STATDUMPFREQ: statistics dump frequency.
SPTDUMPFREQ: single-particle trajectory dump frequency in OPAL-cycl.
REPARTFREQ: repartition frequency for load balancing.
SCSOLVEFREQ: space-charge solve frequency reuse option for selected integrators.
ENABLEHDF5, ENABLEVTK: globally enable or disable HDF5 and VTK output support.

9.3.1 OPAL / OPALX differences

In the legacy OPAL manual, the particle-deletion frequency option is named BOUNDPDESTROYFQ. It controls the frequency for deleting particles that are too far away from the center of the beam in OPAL-cycl. Its default value is 10.

In OPALX, the corresponding option name is BOUNDPDESTROY. It governs how many sigmas away particles are deleted. Its default value is 10.

OPALX also adds:

QM_MODE

control how particle charge and mass are stored internally.

SINGLE: one shared charge and mass per container
ATTRIBUTES: per-particle charge and mass attributes

9.3.2 Default settings

Option	Default
`AMR`	`FALSE`
`AMR_REGRID_FREQ`	`10`
`AMR_YT_DUMP_FREQ`	`10`
`ASCIIDUMP`	`FALSE`
`AUTOPHASE`	`6`
`BEAMHALOBOUNDARY`	`0.0`
`BOUNDPDESTROYFQ` / `BOUNDPDESTROY`	`10`
`CLOTUNEONLY`	`FALSE`
`COMPUTEPERCENTILES`	`FALSE`
`CSRDUMP`	`FALSE`
`CZERO`	`FALSE`
`DELPARTFREQ`	`1`
`DUMPBEAMMATRIX`	`FALSE`
`EBDUMP`	`FALSE`
`ECHO`	`FALSE`
`ENABLEHDF5`	`TRUE`
`ENABLEVTK`	`TRUE`
`HALOSHIFT`	`0.0`
`IDEALIZE`	`FALSE`
`INFO`	`TRUE`
`LOGBENDTRAJECTORY`	`FALSE`
`MEMORYDUMP`	`FALSE`
`MINBINEMITTED`	`10`
`MINSTEPFORREBIN`	`200`
`MTSSUBSTEPS`	`1`
`NLHS`	`1`
`NUMBLOCKS`	`0`
`PSDUMPEACHTURN`	`FALSE`
`PSDUMPFRAME`	`GLOBAL`
`PSDUMPFREQ`	`10`
`QM_MODE`	`SINGLE` (OPALX)
`RECYCLEBLOCKS`	`0`
`REBINFREQ`	`100`
`REMOTEPARTDEL`	`0.0`
`REPARTFREQ`	`10`
`RHODUMP`	`FALSE`
`RNGTYPE`	`RANDOM`
`SCSOLVEFREQ`	`1`
`SEED`	`123456789`
`SPTDUMPFREQ`	`1`
`STATDUMPFREQ`	`10`
`TELL`	`FALSE`
`TRACE`	`FALSE`
`VERSION`	`none`
`WARN`	`TRUE`

9.4 Parameter Statements

9.4.1 Variable Definitions

OPAL supports real scalars, real vectors, and logical variables.

Real Scalar Variables

REAL variable-name = real-expression;

The older form

REAL variable-name := real-expression;

is accepted for backward compatibility.

The variable is defined symbolically: whenever a quantity on the right-hand side changes, the variable is recomputed. Circular definitions are not allowed.

Examples:

REAL GEV = 100;
P0 = GEV;

P0 is a reserved global reference momentum used to normalize magnetic-field coefficients.

Real Vector Variables

REAL VECTOR variable-name = vector-expression;

This creates a symbolic real vector. In modern OPAL syntax the REAL keyword is mandatory for vector declarations.

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;

9.4.2 Symbolic Constants

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

REAL CONST label: CONSTANT = real-expression;

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

Example:

CONST IN = 0.0254;

9.4.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);

9.4.4 Assignment to Variables

To force immediate evaluation and assign the resulting value as a constant, use EVAL(...):

variable-name = EVAL(real-expression);

This behaves like assignment in C or Fortran.

Example:

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

9.4.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, for tabulating expressions, and for using OPAL as a programmable calculator.

Example:

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

9.5 Miscellaneous Commands

9.5.1 `ECHO` Statement

ECHO, MESSAGE=message;
ECHO, message;

The given string is written immediately to the echo stream.

9.5.2 `SYSTEM`

SYSTEM, CMD=string;
SYSTEM, string;

SYSTEM executes an operating-system command on a single process, then returns control to OPAL.

Example:

SYSTEM, "ls -l";

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

9.5.3 `PSYSTEM`

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

9.6 `TITLE` Statement

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

TITLE sets the page header used for subsequent output pages. Before the first TITLE statement, the page header is empty.

9.7 File Handling

9.7.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";

9.7.2 `init.opal`

Before the main input file is processed, OPAL 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.

9.8 `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.

9.9 `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.

9.10 `MACRO`: Macro Statements

Macros provide subroutine-like token substitution.

Definitions:

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

Calls:

name(actuals);
name();

The actual arguments replace all occurrences of the corresponding formal names inside the stored token list.

Example:

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

DOIT(): MACRO {
   DYNAMIC, LINE=RING, FILE="DYNAMIC.OUT";
}

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

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

9.1 Getting Help

9.1.1 HELP Command

9.2 STOP / QUIT

9.3 OPTION Statement

9.3.1 OPAL / OPALX differences

9.3.2 Default settings

9.4 Parameter Statements

9.4.1 Variable Definitions

Real Scalar Variables

Real Vector Variables

Logical Variables

9.4.2 Symbolic Constants

9.4.3 Vector Values

9.4.4 Assignment to Variables

9.4.5 VALUE: Output of Expressions

9.5 Miscellaneous Commands

9.5.1 ECHO Statement

9.5.2 SYSTEM

9.5.3 PSYSTEM

9.6 TITLE Statement

9.7 File Handling

9.7.1 CALL Statement

9.7.2 init.opal

9.8 IF: Conditional Execution

9.9 WHILE: Repeated Execution

9.10 MACRO: Macro Statements

9.1.1 `HELP` Command

9.2 `STOP` / `QUIT`

9.3 `OPTION` Statement

9.4.5 `VALUE`: Output of Expressions

9.5.1 `ECHO` Statement

9.5.2 `SYSTEM`

9.5.3 `PSYSTEM`

9.6 `TITLE` Statement

9.7.1 `CALL` Statement

9.7.2 `init.opal`

9.8 `IF`: Conditional Execution

9.9 `WHILE`: Repeated Execution

9.10 `MACRO`: Macro Statements