GitLab

1.1.1. HELP Command

HELP;                 // Give help on the "HELP" command
HELP,NAME=label;      // List funct. and attr. types of
                      // "label"
HELP,label;           // Shortcut for the second format

HELP;
HELP,NAME=TWISS;
HELP,TWISS;

1.1.2. SHOW Command

SHOW;                 // Give help on the "SHOW" command
SHOW,NAME=pattern;    // Show names matching of "pattern"
SHOW,pattern;         // Shortcut for the second format

SHOW;
SHOW,NAME="QD.*\.L*";
SHOW,"QD.*\.L*";

1.1.3. WHAT Command

WHAT;                   // Give help on the "WHAT" command
WHAT,NAME=label;        // Show definition of "label"
WHAT,label;             // Shortcut for the second format

WHAT;
WHAT,NAME=QD;
WHAT,QD;

The statement

terminates execution of the OPAL program, or, when the statement occurs in a CALL file see Section [call], returns to the calling file. Any statement following the STOP or QUIT statement is ignored.

The OPTION command controls global command execution and sets a few global quantities. Starting with version 1.6.0 of OPAL the option VERSION is mandatory in the OPAL input file. Example:

VERSION

Used to indicate for which version of OPAL the input file is written. The major and minor versions of OPAL and of the input file have to match. The patch version of OPAL must be greater or equal to the patch version of the input file. If the version doesn’t fulfill above criteria OPAL stops immediately and prints instructions on how to convert the input file. The format is Mmmpp where M stands for the major, m for the minor and p for the patch version. For version 1.6.0 of OPAL VERSION should read 10600.

The next five logical flags activate or deactivate execution options:

ECHO

Controls printing of an echo of input lines on the standard error file.

INFO

If this option is turned off, OPAL suppresses all information messages. It also affects the gnu.out and eb.out files in case of OPAL-cycl simulations.

WARN

If this option is turned off, OPAL suppresses all warning messages.

TELL

If true, the current settings are listed. Must be the last option in the inputfile in order to render correct results.

SEED

Selects a particular sequence of random values. A SEED value is an integer in the range [0…​999999999] (default: 123456789). SEED can be an expression. If SEED = -1, the time is used as seed and the generator is not portable anymore. See also: random values see Section [adefer].

PSDUMPFREQ

Defines after how many time steps the phase space is dumped into the H5hut file. Default value is 10.

STATDUMPFREQ

Defines after how many time steps we dump statistical data, such as RMS beam emittance, to the .stat file. The default value is 10. Currently only available for OPAL-t.

SPTDUMPFREQ

Defines after how many time steps we dump the phase space of single particle. It is always useful to record the trajectory of reference particle or some specified particle for primary study. Its default value is 1.

REPARTFREQ

Defines after how many time steps we do particles repartition to balance the computational load of the computer nodes. Its default value is 10.

REBINFREQ

Defines after how many time steps we update the energy Bin ID of each particle. For the time being. Only available for multi-bunch simulation in OPAL-cycl. Its default value is 100.

PSDUMPEACHTURN

Control option of phase space dumping. If true, dump phase space after each turn. For the time being, this is only use for multi-bunch simulation in OPAL-cycl. Its default set is false.

PSDUMPFRAME

Control option that defines the frame in which the phase space data is written for h5 and stat files.

• GLOBAL: data is written in the global Cartesian frame;

• BUNCH_MEAN: data is written in the bunch mean frame or;

• REFERENCE: data is written in the frame of the reference particle.

SCSOLVEFREQ

If the space charge field is slowly varying w.r.t. external fields, this option allows to change the frequency of space charge calculation, i.e. the space charge forces are evaluated every SCSOLVEFREQ step and then reused for the following steps. Affects integrators LF-2 and RK-4 of OPAL-cycl. Its default value is 1. Note: as the multiple-time-stepping (MTS) integrator maintains accuracy much better with reduced space charge solve frequency, this option should probably not be used anymore.

MTSSUBSTEPS

Only used for multiple-time-stepping (MTS) integrator in OPAL-cycl. Specifies how many sub-steps for external field integration are done per step. Default value is 1. Making less steps per turn and increasing this value is the recommended way to reduce space charge solve frequency.

RHODUMP

If true the scalar \rho field is saved each time a phase space is written. There exists a reader in Visit with versions greater or equal 1.11.1.

EFDUMP

Not supported anymore.

EBDUMP

If true the electric and magnetic field on the particle is saved each time a phase space is written.

CSRDUMP

If true the electric csr field component, E_z, line density and the derivative of the line density is written into the data directory. The first line gives the average position of the beam bunch. Subsequent lines list z position of longitudinal mesh (with respect to the head of the beam bunch), E_z, line density and the derivative of the line density. Note that currently the line density derivative needs to be scaled by the inverse of the mesh spacing to get the correct value. The CSR field is dumped at each time step of the calculation. Each text file is named "Bend Name" (from input file) + "-CSRWake" + "time step number in that bend (starting from 1)" + ".txt".

SCAN

If true one can simulate in a loop several machines where some variables can be random variables. Find an example in Section [randmach].

CZERO

If true the distributions are generated such that the centroid is exactly zero and not statistically dependent.

RNGTYPE

The name see Section [astring] of a random number generator can be provided. The default random number generator (RANDOM) is a portable 48-bit generator. Three quasi random generators are available:

1. HALTON

2. SOBOL

3. NIEDERREITER.

For details see the GSL reference manual (18.5).

ENABLEHDF5

If true (default), HDF5 read and write is enabled.

ASCIIDUMP

