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:
label: optional for executable commands, required for definitions stored for later usekeyword: identifies the command or element typeattribute: 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:
VMAXVMINVRMSVABSMAX
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 ofC#S: beginning of the lineM[2]: second occurrence ofM#E: end of the lineS[1]::M[1]: markerMnested in the first occurrence of sub-lineS
9.10.2 Range Selection
A range is one place or two places joined by /:
range ::= place | place/place
Examples:
#S/#E: the full lineA[1]/A[2]: from the firstAthrough the secondAS[1]/S[2]: from entry of firstSthrough exit of secondS
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}