format · Wiki · snuverink_j / OPALManualWiki

Table of Contents

1. Command Format

1. Command Format

All flavors of OPAL using the same input language the MAD language. The language dialect here is ajar to MAD9, for hard core MADeight users there is a conversion guide.

It is the first time that machines such as cyclotrons, proton and electron linacs can be described within the same language in the same simulation framework.

1.1. Statements and Comments

Input for OPAL is free format, and the line length is not limited. During reading, input lines are normally printed on the echo file, but this feature can be turned off for long input files. The input is broken up into tokens (words, numbers, delimiters etc.), which form a sequence of commands, also known as statements. Each statement must be terminated by a semicolon (;), and long statements can be continued on any number of input lines. White space, like blank lines, spaces, tabs, and newlines are ignored between tokens. Comments can be introduced with two slashes (//) and any characters following the slashes on the same line are ignored.

The C convention for comments (/* … */) is also accepted. The comment delimiters /* and */ can be nested; this allows to ``comment out'' sections of input.

In the following descriptions, words in lower case stand for syntactic units which are to be replaced by actual text. UPPER CASE is used for keywords or names. These must be entered as shown. Ellipses (…) are used to indicate repetition.

The general format for a command is

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

It has three parts:

The label is required for a definition statement. Its must be an identifier see Section [label] and gives a name to the stored command.
The keyword identifies the action desired. It must be an identifier see Section [label].
Each attribute is entered in one of the forms
```
attribute-name
attribute-name=attribute-value
attribute-name:=attribute-value
```
and serves to define data for the command, where:
- The attribute-name selects the attribute, it must be an identifier see Section [label].
- The attribute-value gives it a value see Section [attribute]. When the attribute value is a constant or an expression preceded by the delimiter = it is evaluated immediately and the result is assigned to the attribute as a constant. When the attribute value is an expression preceded by the delimiter := the expression is retained and re-evaluated whenever one of its operands changes.
  
  Each attribute has a fixed attribute type see Section [attribute].
  The attribute-value can only be left out for logical attributes, this implies a true value.

When a command has a label, OPAL keeps the command in memory. This allows repeated execution of the same command by entering its label only:

label;

or to re-execute the command with modified attributes:

label,attribute,...,attribute;

If the label of such a command appears together with new attributes, OPAL makes a copy of the stored command, replaces the attributes entered, and then executes the copy:

QF:QUADRUPOLE,L=1,K1=0.01; // first definition of QF
QF,L=2;                    // redefinition of QF

MATCH;
...
LMD:LMDIF,CALLS=10;           // first execution of LMD
LMD;                          // re-execute LMD with
                              // the same attributes
LMD,CALLS=100,TOLERANCE=1E-5; // re-execute LMD with
                              // new attributes
ENDMATCH;

1.2. Identifiers or Labels

An identifier refers to a keyword, an element, a beam line, a variable, an array, etc.

A label begins with a letter, followed by an arbitrary number of letters, digits, periods (.), underscores (_). Other special characters can be used in a label, but the label must then be enclosed in single or double quotes. It makes no difference which type of quotes is used, as long as the same are used at either end. The preferred form is double quotes. The use of non-numeric characters is however strongly discouraged, since it makes it difficult to subsequently process an _OPAL_ output with another program.

When a name is not quoted, it is converted to upper case; the resulting name must be unique. An identifier can also be generated from a string expression see Section [astring].

1.3. Command Attribute Types

An object attribute is referred to by the syntax

object-name->attribute-name

If the attribute is an array see Section [anarray], one of its components is found by the syntax

object-name->attribute-name[index]

The following types of command attributes are available in OPAL:

String see Section [astring],
Logical see Section [alogical],
Real expression see Section [areal],
Deferred expression see Section [adefer],
Place see Section [aplace],
Range see Section [arange],
Constraint see Section [aconstraint],
Variable Reference see Section [areference]
Regular expression see Section [wildcard]
Token list see Section [toklist].
Array see Section [anarray] of
- Logical see Section [logarray],
- Real see Section [realarray],
- String see Section [strarray],
- Token lists see Section [tokarray],

1.4. String Attributes

A string attribute makes alphanumeric information available, e.g. a title, file name, element class name, or an option. It can contain any characters, enclosed in single (’) or double (") quotes. However, if it contains a quote, this character must be doubled. Strings can be concatenated using the & operator see Table [stroperator]. An operand in a string can also use the function STRING see Table [stringfun]. String values can occur in string arrays see Section [anarray].

Table 1. String Operator in *OPAL*
Operator	Meaning	result type	operand types
`X & Y`	concatenate the strings `X` and `Y`. String concatenations are always evaluated immediately when read.	string	string,string

Table 2. String Function in *OPAL*
Function	Meaning	result type	argument type
`STRING(X)`	return string representation of the value of the numeric expression `X`	string	real

Examples:

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

REAL X=1;
TWISS,LINE=LEP&STRING(X+1);

The second example converts the value of the expression X+1 to a string and appends it to LEP, giving the string LEP2.

1.5. Logical Expressions

Many commands in OPAL require the setting of logical values (flags) to represent the on/off state of an option. A logical value is represented by one of the values TRUE or FALSE, or by a logical expression. A logical expression can occur in logical arrays see Section [logarray].

A logical expression has the same format and operator precedence as a logical expression in C. It is built from logical operators see Table [logoperator] and logical operands:

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

Table 3. Logical Operators in *OPAL*
Operator	Meaning	result type	operand type
`X < Y`	true, if `X` is less than `Y`	logical	real,real
`X ⇐ Y`	true, if `X` is not greater than `Y`	logical	real,real
`X > Y`	true, if `X` is greater than `Y`	logical	real,real
`X >= Y`	true, if `X` is not less than `Y`	logical	real,real
`X == Y`	true, if `X` is equal to `Y`	logical	real,real
`X != Y`	true, if `X` is not equal to `Y`	logical	real,real
`X && Y`	true, if both `X` and `Y` are true	logical	logical,logical
`X` \|\| `Y`	true, if at least one of `X` and `Y` is true	logical	logical,logical

Example:

OPTION,ECHO=TRUE; // output echo is desired

When a logical attribute is not entered, its default value is always FALSE. When only its name is entered, the value is set to TRUE:

OPTION,ECHO;      // same as above

Example of a logical expression:

X>10 && Y<20 || Z==15

1.6. Real Expressions

To facilitate the definition of interdependent quantities, any real value can be entered as an arithmetic expression. When a value used in an expression is redefined by the user or changed in a matching process, the expression is re-evaluated. Expression definitions may be entered in any order. OPAL evaluates them in the correct order before it performs any computation. At evaluation time all operands used must have values assigned. A real expression can occur in real arrays see Section [realarray].

A real expression is built from operators see Table [operator] and operands see Section [operand]:

real-ref  ::= real-variable |
              real-array "[" index "]" |
              object "->" real-attribute |
              object "->" real-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 |

It may contain functions see Table [realfun], Parentheses indicate operator precedence if required. Constant sub-expressions are evaluated immediately, and the result is stored as a constant.

1.7. Operators

An expression can be formed using operators see Table [operator] and functions see Table [realfun] acting on operands see Section [operand].

Table 4. Real Operators in *OPAL*
Operator	Meaning	result type	operand type(s)
Real operators with one operand
`+ X`	unary plus, returns `X`	real	real
`- X`	unary minus, returns the negative of `X`	real	real
Real operators with two operands
`X + Y`	add `X` to `Y`	real	real,real
`X - Y`	subtract `Y` from `X`	real	real,real
`X * Y`	multiply `X` by `Y`	real	real,real
`X / Y`	divide `X` by `Y`	real	real,real
`X Y`	power, return `X` raised to the power `Y` (`\mathtt{Y} > 0`)	real	real,real

Table 5. Real Functions in *OPAL*
Function	Meaning	result type	argument type(s)
Real functions with no arguments
`RANF()`	random number, uniform distribution in [0,1)	real	-
`GAUSS()`	random number, Gaussian distribution with `\mu=0` and `\sigma=1`	real	-
`GETEKIN()`	returns the kinetic energy of the bunch (MeV)	real	-
`USER0()`	random number, user-defined distribution	real	-
Real functions with one argument
`TRUNC(X)`	truncate `X` towards zero (discard fractional part)	real	real
`ROUND(X)`	round `X` to nearest integer	real	real
`FLOOR(X)`	return largest integer not greater than `X`	real	real
`CEIL(X)`	return smallest integer not less than `X`	real	real
`SIGN(X)`	return sign of `X` (+1 for `X` positive, -1 for `X` negative, 0 for `X` zero)	real	real
`SQRT(X)`	return square root of `X`	real	real
`LOG(X)`	return natural logarithm of `X`	real	real
`EXP(X)`	return exponential to the base `e` of `X`	real	real
`SIN(X)`	return trigonometric sine of `X`	real	real
`COS(X)`	return trigonometric cosine of `X`	real	real
`ABS(X)`	return absolute value of `X`	real	real
`TAN(X)`	return trigonometric tangent of `X`	real	real
`ASIN(X)`	return inverse trigonometric sine of `X`	real	real
`ACOS(X)`	return inverse trigonometric cosine of `X`	real	real
`ATAN(X)`	return inverse trigonometric tangent of `X`	real	real
`TGAUSS(X)`	random number, Gaussian distribution with `\sigma`=1, truncated at `X`	real	real
`USER1(X)`	random number, user-defined distribution with one parameter	real	real
`EVAL(X)`	evaluate the argument immediately and transmit it as a constant	real	real
Real functions with two arguments
`ATAN2(X,Y)`	return inverse trigonometric tangent of `Y/X`	real	real,real
`MAX(X,Y)`	return the larger of `X`, `Y`	real	real,real
`MIN(X,Y)`	return the smaller of `X`, `Y`	real	real,real
`MOD(X,Y)`	return the largest value less than `Y` which differs from `X` by a multiple of `Y`	real	real,real
`USER2(X,Y)`	random number, user-defined distribution with two parameters	real	real,real

Table 6. Real Functions of Arrays in *OPAL*
Function	Meaning	result type	operand type
`VMAX(X,Y)`	return largest array component	real	real array
`VMIN(X,Y)`	return smallest array component	real	real array
`VRMS(X,Y)`	return rms value of an array	real	real array
`VABSMAX(X,Y)`	return absolute largest array component	real	real array

Care must be used when an ordinary expression contains a random generator. It may be re-evaluated at unpredictable times, generating a new value. However, the use of a random generator in an assignment expression is safe. Examples:

D:DRIFT,L=0.01*RANF();    // a drift space with rand. length,
                          // may change during execution.
REAL P=EVAL(0.001*TGAUSS(X));  // Evaluated once and stored as a constant.

1.8. Operands in Expressions

A real expression may contain the operands listed in the following subsections.

1.8.1. Literal Constants

Numerical values are entered like FORTRAN constants. Real values are accepted in INTEGER or REAL format. The use of a decimal exponent, marked by the letter D or E, is permitted.

Examples:

1, 10.35, 5E3, 314.1592E-2

1.8.2. Symbolic constants

OPAL recognizes a few built-in mathematical and physical constants see Table [constant]. Their names must not be used for user-defined labels. Additional symbolic constants may be defined see Section [constant] to simplify their repeated use in statements and expressions.

Table 7. Predefined Symbolic Constants
OPAL name	Mathematical symbol	Value	Unit
`PI`	`\pi`	3.1415926535898	1
`TWOPI`	`2 \pi`	6.2831853071796	1
`RADDEG`	`180/\pi`	57.295779513082	rad/deg
`DEGRAD`	`\pi/180`	.017453292519943	deg/rad
`E`	`e`	2.7182818284590	1
`EMASS`	`m_e`	.51099906e-3	GeV
`PMASS`	`m_p`	.93827231	GeV
`HMMASS`	`m_{h^{-}}`	.939277	GeV
`CMASS`	`m_c`	12*0.931494027	GeV
`UMASS`	`m_u`	238*0.931494027	GeV
`MMASS`	`m_\mu`	0.1057	GeV
`DMASS`	`m_d`	2*0.931494027	GeV
`XEMASS`	`m_{xe}`	124*0.931494027	GeV
`CLIGHT`	`c`	299792458	m/s
OPALVERSION		120	for 1.2.0
`RANK`		`0\ldots N_{p}-1`	1

Here the RANK represents the MPI-Rank of the process and N_{p} the total number of MPI processes.

1.8.3. Variable labels

Often a set of numerical values depends on a common variable parameter. Such a variable must be defined as a global variable see Section [variable] defined by one of

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

When such a variable is used in an expression, OPAL uses the current value of the variable. When the value is a constant or an expression preceded by the delimiter = it is evaluated immediately and the result is assigned to the variable as a constant. When the value is an expression preceded by the delimiter := the expression is retained and re-evaluated whenever one of its operands changes.
Example:

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

When the value of X is changed, the lengths of the drift spaces are recalculated as X and 2-X respectively.

1.8.4. Element or command attributes

In arithmetic expressions the attributes of physical elements or commands can occur as operands. They are named respectively by

element-name->attribute-name
command-name->attribute-name

If they are arrays, they are denoted by

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

Values are assigned to attributes in element definitions or commands.

Example:

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

D1→L refers to the length L of the drift space D1.

1.8.5. Deferred Expressions and Random Values

Definition of random machine imperfections requires evaluation of expressions containing random functions. These are not evaluated like other expressions before a command begins execution, but sampled as required from the distributions indicated when errors are generated. Such an expression is known as a deferred expression. Its value cannot occur as an operand in another expression.

1.9. Element Selection

Many OPAL commands allow for the possibility to process or display a subset of the elements occurring in a beam line or sequence. This is not yet available in: DOPAL-t and DOPAL-cycl.

1.9.1. Element Selection

A place denotes a single element, or the position following that element. It can be specified by one of the choices

object-name[index]: The name object-name is the name of an element, line or sequence, and the integer index is its occurrence count in the beam line. If the element is unique, [index] can be omitted.
#S: denotes the position before the first physical element in the full beam line. This position can also be written #0.
#E: denotes the position after the last physical element in the full beam line.

Either form may be qualified by one or more beam line names, as described by the formal syntax:

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

An omitted index defaults to one. Examples: assume the following definitions:

M: MARKER;
S: LINE=(C,M,D);
L: LINE=(A,M,B,2*S,A,M,B);
   SURVEY,LINE=L

The line L is equivalent to the sequence of elements

A,M,B,C,M,D,C,M,D,A,M,B

Some possible place definitions are:

C[1]: The first occurrence of element C.
#S: The beginning of the line L.
M[2]: The second marker M at top level of line L, i. e. the marker between second A and the second B.
#E: The end of line L
S[1]::M[1]: The marker M nested in the first occurrence of S.

1.9.2. Range Selection

A range in a beam line see Section [line] is selected by the following syntax:

range ::= place |
          place "/" place

This denotes the range of elements from the first`place` to the second place. Both positions are included. A few special cases are worth noting:

When place1 refers to a LINE see Section [line]. the range starts at the beginning of this line.
When place2 refers to a LINE see Section [line]. the range ends at the ending of this line.
When both place specifications refer to the same object, then the second can be omitted. In this case, and if place refers to a LINE see Section [line] the range contains the whole of the line.

Examples: Assume the following definitions:

M: MARKER;
S: LINE=(C,M,D);
L: LINE=(A,M,B,2*S,A,M,B);

The line L is equivalent to the sequence of elements

A,M,B,C,M,D,C,M,D,A,M,B

Examples for range selections:

#S/#E: The full range or L.
A[1]/A[2]: A[1] through A[2], both included.
S::M/S[2]::M: From the marker M nested in the first occurrence of S, to the marker M nested in the second occurrence of S.
S[1]/S[2]: Entrance of first occurrence of S through exit of second occurrence of S.

1.10. Constraints

Please note this is not yet available in: DOPAL-t and DOPAL-cycl.

In matching it is desired to specify equality constraints, as well as lower and upper limits for a quantity. OPAL accepts the following form of constraints:

constraint          ::= array-expr constraint-operator array-expr

constraint-operator ::= "==" | "<" | ">"

1.11. Variable Names

A variable name can have one of the formats:

   variable name ::= real variable |
                     object"->"real attribute

The first format refers to the value of the global variable see Section [variable], the second format refers to a named attribute of the named object. object can refer to an element or a command

1.12. Regular Expressions

Some commands allow selection of items via a regular-expression. Such a pattern string must be enclosed in single or double quotes; and the case of letters is significant. The meaning of special characters follows the standard UNIX usage:

.: Stands for a single arbitrary character,
[letter…letter]: Stands for a single character occurring in the bracketed string, Example: [abc] denotes the choice of one of a,b,c.
[character-character]: Stands for a single character from a range of characters, Example: [a-zA-Z] denotes the choice of any letter.
*: Allows zero or more repetitions of the preceding item, Example: [A-Z]* denotes a string of zero or more upper case letters.
\backslashcharacter: Removes the special meaning of character, Example: \* denotes a literal asterisk.

All other characters stand for themselves. The pattern

"[A-Za-z][A-Za-z0-9_']*"

illustrates all possible unquoted identifier formats see Section [label]. Since identifiers are converted to lower case, after reading they will match the pattern

"[a-z][a-z0-9_']*"

Examples for pattern use:

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

The first command selects all elements whose names have exactly three characters and begin with the letter D. The second command saves definitions beginning with the letter K, containing the string QD, and ending with the string .R1. The two occurrences of .* each stand for an arbitrary number (including zero) of any character, and the occurrence \. stands for a literal period.

1.13. Arrays

An attribute array is a set of values of the same attribute type see Section [attribute]. Normally an array is entered as a list in braces:

{value,...,value}

The list length is only limited by the available storage. If the array has only one value, the braces (``) can be omitted:

value

1.13.1. Logical Arrays

For the time being, logical arrays can only be given as a list. The formal syntax is:

logical-array ::= "{" logical-list "}"

logical-list  ::= logical-expr |
                  logical-list "," logical-expr

Example:

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

1.13.2. Real Arrays

Real arrays have the following syntax:

array-ref     ::= array-variable |
                  object "->" array-attribute |

table-ref     ::= "ROW" "(" table "," place ")" |
                  "ROW" "(" table "," place "," column-list ")"
                  "COLUMN" "(" table "," column ")" |
                  "COLUMN" "(" table "," column "," range ")"

columns       ::= column |
                  "{" column-list "}"

column-list   ::= column |
                  column-list "," column

column        ::= string

real-list     ::= real-expr |
                  real-list "," real-expr

index-select  ::= integer |
                  integer "," integer |
                  integer "," integer "," integer

array-primary ::= "{" real-list "}" |
                  "TABLE" "(" index-select "," real-expr ")" |
                  array-ref |
                  table-ref |
                  array-function-name "(" arguments ")" |
                  (array-expression)

array-factor  ::= array-primary |
                  array-factor "^" array-primary

array-term    ::= array-factor |
                  array-term "*" array-factor |
                  array-term "/" array-factor

array-expr    ::= array-term |
                  "+" array-term |
                  "-" array-term |
                  array-expr "+" array-term |
                  array-expr "-" array-term |

Table 8. Real Array Functions in *OPAL* (acting component-wise)
Function	Meaning	result type	argument type
`TRUNC(X)`	truncate `X` towards zero (discard fractional part)	real array	real array
`ROUND(X)`	round `X` to nearest integer	real array	real array
`FLOOR(X)`	return largest integer not greater than `X`	real array	real array
`CEIL(X)`	return smallest integer not less than `X`	real array	real array
`SIGN(X)`	return sign of `X` (+1 for `X` positive, -1 for `X` negative, 0 for `X` zero)	real array	real array
`SQRT(X)`	return square root of `X`	real array	real array
`LOG(X)`	return natural logarithm of `X`	real array	real array
`EXP(X)`	return exponential to the base `e` of `X`	real array	real array
`SIN(X)`	return trigonometric sine of `X`	real array	real array
`COS(X)`	return trigonometric cosine of `X`	real array	real array
`ABS(X)`	return absolute value of `X`	real array	real array
`TAN(X)`	return trigonometric tangent of `X`	real array	real array
`ASIN(X)`	return inverse trigonometric sine of `X`	real array	real array
`ACOS(X)`	return inverse trigonometric cosine of `X`	real array	real array
`ATAN(X)`	return inverse trigonometric tangent of `X`	real array	real array
`TGAUSS(X)`	random number, Gaussian distribution with `\sigma`=1, truncated at `X`	real array	real array
`USER1(X)`	random number, user-defined distribution with one parameter	real array	real array
`EVAL(X)`	evaluate the argument immediately and transmit it as a constant	real array	real array

Example:

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

There are also three functions allowing the generation of real arrays:

TABLE

Generate an array of expressions:

TABLE(n2,expression)    // implies
                        // TABLE(1:n2:1,expression)
TABLE(n1:n2,expression) // implies
                        // TABLE(n1:n2:1,expression)
TABLE(n1:n2:n3,expression)

These expressions all generate an array with n2 components. The components selected by n1:n2:n3 are filled from the given expression; a C pseudo-code for filling is

int i;
for (i = n1; i <= n2; i += n3) a[i] = expression(i);

In each generated expression the special character hash sign (#) is replaced by the current value of the index i.

Example:

// an array with 9 components, evaluates to
// {1,4,7,10,13}:
table(5:9:2,3*#+1) // equivalent to
                   // {0,0,0,0,16,0,22,0,28}

ROW

Generate a table row:

ROW(table,place)             // implies all columns
ROW(table,place,column list)

This generates an array containing the named (or all) columns in the selected place.

COLUMN

Generate a table column:

COLUMN(table,column)         // implies all rows
COLUMN(table,column,range)

This generates an array containing the selected (or all) rows of the named column.

1.13.3. String Arrays

String arrays can only be given as lists of single values. For permissible values String values see Section [astring].

Example:

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

1.13.4. Token List Arrays

Token list arrays are always lists of single token lists.

Example:

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