Lattice File Language Syntax

An OptiM input file template may be generated by selecting the File|New menu item. The file structure is described in what follows.

The input file (the text in the main window) optionally begins with a math header section where named variables can be defined. These variables, or expressions build from them, may be used later in the main body of the file. With the exception of lines beginning with the strings #INCLUDE or #include, any line beginning with a "#" character is considered a comment and is ignored. Comment lines are allowed anywhere within the input file. In addition, within the the math header, the # character can be used for in-line comments i.e. whatever follows the # on a given line is considered as a comment. The first line following the math header (whether or not the header exists) must contain the single string "OptiM" (without the quotes). This line acts as a marker for the beginning of statements that pertain to the lattice definition. Assuming that this marker is the first line within the body of the file, the subsequent lines must be ordered in a prescribed sequence ( comment lines may be included ) :

After line 9 an optional block making references to external files may appear. Up to 10 external files can be referenced. These files are used to specify the field in accelerating cavities (see W-RF cavity (PI standing wave) ). The block must begin with the line
  file  reference start
and end with the line
  file reference end.
There can be up to 10 lines in between these two delimiters. Each line defines two parameters: a file reference number (0 - 9) and a file name. The example below should make the syntax clearer.
file reference start
0 C:\BCPP\OPTIM\CAVITY\fit.DAT 
file reference end 

Either absolute or relative (to the location the main optics file) file paths may be used. File/directory names containing white space must be enclosed in double quotes (e.g. "File name with spaces.opt"). If there are no external file references the block can be omitted. The next lines are occupied by a block which describes the lattice element sequence. The first line is delimiter which also defines the number of superperiods present in the lattice. In most cases, it would read as follows:

 begin lattice. Number of periods=1
  

Element labels appearing in the element list can be separated by any number of space or tab characters. While there is no limit on the number of lines or the number of element names per line, there is a hard limit of 255 characters on any given line. Labels can be formed using any combination of alphanumeric characters and two special symbols: ":" and "_". In addition, a label can have a suffix (tag), i.e. it can be extended using the & operator. For example, the labels bARC&1 and bARC& would both reference an element of type bARC. While the unextended base label has to be used in the description of element parameters (see below) the labels bARC1 and bARC2 will appear in all element lists and program output. This scheme allows the use of distinct tags for otherwise identical elements. The operator & can also be used with text variables (see math header). In this case, the suffix will be appended to every label present in the expression represented by the variable. The element list ends with a delimiter line containing the string "end lattice".

The line "begin list" begins a block which holds a list of elements with their attributes. On line per element (see Elements) is used with the exception of the transfer matrix element, which requires 7 lines. The element list must be terminated by the delimiter "end list". The lattice description is finalized, if required, by a few service blocks arranged in arbitrary order. Possible blocks include the fitting block, (see Fitting|Betas), the 4D Beta-functions block (see 4D Beta-functions block), the Space Charge Block (see Space Charge Menu) and the Trajectory Parameters Block (see Trajectory). When parsing elements in the element list, the program reads all parameters on each line in the order in which they appear and ignores attribute keywords. Attribute values are assumed to begin immmediately after the '=' sign and end when the first non-numeric character is encountered. In other words, attributes keywords are mere mnemonics and they can be abridged or simply omitted. Note that in the event a line contains an insufficient number of attribute values, the remaining ones are set to zero. Numerical values can be specified in either fixed point decimal or scientific notation.

Pressing the 'F2' key (see Edit|Analyze lattice) causes the input buffer to be parsed and overwritten as it is interpreted by the program. While this is useful to bring a file into standard form without modifying the comment lines, numerical values will also be assigned to all variables used in element definition, destroying the relationship between the math header and the element descriptions. In the event a syntax error is encountered, the cursor is positioned on the offending line and an explanatory message is issued.

#INCLUDE and #include Directives

The directives #INCLUDE and #include are used to insert external files into an OptiM file; this is useful to minimize duplication. For example, to describe the different optics of a ring or transfer line under different operational scenarios, one would include a different file for each distict set of element settings. While both directives are superficially similar, i.e.:

#INCLUDE FileName
#include FileName 

they behave somewhat differently. The first form, #INCLUDE, is only active while an input file is being either read or saved. When an #INCLUDE directive is encountered during a Read operation the input switches to the external file Filename. Once the external file end is reached, the input returns to the main editor and a #END_INCLUDE directive is appended. Included lines are shifted by one tab-stop to distinguish them from those in the rest of the (main)file. During a Save operation, the program saves the editor buffer line-by-line. If #INCLUDE is encountered, all subsequent lines are skipped until #END_INCLUDE is reached. There is no limitation on number of #INCLUDE statements; however, nested #INCLUDE directives are not supported.