If true, instead of HDF5, ASCII output is generated for the following elements: Probe, Collimator, Monitor, Stripper, Foil and global losses.

NLHS

Number of stored old solutions for extrapolating the new starting vector. Default value is 1 and just the last solution is used.

NUMBLOCKS

Maximum number of vectors in the Krylov space (for RCGSolMgr). Default value is 0 and BlockCGSolMgr will be used.

RECYCLEBLOCKS

Number of vectors in the recycle space (for RCGSolMgr). Default value is 0 and BlockCGSolMgr will be used.

BOUNDPDESTROYFQ

The frequency to do boundp_destroy to delete lost particles. Default 10

REMOTEPARTDEL

Artificially delete the remote particle if its distance to the beam mass is larger than REMOTEPARTDEL times of the beam rms size, its default values is -1 (no delete)

IDEALIZED

Instructs to use the hard edge model for the calculation of the path length in OPAL-t. The path length is computed to place the elements in the three-dimensional space from ELEMEDGE. Default is false.

LOGBENDTRAJECTORY

Save the reference trajectory inside dipoles in an ASCII file. For each dipole a separate file is written to the directory data/. Default is false.

VERSION

Used to indicate for which version of OPAL the input file is written. The versions of OPAL and of the input file have to match. The format is Mmmpp where M stands for the major, m for the minor and p for the patch version. For version 1.6.0 of OPAL VERSION should read 10600. If the version doesn’t match then OPAL stops immediately and prints instructions on how to convert the input file.

PPDEBUG

SURFDUMPFREQ

BEAMHALOBOUNDARY

CLOTUNEONLY

AMR

Enable adaptive mesh refinement. Default: FALSE

MEMORYDUMP

If true, it writes the memory consumption of every core to a SDDS file (*.mem). The write frequency corresponds to STATDUMPFREQ. Default: FALSE

Examples:

1.4.1. Variable Definitions

REAL variable-name=real-expression;

REAL variable-name:=real-expression;

REAL GEV=100;
P0=GEV;

X=X+1;    // X cannot be equal to X+1
REAL A=B;
REAL B=A;      // A and B are equal, but of unknown value

X=EVAL(X+1);

REAL VECTOR variable-name=vector-expression;

REAL VECTOR A = TABLE(10, #);
REAL VECTOR B = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

BOOL variable-name=logical-expression;

BOOL FLAG = X != 0;

1.4.2. Symbolic Constants

REAL CONST label:CONSTANT=<real-expression>;

CONST IN=0.0254; // conversion of inches to meters

1.4.3. Vector Values

REAL VECTOR vector-name=vector-expression;

VECTOR A_AMPL={2.5e-3,3.4e-2,0,4.5e-8};
VECTOR A_ON=TABLE(10,1);

1.4.4. Assignment to Variables

variable-name=EVAL(real-expression);

vector-name=TABLE(range,EVAL(real-expression));
vector-name={...,EVAL(real-expression),...);

...                 // some definitions
X=0;                // create variable X with value
                    // zero
WHILE (X <= 0.10) {
  TWISS,LINE=...;   // uses X=0, 0.01, ..., 0.10
  X=EVAL(X+.01);    // increment variable X by 0.01
                    // CANNOT use: X=X+.01;
}

1.4.5. VALUE: Output of Expressions

VALUE,VALUE=expression-vector;

REAL A=4;
VALUE,VALUE=TABLE(5,#*A);
REAL P1=5;
REAL P2=7;
VALUE,VALUE={P1,P2,P1*P2-3};

value: {0*A,1*A,2*A,3*A,4*A} = {0,4,8,12,16}
value: {P1,P2,P1*P2-3} = {5,7,32}

1.5.1. ECHO Statement

ECHO,MESSAGE=message;
ECHO,message;           // shortcut

1.5.2. SYSTEM: Execute System Command

SYSTEM,CMD=string;
SYSTEM,string;         // shortcut

1.5.3. SYSTEM Command under UNIX

SYSTEM,"ls -l"

The TITLE statement has three formats:

page-header is a string value see Section [astring]. It defines the page header which will be used as a title for subsequent output pages. Before the first TITLE statement is encountered, the page header is empty. It can be redefined at any time.

1.7.1. CALL Statement

CALL,FILE=file-name;
CALL,file-name;

CALL,FILE="structure";
CALL,"structure";

1.7.2. SAVE Statement

SAVE,FILE=file-name

SAVE,FILE="structure";
SAVE,"structure";

Conditional execution can be requested by an IF statement. It allows usages similar to the C language if statement:

Note that all statements must be terminated with semicolons (;), but there is no semicolon after a closing brace. The statement or group of statements following the IF is executed if the condition is satisfied. If the condition is false, and there is an ELSE, the statement or group following the ELSE is executed.

Repeated execution can be requested by a WHILE statement. It allows usages similar to the C language while statement:

Note that all statements must be terminated with semicolons (;), but there is no semicolon after a closing brace. The condition is re-evaluated in each iteration. The statement or group of statements following the WHILE is repeated as long as the condition is satisfied. Of course some variable(s) must be changed within the WHILE group to allow the loop to terminate.

Subroutine-like commands can be defined by a MACRO statement. It allows usages similar to C language function call statements. A macro is defined by one of the following statements:

A macro may have formal arguments, which will be replaced by actual arguments at execution time. An empty formals list is denoted by (). Otherwise the formals consist of one or more names, separated by commas. The token-list consists of input tokens (strings, names, numbers, delimiters etc.) and is stored unchanged in the definition.

A macro is executed by one of the statements:

Each actual consists of a set of tokens which replaces all occurrences of the corresponding formal name. The actuals are separated by commas. Example: