8  Command Format

8.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:

QF: QUADRUPOLE, L=1, K1=0.01;
QF, L=2;

LMD: LMDIF, CALLS=10;
LMD;
LMD, CALLS=100, TOLERANCE=1E-5;

8.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, though the source manual discourages that because it complicates downstream post-processing.

Unquoted names are converted to upper case before storage.

8.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:

8.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 STRING(X) converts a real expression to a string.

Examples:

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

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

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

Examples:

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

8.6 Real Expressions

Any real value may be given as an arithmetic expression. Expression definitions may be entered in any order; OPAL evaluates them when the required operands are available.

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 | factor ^ primary
term      ::= factor | term * factor | term / factor
real-expr ::= term | +term | -term | real-expr + term | real-expr - term

8.7 Operators

8.8 Real Functions

The source chapter lists the following built-ins:

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

Functions of arrays:

• VMAX
• VMIN
• VRMS
• VABSMAX

The source manual explicitly warns that random generators inside ordinary expressions may be re-evaluated at unexpected times. EVAL(...) can be used to force immediate evaluation and store the result as a constant.

8.9 Operands in Expressions

1, 10.35, 5E3, 314.1592E-2

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

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

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

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

8.10 Element Selection

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

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

range ::= place | place/place

8.11 Constraints

Constraints are mainly used in matching and optimization:

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

8.12 Variable Names

Variable references can be:

real-variable
object->real-attribute

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

Examples:

SELECT, PATTERN="D.."
SELECT, PATTERN="K.*QD.*\\.R1"

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

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

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

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

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)

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

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