The #include directive is recognized during parsing only. Every time a computation is requested, the program re-parses the content of the main editor buffer. When #include dis encountered, the input is redirected to the specified file until the end of file is reached, at which point reading from the main editor buffer is resumed. There is no limitation on number of #include directives but nested #include directives are not supported.

The File|Get File Name command is useful to create a FileName argument for the #INCLUDE directive. Both the #include and #ICLUDE directives allow use of either absolute or relative (to the location of the main optics file) path to the file. Note that file/directory names containing white space should be enclosed in double quotes (e.g. "File name with spaces.opt").

Beta-function block

A 4D beta-function block specifies the initial values of dispersions and 4D beta-functions used for computations from the View 4D Menu. A self-explanatory example of such a block is shown below. The program uses eight 4D-Twiss parameters and the symplecticity conditions to determine initial eigenvectors, which then used for further computations (4D beta-functions, betatron phase advances, etc.). Unfortunately, the symplecticity conditions alone are not sufficient to uniquely determine this eigenvectors. In general, there are four independent solutions with different values of the auxiliary 4D-Twiss parameters, Nu_1, Nu_2 and U. To make the choice unambiguous, the program chooses the solution whose Nu_1 parameter is closest to the Nu_1 prescribed in the 4D_BetaBlock (the values of Nu_2 and U from the 4D_BetaBlock are ignored). The menu View4D|Update 4D betas may be used to update the prescribed values of Nu_1, Nu_2 and U.

Example:
4D_BetaBlock
	Beta_X_1[cm]=1760.93 	Beta_X_2[cm]=330.954
	Alfa_X_1=0.498986  	Alfa_X_2=0.20907
	Beta_Y_1[cm]=113.14 	Beta_Y_2[cm]=438.468
	Alfa_Y_1=-0.114458  	Alfa_Y_2=-0.197883
	Nu_1[deg]=122.309 	Nu_2[deg]=97.9812 	U=-0.167011
	Emit1[cm]=1.e-5  	Emit2[cm]=1.e-5
	DispX[cm]=175.168 	DispY[cm]=-20.6339
	DispXpr[cm]=-0.04483 	DispYpr[cm]=-0.0255863
End4DBetaBlock 

Example input file

The following example describes the lattice of the ASTRID storage ring in Aarhus University, Denmark.

# Edge focusing is modeled by short combine function dipoles
$R=120.8;  =>       120.8 
$L=$PI*$R/4-12.8;  =>  82.0760981
$E=579.467;  =>     579.467
$Hr=sqrt(($E+$Me)*($E+$Me)-$Me*$Me)*1e11/$c;  =>  1934.59737
$B=$Hr/$R;  =>  16.0148789
$Bh=$B/2;  =>  8.00743943 
$Dip="bB bBc bB"
OptiM
#  ASTRID general lattice
Energy[MeV]=579.467    Mass[MeV]=0.511006 
Emittance: ex[cm]=1.3e-05  ey[cm]=1e-06  DP/P=0.0007 
Initial:	BetaX[cm]=1575.31 	BetaY[cm]=355.666 
	AlfaX=5.17506e-16 	AlfaY=2.6301e-16 
	DispersX[cm]=269.3 	DispersY[cm]=0 
	Dsp_PrimeX=-1.36334e-16 	DspPrimeY=0 
	X[cm]=0.000    	Y[cm]=0.000    	Z[cm]=0.000    	S[cm]=0.000    
	tetaX[deg]=0        	tetaY[deg]=0        
#  Elements: O-free space, D-dipole, Q-quad, S-sextipole
#  Elements: B-dipole with gradient
begin lattice. Number of periods=4 
O Sf o qQf&4b o Sd o qQd&4b o1 $Dip&1a o2 o2 $Dip&1b o1 qQd&1a o Sd o qQf&1a o Sf O
O Sf o qQf&1b o Sd o qQd&1b o1 $Dip&2a o2 o2 $Dip&2b o1 qQd&2a o Sd o qQf&2a o Sf O
O Sf o qQf&2b o Sd o qQd&2b o1 $Dip&2a o2 o2 $Dip&2b o1 qQd&3a o Sd o qQf&3a o Sf O
O Sf o qQf&3b o Sd o qQd&3b o1 $Dip&2a o2 o2 $Dip&2b o1 qQd&4a o Sd o qQf&4a o Sf O
end lattice
begin list
O       	L[cm]=136      
Os   	L[cm]=86       
o      	L[cm]=9.90133  
o1    	L[cm]=57.46    
o2    	L[cm]=7.16     
Sf     	L[cm]=36         	S[kG/cm/cm)]=0.0027
Sd    	L[cm]=36         	S[kG/cm/cm)]=-0.0054
qQf  	L[cm]=45         	G[kG/cm]=0.277565 	Tilt[deg]=0
qQd  	L[cm]=45         	G[kG/cm]=-0.445846 	Tilt[deg]=0
bB    	L[cm]=12.8       	B[kG]=8.0074394   	G[kG/cm]=0.033144  	Tilt[deg]=0
bBc  	L[cm]=82.076098   	B[kG]=16.014879   	G[kG/cm]=0        	Tilt[deg]=0
c1   	L[cm]=100          	B[kG]=8.40637       
end list of elements

BetaFitBlock  dL[cm]=0.01  dB[kGs]=0.01  dG[kGs/cm]=0.001
#Required parameters and their accuracy listed below(dPARM<=0. - no fitting)
#Maximum Betas[cm] and MomentumCompaction are on the next line
BtXmax=5000  dBtXmax=0  BtYmax=5000  dBtYmax=0  Alfa=0.0679  dAlfa=0.001
#Fitting parameters at the end of the lattice
Beta_X[cm]=1603.9 	dBeta_X[cm]=-0.1 	Alfa_X=0  	dAlfa_X=-0.0001
Beta_Y[cm]=359.5 	dBeta_Y[cm]=0.1 	Alfa_Y=0  	dAlfa_Y=-0.0001 
Disp_X[cm]=269.058 	dDisp_X[cm]=-1 	D_prime_X=0 	dD_prime_X=-0.001 
Disp_Y[cm]=0 	dDisp_Y[cm]=-1 	D_prime_Y=0 	dD_prime_Y=-0.001 
Qx=0.550986 	dQx=-0.01 
Qy=0.658466 	dQy=-0.01 
G: qQf
G: qQd
EndBetaFitBlock

4D_BetaBlock
	Beta_X_1[cm]=1575.31 	Beta_X_2[cm]=6.89188e-32
	Alfa_X_1=5.10072e-16  	Alfa_X_2=0
	Beta_Y_1[cm]=6.6708e-34 	Beta_Y_2[cm]=355.666
	Alfa_Y_1=0  	Alfa_Y_2=2.61961e-16
	Nu_1[deg]=23.0371 	Nu_2[deg]=-147.283 	U=0
	Emit1[cm]=1.e-5. 	Emit2[cm]=1.e-5
	DispX[cm]=269.3 	DispY[cm]=0
	DispXpr[cm]=-1.35845e-16 	DispYpr[cm]=0
End4DbetaBlock

SpaceChargeBlock
  BeamCurrent[A]=0.1
  BunchLength[cm]=1.0   dP/P=0.001   Alpha[-1,1]=0.
EndSpaceChargeBlock

Math Header

The syntax of the math header is similar to that of the PERL language. Like in PERL, variable names begin with the "$" character. Unlike PERL, each line in the OptiM math header may contain only one expression and the latter must end with ";" or a newline character. Characters appearing after ";" are ignored. Choosing menu Edit|Analyse Header or Ctrl+F2 evaluates all expressions appearing in the header. On each line, the expression is evaluated and the numerical value is appended, overwriting any textual information that may be present after ";". Should one need to preserve such information, an in-line comment should be used. In tha case, the terminator ";" must apperar appear before the comment character #.

An array of numbers may be defined as follows

	ARRAY $name[size]={val1, val2, val_size}
Here \$name is the array name, size is an integer which defines the array size. If vals are not set they are assumed to be zero. To reference an array element the syntax \$name[\$i] is used to reference a specific array element (note that in that context \$i is interpreted as the integer value of the real variable \$i). The arithmetic operator precedence within an expression is the same as in most standard computer languages (FORTRAN, C, PERL, et c.) . The four arithmetic operators are : +, -, * and /. The operator = is used for assigment. A variable must be assigned before it can be used in an expression.

In addition to the standard operations, the following functions can be used within an expression:

sqrt($x 
sin($x)
cos($x)
tan($x) 
asin($x)
acos($x)
atan($x)
exp($x) 
log($x)    - natural logarithm.
theta($x)  - Heaviside step function (theta($x)=1 if $x&>amp;0 and theta($x)=0 otherwise)
abs($x)    - absolute value of $x  
sign($x)   - sign($x) = 1 for positive $x, and sign($x) = -1 for negative $x
int($x)    - returns integer part of $x
fact($x)   - computes factorial of integer $x, $x must belong to [1,20] interval
hro($P)    - computes H*rho in kG cm for given momentum $P im MeV/c 
gauss($x)  - generates a random number with Gaussian distribution and sigma equal to $x

Variables and functions name are case-sensitive.

A few pre-defined constants are available. They can be refined if necessary. These constants are:

$pi = $PI = 3.1415926535897932385;
$e = $E = 2.7182818284590452354;
$Me = 0.511006	-	the mass of electron in MeV;
$Mp = 938.2723	-	the mass of proton in MeV;
$Mmu = 105.6		-	the mass of muon in MeV;
$c = 2.997925e10	-	the light velocity in cm/s;
$_turn                  -	Internal variable used in the tracking. 

\$_turn is set to 1 on the first turn. If requested (tracking parameters dialog) \$_nturn is incremented by 1 after each turn during tracking. This variable can be used to change lattice parameters, accelerating voltage, etc. at each turn if necessary. All expressions within the math header are evaluated in double precision. Variables defined in the math header can be used inside the main body of the file (after OptiM line). The variables names will be replaced by their values (nine digit accuracy) during parsing. Character strings may be used in math header. See the Math Header example describing a FODO cell with a dipole magnet for an example. Do-While loops can be used to help with calculations and/or to fill arrays. The construct is similar to the Do-While loop in C with the difference that the keywords include { and } i.e. the loop begins with "do{" and this is the only keyword allowed on this line. The loop ends with a "} while" keyword which must be followed by an expression. The iterations continue as long as this expression is positive. In the example below, a loop is used to fill the 10 elements of an array s :

ARRAY $s[10];
$n=           0;  
do{
	$s[$n]=$n+100;  
	$n=$n+1;  
}while 10-$n

Nested loops and multidimensional arrays are not allowed. To avoid infinite loops the maximum number of iterations is limited to 10,000. Note that in the main body of the file (after the math header) anything appearing after the = sign is assumed to be a mathematical expressions. This rule applies to element parameters and variables in service blocks. It is important to remember that performing the Edit| Analyse Lattice function (pressing F2 key) will replace all variables with their numerical values. Taking into account that this destroys the connection of the lattice description with the math-header, the user will be prompted for a confirmation. Similarly, the Edit|Read Field Integral command and Fitting|Betas commands will substitute new numerical values for elements that are affected. The Edit|Increment and Edit|Decrement commands can be used to interactively change a variable, as long as the assignement is of form: \$VariableName= value, where value is a numerical value.

Math header example
Example describes a FODO cell with a dipole magnet. The magnet has parallel edges and edge sextupole field:
$P=4000;  #beam  momentum of 4 GeV
$E=sqrt($P*$P+$Me*$Me)-$Me;  =>  3999.48903; #beam energy for electrons
$fi=10;  #bending angle of 20 deg.
$L=200; #magnet length of 200 cm;
$HR=$P/($c*1e-11);  =>  13342.5619;  #rigidity in kG cm
$B=$HR/$L*$fi/180*$pi; =>  11.6435818;   #magnetic field in kG
$FIedge=$fi/2;
$Sint=0.05;  #integral sextupole strength
$Lsext=1e-3;
$Ssext=$Sint/$Lsext
$Dipole="hDip Sedge Gedge bDipole Gedge Sedge hDip";
OptiM
Energy[MeV]=$E   Mass[MeV]=0.511006   Hr[kG*cm]=335.264 
Emittance: ex[cm]=1e-05  ey[cm]=1e-07  DP/P=0.0001 
Initial:	BetaX[cm]=1207.15 	BetaY[cm]=581.058 
	AlfaX=-1.35249 	AlfaY=0.675715 
	DispersX[cm]=653.417 	DispersY[cm]=0 
	Dsp_PrimeX=0.738743 	DspPrimeY=0 
	X[cm]=0 	Y[cm]=0 	Z[cm]=0 	S[cm]=0 
	tetaX[deg]=0 	tetaY[deg]=0 
begin lattice. Number of periods=1 
qF o $Dipole&2 o qD o $Dipole&3 o
end lattice
begin list
o          	L[cm]=15 
Sedge   	L[cm]=$Lsext   	S[kG/cm/cm)]=$Ssext
Gedge  	B[kG]=$B   	Angle[deg]=$FIedge  EffLen[cm]=5  Tilt[deg]=0  
Bdipole 	L[cm]=$L   	B[kG]=$B   	G[kG/cm]=0  	Tilt[deg]=0
qF        	L[cm]=30   	G[kG/cm]=1 	Tilt[deg]=0
qD        	L[cm]=30   	G[kG/cm]=-1 	Tilt[deg]=0
hDip     	Ax[cm]=0  Ay[cm]=0  Shape=0  OffsetX[cm]=0  OffsetY[cm]=0 	Tilt[deg]=0
end list of elements

The operator & adds tags for a dipole in the list so that the dipoles of the same design could be described once but every dipole in the lattice would have a unique name.