9  Command Format

OPALX and OPAL use the same MAD-like command grammar. The dialect is close to MAD9.

9.1 Statements and Comments

Input is free format. Statements are tokenized and terminated by semicolons. Comments may be introduced by //, and C-style block comments are also accepted.

General command form:

keyword, attribute, ..., attribute;
label: keyword, attribute, ..., attribute;

The three parts are:

  1. label: optional for executable commands, required for definitions stored for later use
  2. keyword: identifies the command or element type
  3. attribute: one of
attribute-name
attribute-name = attribute-value
attribute-name := attribute-value

= evaluates the expression immediately. := stores the expression and re-evaluates it when dependent values change. A logical attribute may be given without a value, in which case it implies TRUE.

If a labeled command is stored, it can later be re-executed by label only or re-executed with modified attributes.

9.2 Identifiers or Labels

An identifier names a keyword, element, beamline, variable, or array. Unquoted identifiers begin with a letter and may contain letters, digits, periods, and underscores. Quoted identifiers may contain other special characters. Avoid them when downstream post-processing tools require simple names.

Unquoted names are converted to upper case before storage.

9.3 Command Attribute Types

Object attributes are referenced as

object-name->attribute-name
object-name->attribute-name[index]

The attribute categories used throughout OPAL are:

Attribute Type
String
Logical
Real expression
Deferred expression
Place
Range
Constraint
Variable reference
Regular expression
Array
Array of logical
Array of real
Array of string
Array of token lists

9.4 String Attributes

String attributes carry titles, file names, class names, or options. Strings may be quoted with single or double quotes. Concatenation uses &, and the function TO_STRING(X) converts a real expression to a string.

Operator / Function Meaning
X & Y concatenate strings
TO_STRING(X) convert real expression X to a string

Examples:

TITLE, "This is a title for the program run ""test""";
CALL, FILE="save";

REAL X=1;
STRING L2="LEP" & TO_STRING(X+1);

9.4.1 Predefined String Attributes

Many string attributes are restricted to a predefined set of accepted values. Such attributes do not need to be quoted. If the supplied value is not in the allowed set, OPAL raises an exception.

9.5 Logical Expressions

Logical expressions use the same precedence and syntax style as C. They are built from relations combined with && and ||.

Grammar sketch:

relation      ::= TRUE | FALSE | real-expr rel-operator real-expr
rel-operator  ::= == | != | < | > | >= | <=
and-expr      ::= relation | and-expr && relation
logical-expr  ::= and-expr | logical-expr || and-expr
Operator Meaning
X < Y true if X is less than Y
X <= Y true if X is not greater than Y
X > Y true if X is greater than Y
X >= Y true if X is not less than Y
X == Y true if X equals Y
X != Y true if X differs from Y
X && Y true if both are true
X \|\| Y true if at least one is true

Examples:

OPTION, ECHO=TRUE;
OPTION, ECHO;
X>10 && Y<20 || Z==15

9.6 Real Expressions

Any real value may be given as an arithmetic expression. An immediate = assignment requires its operands to be available when the statement is parsed. A retained := expression can use values defined before that expression is evaluated.

Grammar sketch:

real-ref  ::= real-variable |
              real-array[index] |
              object->real-attribute |
              object->array-attribute[index]

table-ref ::= table@place->column-name

primary   ::= literal-constant |
              symbolic-constant |
              # |
              real-ref |
              table-ref |
              function-name(arguments) |
              (real-expression)

factor    ::= primary | primary ^ primary
term      ::= factor | term * factor | term / factor
real-expr ::= term | +term | -term | real-expr + term | real-expr - term

9.7 Operators

Operator Meaning
+X unary plus
-X unary minus
X + Y addition
X - Y subtraction
X * Y multiplication
X / Y division
X ^ Y power

9.8 Real Functions

The OPALX expression parser provides these built-ins:

  • no arguments: RANF(), GAUSS(), SI(), SC(), SO(), GETEKIN()
  • one argument: TRUNC, ROUND, FLOOR, CEIL, SIGN, SQRT, LOG, EXP, SIN, COS, ABS, TAN, ASIN, ACOS, ATAN, TGAUSS, ERF, EVAL
  • two arguments: ATAN2, MAX, MIN, MOD, POW

Functions of arrays:

  • VMAX
  • VMIN
  • VRMS
  • VABSMAX

Random generators inside ordinary expressions may be re-evaluated when their enclosing expressions are evaluated. EVAL(...) can be used to force immediate evaluation and store the result as a constant.

9.9 Operands in Expressions

9.9.1 Literal Constants

Numerical values follow FORTRAN-style literal syntax. Examples:

1, 10.35, 5E3, 314.1592E-2

9.9.2 Symbolic Constants

The predefined symbolic constants include mathematical constants and particle masses:

Name Meaning / Value
PI, TWOPI, RADDEG, DEGRAD, E usual mathematical constants
EMASS, MUMASS, PMASS, DMASS, HMMASS, H2PMASS, ALPHAMASS, CMASS, XEMASS, UMASS predefined particle masses
CLIGHT, AMU speed of light and atomic mass unit
OPALVERSION OPAL version constant
RANK MPI rank

9.9.3 Variable Labels

Global real and vector variables are defined with:

REAL X=expression;
REAL X:=expression;
VECTOR X=vector-expression;
VECTOR X:=vector-expression;

Example:

REAL L=1.0;
REAL X:=L;
D1: DRIFT, L:=X;
D2: DRIFT, L:=2.0-X;

9.9.4 Element or Command Attributes

Attributes can appear directly in arithmetic expressions:

element-name->attribute-name
command-name->attribute-name
element-name->attribute-name[index]
command-name->attribute-name[index]

Example:

D1: DRIFT, L=1.0;
D2: DRIFT, L=2.0-D1->L;

9.9.5 Deferred Expressions and Random Values

Expressions containing random generators may be deferred and sampled when the target command actually executes. Such a value cannot safely be used as an operand inside another deferred expression.

9.10 Element Selection

Element selection is not available in OPAL-T and OPAL-CYCL, but it is part of the general language.

9.10.1 Element Selection

A place denotes a specific element occurrence or the position immediately before or after the full line:

place ::= element-name |
          element-name[index] |
          #S |
          #E |
          line-name::place

Examples from the source chapter:

  • C[1]: first occurrence of C
  • #S: beginning of the line
  • M[2]: second occurrence of M
  • #E: end of the line
  • S[1]::M[1]: marker M nested in the first occurrence of sub-line S

9.10.2 Range Selection

A range is one place or two places joined by /:

range ::= place | place/place

Examples:

  • #S/#E: the full line
  • A[1]/A[2]: from the first A through the second A
  • S[1]/S[2]: from entry of first S through exit of second S

9.11 Constraints

Constraint expressions from the legacy OPAL matching language are not implemented in the current OPALX attribute and expression parsers. The following syntax is retained only as a legacy reference:

constraint          ::= array-expr constraint-operator array-expr
constraint-operator ::= == | < | >

9.12 Variable Names

Variable references can be:

real-variable
object->real-attribute

9.13 Regular Expressions

Some commands accept UNIX-style regular expressions. The pattern must be quoted. The source chapter documents the usual forms:

  • .
  • [abc]
  • [a-zA-Z]
  • *
  • \character

9.14 Arrays

An array is normally entered as a list in braces:

{value, ..., value}

If the array has only one value, the braces may be omitted.

9.14.1 Logical Arrays

logical-array ::= { logical-list }
logical-list  ::= logical-expr | logical-list , logical-expr

Example:

{true,true,a==b,false,x>y && y>z,true,false}

9.14.2 Real Arrays

Real arrays mirror scalar arithmetic and support:

  • array variables and object array attributes
  • TABLE(...)
  • ROW(...)
  • COLUMN(...)
  • component-wise real functions

Example:

{a, a+b, a+2*b}

Important generator forms:

TABLE(n2, expression)
TABLE(n1:n2, expression)
TABLE(n1:n2:n3, expression)
ROW(table, place)
ROW(table, place, column-list)
COLUMN(table, column)
COLUMN(table, column, range)

In TABLE(...), the special symbol # is replaced by the running index.

ROW(...), COLUMN(...), and table@place->column require a named table object. Current OPALX does not register table-producing commands, so these forms are retained language infrastructure rather than a complete table-analysis interface. TABLE(...) is a usable array generator and does not require a table object.

9.14.3 String Arrays

String arrays are lists of string expressions. Example:

{A, "xyz", A & STRING(X)}

9.14.4 Token List Arrays

Token-list arrays are lists of token lists. Example:

{X:12:8, Y:12:8}