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 ) :
file reference startand 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.
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").
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
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
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.