|
|
:toc:
|
|
|
[[chp:opalcycl]]
|
|
|
|
|
|
:stem: latexmath
|
|
|
:sectnums:
|
|
|
|
|
|
[[chp:format]]
|
|
|
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 __MAD__eight
|
|
|
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.
|
|
|
|
|
|
[[sec:statements]]
|
|
|
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:
|
|
|
|
|
|
1. The `label` is required for a definition statement. Its must be an
|
|
|
identifier see Section [label] and gives a name to the stored command.
|
|
|
2. The `keyword` identifies the action desired. It must be an
|
|
|
identifier see Section [label].
|
|
|
3. 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;
|
|
|
....
|
|
|
|
|
|
[[sec:label]]
|
|
|
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 a
|
|
|
_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].
|
|
|
|
|
|
[[sec:attribute]]
|
|
|
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],
|
|
|
|
|
|
See also:
|
|
|
|
|
|
* Operators see Table [operator],
|
|
|
* Functions see Table [realfun],
|
|
|
* Array functions see Table [arrayfun],
|
|
|
* Real functions of arrays see Table [compfun],
|
|
|
* Operand see Section [operand],
|
|
|
* Random generators see Section [adefer].
|
|
|
|
|
|
[[sec:astring]]
|
|
|
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].
|
|
|
|
|
|
.String Operator in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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
|
|
|
|=======================================================================
|
|
|
|
|
|
.String Function in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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`.
|
|
|
|
|
|
[[sec:alogical]]
|
|
|
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
|
|
|
....
|
|
|
|
|
|
.Logical Operators in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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
|
|
|
....
|
|
|
|
|
|
[[sec:areal]]
|
|
|
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.
|
|
|
|
|
|
[[operators]]
|
|
|
Operators
|
|
|
~~~~~~~~~
|
|
|
|
|
|
An expression can be formed using operators see Table [operator] and
|
|
|
functions see Table [realfun] acting on operands see Section [operand].
|
|
|
|
|
|
.Real Operators in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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`
|
|
|
(latexmath:[\mathtt{Y} > 0]) |real |real,real
|
|
|
|=======================================================================
|
|
|
|
|
|
.Real Functions in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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
|
|
|
latexmath:[\mu=0] and latexmath:[\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 latexmath:[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
|
|
|
latexmath:[\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
|
|
|
|=======================================================================
|
|
|
|
|
|
.Real Functions of Arrays in __OPAL__
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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.
|
|
|
....
|
|
|
|
|
|
[[sec:operand]]
|
|
|
Operands in Expressions
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
A real expression may contain the operands listed in the following
|
|
|
subsections.
|
|
|
|
|
|
[[literal-constants]]
|
|
|
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
|
|
|
....
|
|
|
|
|
|
[[symbolic-constants]]
|
|
|
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.
|
|
|
|
|
|
.Predefined Symbolic Constants
|
|
|
[cols="<,^,^,^",options="header",]
|
|
|
|==========================================================
|
|
|
|_OPAL_ name |Mathematical symbol |Value |Unit
|
|
|
|`PI` |latexmath:[\pi] |3.1415926535898 |1
|
|
|
|`TWOPI` |latexmath:[2 \pi] |6.2831853071796 |1
|
|
|
|`RADDEG` |latexmath:[180/\pi] |57.295779513082 |rad/deg
|
|
|
|`DEGRAD` |latexmath:[\pi/180] |.017453292519943 |deg/rad
|
|
|
|`E` |latexmath:[e] |2.7182818284590 |1
|
|
|
|`EMASS` |latexmath:[m\_e] |.51099906e-3 |GeV
|
|
|
|`PMASS` |latexmath:[m\_p] |.93827231 |GeV
|
|
|
|`HMMASS` |latexmath:[m\_{h^{-}}] |.939277 |GeV
|
|
|
|`CMASS` |latexmath:[m_c] |12*0.931494027 |GeV
|
|
|
|`UMASS` |latexmath:[m_u] |238*0.931494027 |GeV
|
|
|
|`MMASS` |latexmath:[m_\mu] |0.1057 |GeV
|
|
|
|`DMASS` |latexmath:[m_d] |2*0.931494027 |GeV
|
|
|
|`XEMASS` |latexmath:[m_{xe}] |124*0.931494027 |GeV
|
|
|
|`CLIGHT` |latexmath:[c] |299792458 |m/s
|
|
|
|_OPALVERSION_ | |120 |for 1.2.0
|
|
|
|`RANK` | |latexmath:[0\ldots N_{p}-1] |1
|
|
|
|==========================================================
|
|
|
|
|
|
Here the `RANK` represents the MPI-Rank of the process and
|
|
|
latexmath:[N_{p}] the total number of MPI processes.
|
|
|
|
|
|
[[sec:avariable]]
|
|
|
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.
|
|
|
|
|
|
[[element-or-command-attributes]]
|
|
|
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`.
|
|
|
|
|
|
[[sec:adefer]]
|
|
|
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.
|
|
|
|
|
|
[[element-selection]]
|
|
|
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`.
|
|
|
|
|
|
[[sec:aplace]]
|
|
|
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`.
|
|
|
|
|
|
[[sec:arange]]
|
|
|
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`.
|
|
|
|
|
|
[[sec:aconstraint]]
|
|
|
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 ::= "==" | "<" | ">"
|
|
|
....
|
|
|
|
|
|
[[sec:areference]]
|
|
|
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
|
|
|
|
|
|
[[sec:wildcard]]
|
|
|
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.
|
|
|
latexmath:[\backslash]character::
|
|
|
Removes the special meaning of `character`, Example: ```\backslash*`''
|
|
|
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.
|
|
|
|
|
|
[[sec:anarray]]
|
|
|
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
|
|
|
....
|
|
|
|
|
|
[[sec:logarray]]
|
|
|
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}
|
|
|
....
|
|
|
|
|
|
[[sec:realarray]]
|
|
|
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 |
|
|
|
....
|
|
|
|
|
|
.Real Array Functions in _OPAL_ (acting component-wise)
|
|
|
[cols="<,<,<,<",options="header",]
|
|
|
|=======================================================================
|
|
|
|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 latexmath:[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
|
|
|
latexmath:[\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.
|
|
|
|
|
|
[[sec:strarray]]
|
|
|
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)}
|
|
|
....
|
|
|
|
|
|
[[sec:tokarray]]
|
|
|
Token List Arrays
|
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
Token list arrays are always lists of single token lists.
|
|
|
|
|
|
Example:
|
|
|
|
|
|
....
|
|
|
{X:12:8,Y:12:8}
|
|
|
.... |