Changeset 11 in TRACY3 for trunk/tracy/tracy/doc


Ignore:
Timestamp:
Oct 21, 2013, 10:40:43 AM (11 years ago)
Author:
zhangj
Message:
 
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/tracy/tracy/doc/soltracy3_userManual_developer.tex

    r10 r11  
    88\usepackage[colorlinks=true,urlcolor=magenta,citecolor=blue]{hyperref}
    99\usepackage{color}
     10\usepackage{setspace}
     11
     12
     13%% auto center the sentence in the line
     14\newenvironment{tightcenter}{%
     15   \vspace{0.02in}
     16 \setlength\topsep{0pt}
     17  \setlength\parskip{0pt}
     18  \begin{center}
     19}{%
     20  \end{center}
     21\vspace{0.02in}
     22 }
     23
     24%% auto wrap a long word
     25\newcommand*\wrapletters[1]{\wr@pletters#1\@nil}
     26\def\wr@pletters#1#2\@nil{#1\allowbreak\if&#2&\else\wr@pletters#2\@nil\fi}
     27
     28% define the file path font
     29\newcommand{\pathfont}[1]{\textit{\wrapletters{#1}}}
     30% define the font and color of the Tracy command in Tracy file
     31\newcommand{\tracycommand}[2]{\begin{tightcenter}
     32                               \textsf{\textcolor{red}{#1}} \quad \textsf{\textcolor{blue}{#2}}
     33                              \end{tightcenter}}
     34\newcommand{\tracycomm}[1]{\textsf{\textcolor{red}{#1}}}
     35\newcommand{\tracypara}[1]{\textsf{\textcolor{blue}{#1}}}
     36
     37% lattice element definition
     38\newcommand{\latticedef}[3]{\begin{tightcenter}
     39                               \textsf{\textcolor{black}{#1}}   
     40                               \textsf{\textcolor{red}{#2}} \quad \textsf{\textcolor{blue}{#3}}
     41                              \end{tightcenter}}
     42\newcommand{\elemname}[1]{\textsf{\textcolor{black}{#1}}}
     43\newcommand{\elemkeyword}[1]{\textsf{\textcolor{red}{#1}}}
     44\newcommand{\elempara}[1]{\textsf{\textcolor{blue}{#1}}}
     45
     46\newcommand{\notespace}[1]{\vspace{0.1in}\textbf{#1} \vspace{0.05in}}
     47
    1048
    1149\begin{document}
    … …  
    1452\tableofcontents
    1553
     54%\onehalfspacing
     55
    1656\section{Log}
    1757
    1858\begin{itemize}
    19 \item[05/10/2012] Add the control flag to control the entrance and exit edge effects and fringe field of the dipole, with``edge\_effect1 = 1'' in the dipole definition in the lattice file, the
     59\item[05/10/2012] Add the control flag to control the entrance and exit edge effects and fringe
     60field of the dipole, with``edge\_effect1 = 1'' in the dipole definition in the lattice file, the
    2061entrance edge effect and fringe field of the dipole are turned on, with ``edge\_effect1 = 0'',
    2162this effects are turned off. These two effects at the exit of the dipole are controlled by
    … …  
    2465
    2566\section{Introduction}
    26   Tracy is a code to do long term tracking, and is written in the mixture of c and c++. This code is kept on developing. Soleil version of Tracy 3 is a code with more flexibility and easy to use.  User does not need to know the structure of the code, what they need to do is to write an input script, and then run the code.
     67  Tracy is a code to do long term tracking, and is written in the mixture of c and c++.
     68This code is kept on developing. Soleil version of Tracy 3 is a code with more flexibility and easy to use.  User does not need to know the structure of the code, what they need to do is to write an input script, and then run the code.
    2769   Based on the need, user can write the files to define multipole field errors, misalignment errors of the lattice elements, and vacuum chamber, and then provide the file name in the user input script, in order to set the field errors of the lattice elements and the vacuum limit for the different region of the lattice.
    2870Attention:
    … …  
    3072Although the user can define the file name whatever they want,  it is suggested to name the file which is used to define multipole field error with the extension “.fe” and name the file which is used to define the misalignment error with the extension “.ae”.   
    3173
    32   There are two versions of Tracy 3, non-parallel version and parallel version.  Non-parallel version Tracy is for the single computer, parallel version of Tracy is for the the cluster. The user defined input script “*.prm” can be used for both parallel and non-parallel version Tracy.
     74  There are two versions of Tracy 3, non-parallel version and parallel version.  Non-parallel version Tracy is for the single computer, parallel version of Tracy is for the the cluster. The user defined input script which can be used for both parallel and non-parallel version Tracy. The ascii file with any extension isacceptable for Tracy3, but the extension is suggested to be “.prm”.
     75
    3376\section{ Non-parallel version Tracy}
    3477\subsection {Compile}
    35   The make file of Tracy is generated by “automake”. Based on the compilers used, user needs to update “make\_for\_gcc.sh” under path ``\$HOME/TracyIII/'' or the ``Makefile.am'' under path ``\$HOME/TracyIII/tracy/tracy/src'' and ``\$HOME/TracyIII/tracy/tools''. The compilers used on the server ``metis'' of SOLEIL Synchrotron are ``gfortran'', and ``gcc''.
    36 
    37    To compile the code, run
    38 
    39 make\_for\_gcc.sh        opt
    40 
    41 under the shell terminal, an executive file ``soltracy'' is automatically generated under path ``\$HOME/TracyIII/tracy/tools''.   
     78The make file of Tracy is generated by “automake”. Based on the compilers used,
     79user needs to update “\textsf{\wrapletters{make\_for\_gcc.sh}}” under
     80path ``\pathfont{\$HOME/TracyIII/}''
     81or the ``Makefile.am'' under path ``\pathfont{\$HOME/TracyIII/tracy/tracy/src}''
     82and ``\pathfont{\$HOME/TracyIII/tracy/tools}''. The compilers used on the server
     83``metis'' of SOLEIL Synchrotron are ``gfortran'', and ``gcc''.
     84
     85To compile the code, run the command under the shell terminal:
     86\begin{tightcenter}
     87 \textsf{make\_for\_gcc.sh}     \qquad   \textsf{opt}
     88\end{tightcenter}
     89Then the executive file ``soltracy'' is automatically
     90generated under path ``\pathfont{\$HOME/TracyIII/tracy/tools}''.   
    4291
    4392\subsection{Run}
    44 
    45   To execute Tracy, user needs to provide an input script with the file extension “.prm”.  For example, ``Input\_test.prm'' is a user defined script, user can type the command line
    46  
    47 soltracy               Input\_test.prm
    48 
    49 under the shell terminal, and then press ``return'' key to execute the code. The input script file name can be defined with any valid string except it must be ended with the file extension ``.prm''.
     93 To execute Tracy, the user needs to define an input file with the
     94 the lattice file names and the related commands (section~\ref{}).
     95 The name of the input file can be any valid characters. Although
     96 there is no limitation to the extension of the file, the extension
     97 ``.prm'' is preferred. For example, To run the user defined input file
     98 ``Input\_test.prm'', user can type the command:
     99\begin{tightcenter}
     100  \textsf{soltracy}       \qquad        \textsf{Input\_test.prm}
     101\end{tightcenter}
    50102
    51103\section{ Parallel version Tracy}
    … …  
    63115
    64116\subsection{Compile}
    65 The commonly used compilers for parallel computation are MPI 2, and Intel MPI which is based on MPI 2. For the cluster of SOLEIL Synchrotron, Intel MPI is installed. To get the parallel Tracy work, three files of the non-parallel version Tracy need to be modified.
    66 The details are shown in the following steps.
     117The commonly used compilers for parallel computation are MPI 2, and Intel
     118MPI which is based on MPI 2. For the cluster of SOLEIL Synchrotron, Intel
     119MPI is installed. To get the parallel Tracy work, three files of the
     120non-parallel version Tracy need to be modified. The details are shown in
     121the following steps.
    67122\begin{enumerate}
    68123\item
    69124The path of included files of Intel MPI is added in ``Makefile.am'' under
    70 path ``\$HOME/TracyIII/tracy/tracy/src'' (shown in BLUE color):
    71 
    72           INCLUDES = -I../inc -I\$(NUM\_REC)/inc
    73           -I/opt/intel/impi/3.2.2.006/include64 
     125path ``\pathfont{\$HOME/TracyIII/tracy/tracy/src}'' (shown in BLUE color):
     126
     127          \wrapletters{INCLUDES = -I../inc -I\$(NUM\_REC)/inc \quad
     128          -I/opt/intel/impi/3.2.2.006/include64}
     129
    74130\item
    75131 The execute file, source file, paths of included files and library of Intel
    76 MPI are modified in ``Makefile.am'' under path ``\$HOME/TracyIII/tracy/tools''
     132MPI are modified in ``Makefile.am'' under path ``\pathfont{\$HOME/TracyIII/tracy/tools}''
    77133 (shown in BLUE color):
    78134
    79135bin\_PROGRAMS = psoltracy
    80136
    81 soltracy\_SOURCES  = soltracy.cc  nrutil.c nrcheck.c   
    82   nrlinwww.c   nrframe.c ../tracy/src/tracy\_lib.cc   ->
    83   psoltracy\_SOURCES  = psoltracy.cc  nrutil.c  nrcheck.c   
    84   nrlinwww.c   nrframe.c   ../tracy/src/tracy\_lib.cc
    85 
    86   LIBS = -L\$(NUM\_REC)/lib
    87   -L/opt/intel/impi/3.2.2.006/lib64   -L\$(LIBPATH) 
    88     -lrecipes\_c\_icc -lstdc++ -lgfortran -lmpichcxx
     137soltracy\_SOURCES  = \texttt{soltracy.cc  nrutil.c nrcheck.c    }
     138\texttt{  nrlinwww.c   nrframe.c ../tracy/src/tracy\_lib.cc $\rightarrow$}
     139
     140  psoltracy\_SOURCES  = \texttt{psoltracy.cc  nrutil.c  nrcheck.c   
     141  nrlinwww.c   nrframe.c   ../tracy/src/tracy\_lib.cc}
     142
     143  LIBS =  \texttt{\wrapletters{-L\$(NUM\_REC)/lib \quad
     144          -L/opt/intel/impi/3.2.2.006/lib64   \quad -L\$(LIBPATH)  \quad
     145          -lrecipes\_c\_icc \quad -lstdc++ \quad -lgfortran \quad -lmpichcxx}}
    89146 
    90 INCLUDES = -I\$(TRACY\_LIB)/tracy/inc -I\$(NUM\_REC)/inc
    91   -I/opt/intel/impi/3.2.2.006/include64
     147INCLUDES = \texttt{\wrapletters{-I\$(TRACY\_LIB)/tracy/inc \quad -I\$(NUM\_REC)/inc
     148                   \quad  -I/opt/intel/impi/3.2.2.006/include64}}
     149
    92150\item
    93 The compilers used in the parallel computing are defined in the ``make\_for\_psoltracy.sh'' located in path ``\$HOME/TracyIII'' as (shown in BLUE color):
    94 
    95 CC = mpiicc
    96 
    97                 CXX = mpiicpc
    98 
    99                 F77 = mpiifort
     151The compilers used in the parallel computing are defined in the
     152``\wrapletters{make\_for\_psoltracy.sh}'' located in path ``\$HOME/TracyIII''
     153as (shown in BLUE color):
     154
     155                 CC = \texttt{mpiicc}
     156
     157                CXX = \texttt{mpiicpc}
     158
     159                F77 = \texttt{mpiifort}
    100160
    101161Depending on the compilers used to do parallel computation, user needs to
    … …  
    103163files and library which are shown above with blue color.
    104164
    105  After updating compilers, paths of included files and library for parallel
     165After updating compilers, paths of included files and library for parallel
    106166computation, user can run
    107 
    108 make\_for\_psoltracy.sh
    109 
     167\begin{tightcenter}
     168\textsf{make\_for\_psoltracy.sh}
     169\end{tightcenter}
    110170under the shell script to compile the parallel Tracy. After compilation,
    111171the execute file ``psoltracy'' is automatically generated under the
    112 path ``\$HOME/TracyIII/tracy/tools''.
    113 
    114 
     172path ``\pathfont{\$HOME/TracyIII/tracy/tools}''.
    115173\end{enumerate}
    116174
     175
    117176\subsection{Run}
    118   As the non-parallel version Tracy, user needs to write the commands in a script which must be with the file extension “.prm”. The syntaxes to define the script “*.prm” are the same for both non-parallel and parallel Tracy.
    119   To run the parallel Tracy, user need to contact the administrator of their cluster to know how to run parallel programs on the cluster. For the cluster on Synchrotron SOLEIL, the nodes used to do parallel computation are assigned by PBS (Portable Batch System), so a script is need. For example, user define the input script “test.prm” to tell Tracy what jobs are need to be done on the cluster,  define script “lance\_tracy3\_parallel.sh” to assign the numbers of CPUs to do parallel computation and lance job to the SOLEIL cluster. and then type the following command under the bash shell to submit the job and run the parallel Tracy on the cluster:
    120 
    121     lance\_tracy3\_parallel.sh     test.prm
     177As the non-parallel version Tracy, user needs to write the commands in a
     178script which must be with the file extension ``.prm''. The syntaxes to define
     179the script ``*.prm'' are the same for both non-parallel and parallel
     180Tracy.
     181
     182To run the parallel Tracy, user need to contact the administrator of their
     183cluster to know how to run parallel programs on the cluster. For the cluster
     184on Synchrotron SOLEIL, the nodes used to do parallel computation are assigned
     185by PBS (Portable Batch System), so a script is need. For example, user define
     186the input script \texttt{test.prm} to tell Tracy what jobs are need to be done on the
     187cluster,  define script \textsf{\wrapletters{lance\_tracy3\_parallel.sh}} to assign
     188the numbers of CPUs to do
     189parallel computation and lance job to the SOLEIL cluster; and then type the
     190following command under the bash shell to submit the job and run the parallel
     191Tracy on the cluster:
     192\begin{tightcenter}
     193  \textsf{lance\_tracy3\_parallel.sh  \qquad   test.prm}
     194\end{tightcenter}
     195
    122196
    123197\section{ User input script}
    124   There are two types of keywords in the user input script. The first type is to set the file, the file names, and define parameters for the related calculations; the key words for such definitions are ended with the characters “Flag”. The second type is to define Boolean commands with or without parameters to do different calculations. The rules of the definition of input scripts are:
    125 The blank lines and lines starting with "\#" (comment line) are ignored by the code.
    126 Keywords without “Flag” as the final 4 characters are NOT executed according to the defined sequence in user input script. If the same command keywords are defined many times in the user script, only the last defined keyword is executed.
    127 The commands with the last 4 characters as “Flag” are executed according to the sequence in the code.
    128 The definition of lattice file at the beginning of the user script is mandatory. If the lattice file is with any of the following elements: horizontal correctors, vertical correctors, girders, BPM, skew quadrupoles, user must declare the element name at the beginning of input script.
    129 One keyword command uses one line. User can not define more than one command at the same line.   
    130 Except explanation, all commands with Boolean flag are the generic commands, and can be used on all the lattice of the ring.
    131 \subsection{  File path}
    132    In the user input script, user can specify the name of the files which are used in the calculation, such as the lattice file, multipole field error file, misalignment error file, vacuum chamber file. When specifying the file name, user can provide the absolute path for the file which is not located at the current path, such as: “/home/physmach/Tracy3/tracy/soleil.lat”; or for convenience, user provides the filename without absolute path, but put the files at a certain directory and then specific this directory using the command:
    133                        in\_dir            user\_defined\_path
    134         For example:
    135                        in\_dir                /home/zhang/codes/TracyIII/lattice/
    136 
    137 This command tells the code all the files specified in the script are located at the directory “/home/zhang/codes/TracyIII/lattice/”. If user declares the files without absolute path and does not set the directory through command in\_dir; or the files specified in the script are not found at the current working path, the code will give an error message and stop running.
    138 
    139 \section{  File names}   
     198There are two types of keywords in the user input script. The first type is
     199to set the file, the file names, and define parameters for the related
     200calculations; the key words for such definitions are ended with the
     201characters ``Flag''. The second type is to define Boolean commands with or
     202without parameters to do different calculations. The rules of the definition
     203of input scripts are:
     204\begin{itemize}
     205\item
     206The blank lines and lines starting with ``\#'' (comment line) are ignored
     207by the code.
     208\item
     209Keywords without ``Flag'' as the final 4 characters are NOT executed according
     210to the defined sequence in user input script. If the same command keywords
     211are defined many times in the user script, only the last defined keyword is
     212executed.
     213\item
     214The commands with the last 4 characters as ``Flag'' are executed according
     215to the sequence in the code.
     216\item
     217The definition of lattice file at the beginning of the user script is mandatory.
     218\item
     219If the horizontal correctors, or vertical correctors, or girders, Beam Position
     220Monitors, or skew quadrupoles are defined in the lattice file, user must
     221declare the element name at the beginning of Tracy input file.
     222\item
     223One keyword command uses one line. User can not define more than one command
     224at the same line.   
     225\item
     226Except explanation, all commands with Boolean flag are the generic commands,
     227that is, the commands are not machine dependent.
     228\end{itemize}
     229
     230\subsection{File path}
     231In the user input script, user can specify the name of the files which are used
     232in the calculation, such as the lattice file, multipole field error file,
     233misalignment error file, vacuum chamber file. When specifying the file name without
     234file path in the Tracy input file, Tracy will look for the file in the current
     235work path. Otherwise, user need to provide the absolute path of the file which is
     236not located at the current path, such as: ``\texttt{\wrapletters{/home/physmach/Tracy3/tracy/soleil.lat}}''.
     237Another method is to provide the filename without absolute path, but put all the
     238called external files at a certain directory, and this directory is defined in the
     239Tracy input file using the command:
     240                \tracycommand{in\_dir}{user\_defined\_path}
     241For example,
     242                \tracycommand{in\_dir}{/home/zhang/codes/TracyIII/lattice/}
     243This example tells the code all the files defined with absolute file path in the Tracy
     244input file are located
     245at the directory \pathfont{/home/zhang/codes/TracyIII/lattice/}. If user declares the files
     246without absolute path and does not set the directory through command \textsf{in\_dir}; or
     247the files specified in the script are not found at the current working path,
     248the code will give an error message and stop running.
     249
     250\section{File names}   
    140251
    141252\subsection{Lattice file name}
    142 In the input script, user must define the lattice name, this is mandatory. The command is:   
    143 lat\_file            lattice\_file\_name
    144 Here “lattice\_file\_name” is the lattice file name without “.lat” extension. For example, the following command sets the lattice file of SOLEIL ring:
    145 lat\_file   solamor2\_reglage\_focalisation\_chcvqt\_thicksextu\_LQPintermediaire\_QFF
    146   In Tracy 3, after reading the lattice, Twiss parameters are automatically printed to the file “linlat.out”.                                 
    147   If one of these elements (Horizontal/vertical correctors or beam position monitors, or girders, or skew quadrupoles.) are defined in the lattice file, for example to read the misalignment errors of the lattice element and then do orbit correction, to read multipole field errors (SOLEIL lattice), etc.; user MUST specify the names of these elements using the corresponding commands in the “*.prm” script:
    148 h\_corr             HCM
    149 v\_corr             VCM
    150 gs                     GS
    151 ge                     GE
    152 bpm\_name     BPM
    153 qt                     QT
    154 Here “HCM” is the name of horizontal correctors used for horizontal orbit correction, or the horizontal correctors on which the multipole field errors are added in SOLEIL lattice;  “VCM” is the name of vertical correctors used for vertical orbit correction, or the vertical correctors on which the multipole field errors are added in SOLEIL lattice; “GS” is the name of the start girder;  ‘GE’ is the name of the end girder; “BPM” is the name of beam position monitors defined in the lattice file; “QT” is the name of the skew quadrupoles defined in the lattice.  Generally, user needs to define horizontal, vertical correctors and BPMs when reading the misalignment errors or correcting closed orbit distortion 
     253In the input script, user must define the lattice name, this is mandatory.
     254The command is:
     255
     256\tracycommand{lat\_file}{lattice\_file\_name}
     257
     258Here \tracypara{lattice\_file\_name} is the lattice file name without the extension ``.lat''.
     259For example, the following command sets the lattice file of SOLEIL ring:
     260\tracycommand{lat\_file}{solamor2}
     261
     262n Tracy 3, after reading the lattice, Twiss parameters are automatically printed to the
     263file \textsl{linlat.out}.                                 
     264 
     265If one of these elements (Horizontal/vertical correctors or beam position monitors, or
     266girders, or skew quadrupoles.) are defined in the lattice file, for example to read
     267the misalignment errors of the lattice element and then do orbit correction, to read multipole
     268field errors (SOLEIL lattice), etc.; user MUST specify the names of these elements using the
     269corresponding commands in the Tracy input file:
     270\tracycommand{h\_corr}{HCM}
     271\tracycommand{v\_corr}{VCM}
     272\tracycommand{gs}{GS}
     273\tracycommand{ge}{GE}
     274\tracycommand{bpm\_name}{BPM}
     275\tracycommand{qt}{QT}
     276Here \tracypara{HCM} is the name of horizontal correctors for horizontal orbit correction,
     277or the horizontal correctors on which the multipole field errors are added in SOLEIL lattice;
     278\tracypara{VCM} is the name of vertical correctors used for vertical orbit correction, or
     279the vertical correctors on which the multipole field errors are added in SOLEIL lattice;
     280\tracypara{GS} is the name of the start girder; \tracypara{GE} is the name of the end girder;
     281\tracypara{BPM} is the name of beam position monitors defined in the lattice file;
     282\tracypara{QT} is the name of the skew quadrupoles defined in the lattice.  Generally,
     283user needs to define horizontal, vertical correctors and BPMs when reading the misalignment
     284errors or correcting closed orbit distortion. 
    155285
    156286\subsection{Multipole field error file name (SOLEIL lattice)}
    157   User can read the multipole field errors on SOLEIL lattice from an external file; the file is specified in the user script using the following command:
    158 multipole\_file           multipole\_file\_name
    159 Here “multipole\_file\_name” is the user defined multipole field error file, the format of this file is given in section Error: Reference source not found.
    160 
    161 If the multipole field errors of horizontal, vertical correctors and skew quadrupoles are defined in the “multipole\_file”, user MUST specify the names of these lattice elements in the “*.prm” file as the following example:
    162 h\_corr      CH
    163 v\_corr      CV
    164 qt              QT
    165 Here “CH”, “CV” and “QT” are the names of horizontal, vertical correctors, and skew quadrupoles respectively which are defined in the lattice file.
     287User can read the multipole field errors on SOLEIL lattice from an external file;
     288the file is specified in the user script using the following command:
     289\tracycommand{multipole\_file}{multipole\_file\_name}
     290Here \tracypara{multipole\_file\_name} is the user defined multipole field error file,
     291the format of this file is given in section~\ref{}.
     292
     293If the multipole field errors of horizontal, vertical correctors and skew quadrupoles
     294are defined in the \tracypara{multipole\_file}, user MUST specify the names of these
     295lattice elements in the Tracy input file as the following example:
     296\tracycommand{h\_corr}{CH}
     297\tracycommand{v\_corr}{CV}
     298\tracycommand{qt}{QT}
     299Here \tracypara{CH}, \tracypara{CV} and \tracypara{QT} are the names of horizontal,
     300vertical correctors, and skew quadrupoles respectively which are defined in the lattice file.
    166301
    167302\subsection{Files of multipole field errors of correctors and skew quadrupoles (SOLEIL lattice)}
    168   Horizontal, vertical correctors and skew quadrupoles are integrated with the sextupole quadrupoles on SOLEIL storage ring. To define the multipole field errors on these elements, user need to define the orders and relative strengths of multipole field errors in the multipole  field error file (section Error: Reference source not found) and specify the file name in the user input script “*.prm” (section Multipole field error file name), then specify the file names as the following example:
    169 fic\_hcorr         corh.txt
    170 fic\_vcorr         corv.txt
    171 fic\_skew          corqt.txt
    172 Here “corh.txt” and “corv.txt” are the files with measured current values corh, corv, corqt (with unit [Ampere]) for the horizontal, vertical correctors and skew quadrupoles respectively. Based on the measured current values, user can get the integrated field strength as:
    173 Hcorr\_strength [T.m] = corh *\_convHcorr /brho; (horizontal correctors)
    174 Vcorr\_strength [T.m] = corv *\_convVcorr /brho;  (vertical correctors)
    175 Qt\_strength [T.m] = corqt *\_convQt /brho;  (skew quadrupoles)
    176 here brho is the momentum rigidity, and the conversion constants between current and field are \_convHcorr = 8.14e-4, \_convVcorr = 4.642e-4, \_convQt = 93.83e-4.
    177   For SOLEIL lattice, the SAME ORDER of multipole field errors on the same elements are added together, so the SAME ORDER of horizontal/vertical, skew quadrupoles, and sextupoles are added together since these elements are integrated at the same magnets.
     303Horizontal, vertical correctors and skew quadrupoles are integrated with the sextupole quadrupoles
     304on SOLEIL storage ring. To define the multipole field errors on these elements, user need to define the orders and relative strengths of multipole field errors in the multipole  field error file (section Error: Reference source not found) and specify the file name in the user input script “*.prm” (section Multipole field error file name), then specify the file names as the following example:
     305\tracycommand{fic\_hcorr}{corh.txt}
     306\tracycommand{fic\_vcorr}{corv.txt}
     307\tracycommand{fic\_skew}{corqt.txt}
     308Here \tracypara{corh.txt} and \tracypara{corv.txt} are the files with measured current values corh,
     309corv, corqt (with unit [Ampere]) for the horizontal, vertical correctors and skew quadrupoles
     310respectively. Based on the measured current values, user can get the integrated field strength as:\\
     311\vspace{0.02in}
     312\texttt{Hcorr\_strength [T.m] = corh *\_convHcorr /brho; (horizontal correctors) \\}
     313\vspace{0.02in}
     314\texttt{Vcorr\_strength [T.m] = corv *\_convVcorr /brho;  (vertical correctors)} \\
     315\vspace{0.02in}
     316\texttt{Qt\_strength [T.m] = corqt *\_convQt /brho;  (skew quadrupoles)} \\
     317\vspace{0.02in}
     318
     319Here brho is the momentum rigidity, and the conversion constants between current and field are \texttt{\_convHcorr} = 8.14e-4, \texttt{\_convVcorr} = 4.642e-4, \texttt{\_convQt} = 93.83e-4.
     320 
     321For SOLEIL lattice, the SAME ORDER of multipole field errors on the same elements are added together,
     322so the SAME ORDER of horizontal/vertical, skew quadrupoles, and sextupoles are added together since
     323these elements are integrated at the same magnets.
    178324
    179325\subsection{ File to define field strength of virtual coupling source elements (SOLEIL lattice)}
    180   On SOLEIL storage ring, the coupling is thought to come from the rotation of quadrupoles and vertical displacements of sextupoles. The strengths of these coupling sources are written in a file, then read by the following command:
    181 virtualskewquad\_file   virtual\_skew\_quad\_currents.txt
    182 
    183 Here “virtual\_skew\_quad\_currents.txt” is the user defined file with strength of vertical coupling source.
    184   In order to use this command to read the virtual sources of coupling, user needs to define the virtual coupling element as a skew quadrupole in the lattice file:
    185 SQ: quadrupole, tilt=45.0, K= 0.0, method=4, N=1;
     326 On SOLEIL storage ring, the coupling is thought to come from the rotation of quadrupoles
     327and vertical displacements of sextupoles. The strengths of these coupling sources are
     328written in a file, then read by the following command:
     329\tracycommand{virtualskewquad\_file}{virtual\_skew\_quad\_currents.txt}
     330
     331Here \tracypara{virtual\_skew\_quad\_currents.txt} is the user defined file with strength
     332of vertical coupling source.
     333
     334In order to use this command to read the virtual sources of coupling, user needs to define
     335the virtual coupling element as a skew quadrupole in the lattice file:
     336\latticedef{SQ:}{quadrupole,}{tilt=45.0, K= 0.0, method=4, N=1;}
    186337and this virtual coupling element MUST be with the name “SQ”. Now there 152 elements defined as the virtual coupling sources in the SOLEIL lattice. The syntaxs to define skew quadrupole are explained in section .
    187338  The measured current value qtcorr[i] of the ith coupling source is converted to the corresponding integrated skew quadrupole field strength corr\_strength as
    … …  
    435586\subsection{kick map}
    436587
    437 \section{  Commands}
     588
     589\section{ Lattice file}
     590In the lattice, RF cavity with the correct harmonic number must be defined!!!
     591Otherwise Tracy will give the error message:
     592\textcolor{red}{Elem\_GetPos: there are no kids in family 0 ()}. This obigatory is for the
     593correct calculation of positive/negtive momentum compaction factor.
     594To deactive the RF cavity, the cavity voltage can be defined as 0.
     595
     596
     597The followings are the rules to define a lattice file used in Tracy 3. The curvelinear coordinates are
     598used. \textbf{The ideal particle or design particle sees the perfect magnetic field in all magnets, and its}
     599\textbf{orbit is used as the reference orbit and base of the curvilinear coordinate}. Since the reference orbit
     600is a curve inside the dipoles and a straight line in other lattice elements (drifts and the magnets except
     601dipoles), so the length of the dipole is the the path length of the reference particle inside the dipole
     602which is equal to $\rho*\theta$ where $\rho$ is the bending radius of the dipole and $theta$ is the bending angle
     603with unit [rad], and all the other magnet lengths are the straight length of the magnets.
     604
     605Due to the same reason, the curvature of the curvilinear cooridnates h = 1/$\rho$ is not zero only inside dipole;
     606in other magnets and drift h = 0, and the curvilinear coordinates goes to cartesian cooridnates.
     607As a result, the independent variable $s$ inside the dipole harmitonian is the arc length, while the staight
     608length in other lattice elements.
     609
     610\subsection{Lattice}
     611The $n^{th}$ field component of the lattice element is defined as in Tracy (n = 1, 2, 3, 4 ...):
     612\begin{eqnarray*}
     613b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0} \\
     614a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0} \\
     615B \rho & = & \frac{p_0}{e}
     616\end{eqnarray*}
     617$B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, $e$ is the electric charge.
     618For example, for sextupole,  n = 3, so $b_3$ and $a_3$ are defined as
     619\begin{eqnarray*}
     620b_3 & = & \frac{1}{B \rho} \frac{1}{2} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0} \\
     621a_3 & = & \frac{1}{B \rho} \frac{1}{2} \frac{\partial^{2} B_x }{\partial x ^{2}}|_{x=0,y=0}
     622\end{eqnarray*}.
     623
     624 \notespace{NOTES:}
     625In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the definition of are the same as in \textbf{Tracy}.
     626While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the order of the field compoent start from 0, that is
     627n = 0, 1, 2, 3, ..., and the $n^{th}$ field strength components of the lattice element $b_n$ and $a_n$ are defined as
     628\begin{eqnarray*}
     629b_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_y }{\partial x ^{n}}|_{x=0,y=0} \\
     630a_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_x }{\partial x ^{n}}|_{x=0,y=0} \\
     631B \rho & = & \frac{p_0}{e}
     632\end{eqnarray*}
     633For example, for sextupole,  n = 3, its field component $b_2$ and $a_2$ are defined as
     634\begin{eqnarray*}
     635b_2 & = & \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0} \\
     636a_2 & = & \frac{1}{B \rho} \frac{\partial^{2} B_x }{\partial x ^{2}}|_{x=0,y=0}
     637\end{eqnarray*}.
     638
     639
     640                               
     641\subsection{Syntax}
     642Every line embraced by “{}” is comment line. For example:
     643
     644          {*****drift space *****}
     645
     646Each sentence is ended by ‘;’ or no punctuation.
     647Tracy is not sensitive to capital/small letters in the lattice.
     648User can define any lattice element with any valid name (but must start with a character) they want, but the element type is fixed.
     649For the lattice of the ring, the definition of RF cavity is mandatory, and the harmonic number of the RF cavity is also mandatory; for the lattice of the linac, the definition of the RF cavity is optional.
     650
     651\subsection{Variables}
     652  User can define the variables in the lattice file. For example:
     653\begin{tightcenter}
     654                   \textsf{Intmeth = 4};
     655\end{tightcenter}
     656Then when the code is running,  the variable \textsf{intmeth} in the lattice
     657file will be replaced by \textsf{4}.
     658
     659Tracy accept math operation. For example,
     660\latticedef{DL1: }{drift,}{L = 0.1*2 + 0.1-0.01;}
     661
     662\subsection{Start line}
     663  The lattice file must begin with the sentence:
     664\begin{tightcenter}
     665                \textsf{define} \quad    \textsf{lattice};
     666\end{tightcenter}
     667This definition is mandatory.
     668
     669\subsection{Global variables}
     670  After define the ring, user needs to define the system parameters of the lattice:
     671Energy, the beam energy with unit [GeV].
     672 dP, the relative momentum offset of the particle.
     673CODeps, the convergence for the algorism to find the closed orbit.
     674 For example:
     675                Energy = 2.739;
     676dP    = 1.0d-10;
     677                                                           CODeps= 1.0d-15;
     678These definitions are mandatory.
     679
     680\subsection{DRIFT}
     681
     682                  \latticedef{Name:}{drift,}{L = $\langle \dots \rangle$;}
     683
     684\begin{table}[htbp]
     685\centering
     686\caption{Parameters of dipole in the lattice file.}
     687\label{tab:dipole-para}
     688%\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.1\linewidth} | p{0.6\linewidth} |}
     689\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     690\hline
     691\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
     692\hline
     693\textbf{L}  & [m]     & 0.0 & Length.  \\
     694\hline
     695\end{tabular}
     696\end{table}
     697The definition of the length of a drift is mandatory.
     698
     699\vspace{0.05in}
     700\textit{Example:}
     701                      \latticedef{SD1a:}{drift,}{L= 0.900000;}
     702
     703\subsection{DIPOLE}
     704
     705\latticedef{Element\_name:}{bending,}{L = $\langle \dots \rangle$, T = $\langle \dots \rangle$,
     706\textbf{T1} = $\langle \dots \rangle$, \textbf{T2}=$\langle \dots \rangle$,
     707\textbf{H1} = $\lbrack \dots \rbrack$, \textbf{H2}= $\lbrack \dots \rbrack$,
     708\textbf{gap} = $\lbrack \dots \rbrack$, \textbf{edge\_effect1} = $\lbrack \dots \rbrack$, 
     709\textbf{edge\_effect2} = $\lbrack \dots \rbrack$, \textbf{K} =$\lbrack \dots \rbrack$,
     710\textbf{method} = $\langle \dots \rangle$, \textbf{N} = $\langle \dots \rangle$;}
     711 
     712
     713
     714 \begin{table}[tbp]
     715 \centering
     716 \caption{Parameters of dipole in the lattice file.}
     717 \label{tab:dipole-para}
     718%% \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|l|c|c|p{0.4\linewidth}|}
     719\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     720 \hline
     721 \textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
     722 \hline
     723 \textbf{L}       & [m] & 0.0             &  Curved path length of
     724  the design particle inside the dipole. L = $\rho * \theta$, where $\rho$ is the
     725  bending radius of the dipole, and $\theta$ is the bending angle of the dipole.   \\
     726  \hline
     727 \textbf{T}     &[degree] & 0.0          & Total bending angle                      \\
     728 \hline
     729 \textbf{T1}    &[degree] & 0.0 & Entrance angle                            \\
     730  \hline
     731\textbf{T2}    &[degree] & 0.0 & Exit Angle \\
     732\hline
     733\textbf{K}     &   L $\neq$ 0, m$^{-2}$. \newline  L = 0, m$^{-1}$. & 0.0
     734               & L $\neq$ 0, quadrupole field strength; \newline L = 0, integrated field strength. \\
     735\hline                                             
     736\textbf{Method}  & - & 4 &   1,2,4. Symplectic integration method. The
     737            value ``1'' means $1^{\mathrm{st}}$ order, ``2'' means $2^{\mathrm{nd}}$ order,
     738           and ``4'' means $4^{\mathrm{th}}$ order.    \\
     739\hline
     740\textbf{Gap}    &[m] & 0.0 &   Distance between two poles of the dipole,
     741            the gap size determine the fringe field. If the gap size is 0, then the dipole has
     742            no fringe field (\textcolor{red}{??????}).   \\
     743\hline
     744\textbf{edge\_effect1} & - & 0 & 1/0.
     745                ``1'' to turn on the edge focusing effect and the fringe field at the entrance of
     746                  the dipole. ``0'' to turn off the two effects. \\
     747\hline
     748 \textbf{edge\_effect2} & - & 0 & 1/0. ``1'' to turn on the edge focusing effect and the
     749  fringe field at the exit of the dipole. ``0'' to turn off the two effects. \\
     750\hline
     751\textbf{N}      & - & 1 &  number of cut slices. \\
     752 \hline
     753 \end{tabular}
     754 \end{table}
     755
     756\vspace{0.05in}
     757For example:\\
     758\vspace{0.05in}
     759\textsf{beta\_gap=37e-3; tracy\_gap=beta\_gap*2*0.724;}
     760\latticedef{BEND1 :}{ \textbf{bending},}{ \textbf{L} = 1.05243, \textbf{T} = 11.25, \textbf{T1} = 5.5906,
     761\textbf{T2} = 5.67658, \textbf{K} = 0.00204,gap=tracy\_gap,
     762\textbf{edge\_effect1} = 1, \textbf{edge\_effect2} = 1, \textbf{N} = 4,
     763\textbf{method} = intmeth;}
     764
     765The parameters of ``bending'' are optional, the default values for the missing parameters are 0,
     766 and the default value for ``method'' is also 0.
     767
     768
     769\vspace{0.05in}
     770\textbf{Attention:}
     771\begin{itemize}
     772\item
     773The bending magnet in Tracy is a symplectic element.
     774The independent variable $s$ inside the dipole harmitonian is the arc length,
     775so the length of the dipole is defined the curved path length of the design
     776particle inside the dipole.
     777\item
     778One can refer to the definition of $T1$,$T2$, $H1$, $H2$ on page 116 of SLAC-75 for more
     779information.
     780\item
     781In the lattice files of ELEGANT, MADX and BETA, the dipole angles are defined with the unit [rad].
     782But in TRACY, the unit is [degree].
     783\item
     784BETA dipole gap is the Elegant gap; but Tracy dipole gap is different from
     785the definition in both BETA and Elegant.
     786Tracy definition of dipole with fringe field: \\
     787\textsf{
     788beta\_gap=0.04;
     789{tracy\_gap=beta\_gap*2*1/6;}
     790{Due to the Tanh-like fringe field, K1=0.2, and tracy\_gap = beta\_gap *2* FINT (K brown para.)}
     791tracy\_gap = beta\_gap*2*0.348;}
     792
     793
     794 \latticedef{DIP:}{bending,}{L=0.27646,T= 45, T1=0, T2=0,gap=tracy\_gap,edge\_effect1=1,edge\_effect2=1,method=intmeth,N=4;}
     795
     796Elegant definition of dipole with dipole fringe field: \\
     797\textsf{DIP: csbend,N\_KICKS=100,INTEGRATION\_ORDER=4,L=0.27646,angle= 0.785398, E1=0, E2=0,hgap=0.02,Fint=0.348,nonlinear=1,edge1\_effects=2,edge2\_effects=2,edge\_order=2;}
     798\end{itemize}
     799
     800\subsection{QUADRUPOLE}
     801\textbf{Definition:} \\
     802\latticedef{Element\_Name:}{ quadrupole,}{ L = $\lbrack \dots \rbrack$, tilt = $\lbrack \dots \rbrack$,
     803                            K =$\lbrack \dots \rbrack$, FF1 =  $\lbrack \dots \rbrack$,       
     804                            FF2= $\lbrack \dots \rbrack$, FFscaling =  $\lbrack \dots \rbrack$,
     805                            method = $\lbrack \dots \rbrack$, N= $\langle \dots \rangle$;}
     806
     807\begin{table}[htbp]
     808\centering
     809\caption{Parameters of quadrupoles in the lattice file.}
     810\label{tab:quad-para}
     811\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     812\hline
     813\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
     814\hline
     815         L & [m] &  0.0 & Length of the quadrupole \\
     816\hline
     817        Tilt & [degree] & 0.0  & tilt angle of the quadrupole.
     818                                 If ‘tilt’ is non-zero, then the
     819                                 quadrupole is a skew quadruple. \\
     820\hline
     821       K &  L $\neq$ 0, [m$^{-2}$]. \newline L = 0, [m$^{-1}$]. & 0.0 &  L $\neq$ 0, Gradient
     822$\frac{\frac{\partial B_y }{\partial x}}{B \rho}$; \newline  L = 0, integrated field strength
     823$\frac{\frac{\partial B_y }{\partial x} L }{B \rho}$. \\
     824  \hline                 
     825   FF1 & - & 0  & 1 or 0. \newline
     826                   1: to avtive fringe field at the left edge. \textsf{QuadFringeOnFlag}
     827   should be set in the Tracy input file. 0: left fringe field off. \\
     828\hline
     829   FF2 & - & 0  & 1 or 0. \newline
     830                   1: to avtive fringe field at the right edge. \textsf{QuadFringeOnFlag}
     831   should be set in the Tracy input file. 0: right fringe field off. \\
     832\hline
     833FFscaling & - & 1 & Scaling factor of the dipole fringe field. \\
     834\hline
     835Method & - & 4 & 1,2,4. Order of symplectic integration method. 
     836Value ``1'' means 1st order, ``2'' means 2nd order, and ``4'' means 4th order. \\
     837\hline
     838N & - & 1 & Pieces of the quadrupole to be cut when it is treated in the code. \\
     839\hline
     840\end{tabular}
     841\end{table}
     842
     843
     844
     845Example: \\
     846
     847\textsf{Nq=8/2; dgsurg=1.00; dgsurgL=1.00; quadfringe=1.0; LQC=0.3602;}
     848\latticedef{QP1a:}{quadrupole,}{ L=LQC/2, K= -1.073038*dgsurg, FF1=quadfringe, FF2=0,
     849              FFscaling =1, method=intmeth, N=Nq;}
     850
     851The parameters of “quadrupole” are optional, the default value for “method” is 4, the default value for “FFscaling” is 1, the default value for the other parameters are 0.
     852
     853\subsection{SKEW QUADRUPOLE}
     854
     855The skew quadrupole is a quadrupole with a 45 [degree] tilt angle. For example:
     856\latticedef{QT:}{quadrupole,}{tilt=45.0, K= 0.0, method=intmeth, N=1;}
     857
     858\notespace{NOTES:}
     859If skew quadrupoles are defined in the lattice file with a name \tracypara{skewquad},
     860User must specify the name of  skew quadrupole in the tracy input file using
     861the commands:
     862\tracycommand{qt}{skewquad} 
     863
     864\subsection{SEXTUPOLE}
     865
     866\latticedef{Element\_Name:}{sextupole,}{L = $\lbrack \dots \rbrack$, K = $\lbrack \dots \rbrack$,
     867 FF1 = $\lbrack \dots \rbrack$, FF2=$\lbrack \dots \rbrack$,method = $\lbrack \dots \rbrack$,
     868 N=$\lbrack \dots \rbrack$;}
     869
     870
     871 \begin{table}[htpb]
     872 \centering
     873 \caption{Parameters of sextupoles in the lattice file.}
     874 \label{tab:sext-para}
     875\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     876\hline
     877\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     878\hline
     879\textbf{L}        [m] &   & 0.0 & Length\\
     880\hline
     881\textbf{K}         &L $\neq$ 0, [m$^{-3}$]. \newline L = 0, [m$^{-2}$]. & 0.0 &
     882                   If L $\neq$ 0,
     883                   $K  = \frac{1}{2} \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0}$,   
     884                     $B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum,
     885                     $e$ is the electric charge. If L = 0, K is the integrated field
     886             strength $L\frac{1}{2} \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0}$ \\   
     887\hline
     888 \textbf{FF1}      & - & 0 & \textbf{1} or \textbf{0}. \textbf{1}: tringe on the fringe field at the
     889                      left edge. \textbf{0}: tringe off the fringe field at the     
     890                      left edge.\\
     891 \hline
     892 \textbf{FF2}      & - & 0 & \textbf{1} or \textbf{0}. \textbf{1}: tringe on the fringe field at the
     893                      right edge. \textbf{0}: tringe off the fringe field at the     
     894                      right edge.\\
     895 \hline
     896 \textbf{Method}   & - & 4 & \textbf{1},\textbf{2},\textbf{4}. Order of symplectic integration method.       
     897                      \textbf{1}: 1st order; \textbf{2}: 2nd order; \textbf{4} 4th order. \\
     898 \hline
     899 \textbf{N}       & - & 1 &  Pieces of this element to be cut, used in the symplectic   
     900                      integration. \\
     901
     902 \hline
     903 \end{tabular}
     904 \end{table}
     905
     906
     907
     908\textit{Example:} \\
     909\textsf{NqSx=1; coef=1.0/0.16; method4sextu = 4; sextfringe = 0;}
     910\latticedef{SX1:}{sextupole,}{ L=0.16, K =  1.719190*coef, method=method4sextu, N = NqSx,
     911                              FF1=sextfringe, FF2=sextfringe;}
     912
     913The parameters of “sextupole” are optional, the default value for “method” is 4,
     914the default value for the other parameters is 0.
     915
     916
     917\notespace{NOTES:}
     918
     919In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the european notation of
     920the order of magnetic field is used. That is n = 1, 2, 3, ...n; and the definition of
     921K are the same as in \textbf{Tracy}.
     922While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the U.S. notation of the
     923order order of the field is used, that is n = 0, 1, 2, 3, ..n. For sextupole,  n = 2,
     924and its gradient is defined as
     925\begin{equation*}
     926K_2  =  \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0}
     927\end{equation*}
     928
     929\subsection{MULTIPOLE}
     930
     931\latticedef{Element\_Name:}{Multipole,}{L= $\lbrack \dots \rbrack$, T =$\lbrack \dots \rbrack$,
     932               T1=$\lbrack \dots \rbrack$, T2=$\lbrack \dots \rbrack$,
     933tilt=$\lbrack \dots \rbrack$, HOM = (i, $\langle$ $b_i$ $\rangle$, $\langle$ $a_i$ $\rangle$,
     934j, $\langle$ $b_j$ $\rangle$, $\langle$ $a_j$ $\rangle$,
.$n$, $\langle$ $b_n$ $\rangle$, $\langle$
     935$a_n$ $\rangle$), $N$ =$\lbrack \dots \rbrack$$\langle$, method =$\lbrack \dots \rbrack$;}
     936
     937\begin{table}[htpb]
     938\centering
     939\caption{Parameters of the multipoles.}
     940\label{tab:mult-para}
     941\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     942\hline
     943\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     944\hline
     945\textbf{L}         & [m] & 0.0 & Length \\
     946\hline
     947\textbf{T}         & [degree] & 0.0  & Total bending angle \\
     948\hline
     949\textbf{T1}        & [degree] & 0.0 & Entrance angle \\
     950\hline
     951\textbf{T2}        & [degree] & 0.0 & Exit Angle \\
     952\hline
     953\textbf{Tilt}      & [degree] & 0.0 & Rotation angle of the quadrupole; if \tracypara{Tilt}
     954                     is non-zero, then the quadrupole is a skew quadruple.???? \\
     955\hline
     956\textbf{HOM}       & - & (0, 0, 0) & Multipole field components of the element. The format
     957                     is \textit{n}, \textit{$b_{n}$}, \textit{$a_n$}, etc. \newline
     958                     \textit{n} is order of the multipole
     959                     field in U.S. notation (?????), n=1 (dipole field),
     960                     n=2 (quadrupole field), n=3 (sextupole field),
     961                     n=4 (octuple field), n=5 (decuple field).
     962                     \textit{$b_n$} is $n^{\mathrm{th}}$ component of the upright multipole
     963                     field with the unit [$\frac{1}{m^{-n}}$];
     964                     \textit{$a_n$} is $n^{\mathrm{th}}$ component
     965                      of the skew multipole field with the
     966                      unit [$\frac{1}{m^-n}$]. \\
     967\hline
     968\textbf{N}         & - & 1 & Pieces of this element to be cut \\
     969\hline
     970\textbf{Method}    & - & 4 & 1,2,4. Symplectic integration method.
     971                      1 is $1^{\mathrm{st}}$ order, 2 is $2^{\mathrm{nd}}$ order, 4 is
     972                      $4\mathrm{th}$ order. \\
     973\hline
     974\end{tabular}
     975\end{table}
     976
     977The multipole field components $a_n$ and $b_n$ are defined as
     978\begin{eqnarray}   
     979b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0} \\
     980a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0} \\
     981B \rho & = & \frac{p_0}{e}
     982\end{eqnarray}
     983$B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, $e$ is the electric charge.
     984
     985If the magnetic field $\vec{B^{tip}}$ is measured at the location with the radius $r_0$, then
     986$b_n$ and $a_n$ are defined as
     987\begin{eqnarray*}
     988b_n & = & \frac{1}{B \rho} \frac{B_y^{tip}}{r_0^{n-1}}\\
     989a_n & = & \frac{1}{B \rho} \frac{B_x^{tip}}{r_0^{n-1}} \\
     990\vec{B^{tip}} & = & B_y^{tip} \hat{y} +  B_x^{tip} \hat{x} 
     991\end{eqnarray*}
     992
     993 The $n^{th}$ order magnetic field is
     994 \begin{equation}
     995 B_y^n + i * B_x^n = (b_n + i*a_n) * (x + i*y)^n
     996 \end{equation}
     997 The total magnetic field with $1^{st}$ to $n^{th}$ order field components can be calculated using 
     998 \begin{eqnarray}
     999\label{eqn:total:field}
     1000 B_y + i * B_x & = & (b_n + i*a_n) * (x+i*y)*(x + i*y)^{n-1} + O(n-1) \\
     1001             & = & [(b_n*x - a_n*y) + b_{n-1} + i*(a_n*x + b_n*y + a_{n-1})]*(x+i*y)^{n-1} + O(n-2) \\
     1002              & ...&
     1003 \end{eqnarray}
     1004
     1005The eqn.~\ref{eqn:total:field} is used in Tracy3 to calculate the effective fields of the
     1006magnet. This equation clearly shows that, all the field errors gives the same effect the
     1007beam: horizontal focusing and vertical decusing. But since the field strength of the
     1008$n^{th}$ order magnet is proportial to the $n^{th}$ order of $x/y$ and $x/y$ at the
     1009entrance of the magnet is small, so the higher $n$ is, the weak of the $n^{th}$ order
     1010multipole field is.
     1011
     1012\vspace{0.05in}
     1013\textit{Example 1: }
     1014
     1015\latticedef{B:}{multipole,}{L=0.70, T=10.0, T1=5.0, T2=5.0, HOM = (1, -1.0, 0), N=8, Method=2;}
     1016
     1017In this example, the multipole is a dipole with field component  $b_1$ = -1.0, or the
     1018field strength is $B_{y0}$, and the field direction is down. This field gives a horizontal
     1019focusing to the electron.
     1020
     1021\vspace{0.05in}
     1022\textit{Example 2:}
     1023
     1024 \latticedef{QF:}{multipole,}{L=0.70, HOM = (1, 2.50, 0.0, 4, 1.01e7, 0.0), N=8, Method=4;}
     1025
     1026In this example, the multipole is a dipole with $4^{th}$ order upright multipole filed errors (octupole),
     1027and $b_4$ = 1.01e7. 
     1028
     1029To add multipole errors in the defined lattice files, user can also define the multipoles
     1030inside an external file (Section~\ref{sec:mult:field:error}) (???? To be checked, can this
     1031routine mesured with the general one???).
     1032
     1033 \notespace{NOTES:} \\
     1034In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the definition of are the same
     1035as in \textbf{Tracy}. While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the order
     1036of the field compoent start from 0, that is n = 0, 1, 2, 3, ..., and the $n^{th}$ field
     1037strength components of the lattice element $b_n$ and $a_n$ are defined as
     1038\begin{eqnarray*}
     1039b_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_y }{\partial x ^{n}}|_{x=0,y=0} \\
     1040a_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_x }{\partial x ^{n}}|_{x=0,y=0} \\
     1041B \rho & = & \frac{p_0}{e}
     1042\end{eqnarray*}
     1043
     1044\subsection{ wiggler (To be updated.)}
     1045
     1046\latticedef{Element\_Name:}{Wiggler,}{L  = $\langle$ length $\rangle$,BoBrhoV = $\langle$ B/Brho $\rangle$,
     1047BoBrhoH = $\langle$ B/Brho $\rangle$, Lambda  = $\langle$ period $\rangle$,kxV= $\langle$ [m] $\rangle$,kxH     = $\langle$ [m] $\rangle$,phi     = $\langle$ phase $\rangle$,
     1048               harm(n, kxV, BoBrhoV, kxH, BoBrhoH, phi), N = $\langle$ no of integration steps $\rangle$,
     1049               Method  = $\langle$ method $\rangle$;}
     1050
     1051
     1052\begin{table}[htbp]
     1053\centering
     1054\caption{The parameters of wigglers in a lattice file.}
     1055\label{tab:wiggler-para}
     1056\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     1057\hline
     1058\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     1059\textbf{L} & [m] & 0.0 & Length \\ \hline
     1060\textbf{BoBrhoV} & ??? & ??? & the normalized vertical field \\ \hline
     1061\textbf{BoBrhoH} & ??? & ??? &  the normalized horizontal field \\ \hline
     1062\textbf{Labmda} & [m] & ??? & period length  \\ \hline
     1063\textbf{kxV} & [m] & ??? & ??? \\ \hline
     1064\textbf{kxH} & [m] & ??? & ??? \\ \hline
     1065\textbf{phi} & [degree] & ??? & ??? \\ \hline
     1066\textbf{harm} & ??? & ??? & ??? \\ \hline
     1067\textbf{N} & - & - & No of integration steps \\ \hline
     1068\textbf{Method} & - & - &  Symplectic integration method.
     10691 is 1st order, 2 is 2nd order, 4 is 4th order.\\
     1070\hline
     1071\end{tabular}
     1072\end{table}
     1073
     1074\vspace{0.05in}
     1075\textit{ Example 1:}
     1076\latticedef{U143:}{wiggler,}{L=4.80, K=0.5, Lambda=0.15, N=20, Method=0;}
     1077
     1078\vspace{0.05in}   
     1079\textit{Example 2:}
     1080\latticedef{EPU:}{wiggler,}{L=4.80, Lambda=0.15, N=20, Method=0,
     1081                                 harm=(3, kxV\_3, BoBrhoV\_3, kxH\_3, BoBrhoH\_3, phi\_3);}
     1082
     1083\subsection{FIELD MAP (To be updated

..)}
     1084
     1085\latticedef{Element\_Name:}{Fieldmap,}{L = $\langle$ length [m] $\rangle$, N = $\langle$
     1086            no of integration steps $\rangle$, file1 = $\langle$ file name (lower case) $\rangle$};
     1087
     1088\begin{table}[htbp]
     1089\centering
     1090\caption{Parameters of field map in the lattice file.}
     1091\label{tab:fieldmap-para}
     1092\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     1093\hline
     1094\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     1095\hline
     1096\textbf{L} & [m] & 0.0 & Length \\ \hline
     1097\textbf{L} & [m] & 0.0 & Length of the field map \\
     1098\hline
     1099\textbf{N} & - & ??? & the number of integration steps \\
     1100\hline
     1101\textbf{file1} & - & ??? & field map file \\
     1102\hline
     1103\end{tabular}
     1104\end{table}
     1105
     1106\vspace{0.05in}
     1107\textit{Example:}
     1108\latticedef{FM:}{Fieldmap,}{L = 1.0, N = 20, file1 = "U19\_Bxyz.dat";}
     1109
     1110
     1111\subsection{INSERTION DEVICE}
     1112
     1113\latticedef{Element\_Name:}{insertion,}{scaling1 = 1/0, scaling2=1/0,method = interpolation\_method,
     1114         N=Number of slice, file1 = name of the file with 1st order radia map, 
     1115         file2 = name of the file with 2nd order radia map;}
     1116
     1117\begin{table}[htbp]
     1118\centering
     1119\caption{Parameters of the insertion devices.}
     1120\label{tab:insertiondevice-para}
     1121\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     1122\hline
     1123\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     1124\textbf{scaling1} & - & ??? &  scaling factor for the 1st order field map \\
     1125\hline
     1126\textbf{scaling2} & - & ??? &  scaling factor for the 2rd order field map \\
     1127\hline
     1128\textbf{method} & - & ??? & 1, 3. The order of symplectic interpolation method. 1 is linear
     1129  interpolation, 3 is spline interpolation.\\
     1130\hline
     1131\textbf{N} & - & ??? & pieces of this element is cut when it is treated in the code \\
     1132\hline
     1133\textbf{file1} & - & ??? & The 1st order of insertion device field are read from the
     1134files generated by RADIA. If user does not specify the file name with the file path,
     1135then the code will look for the files in the current working directory. The path of
     1136the Radia map file must be in small letters, otherwise the code can’t find the file. \\
     1137\hline
     1138\textbf{file2} & - & ??? &
     1139The 2nd order of insertion device field are read from the files generated by RADIA.
     1140If user does not specify the file name with the file path, then the code will look
     1141for the files in the current working directory. The path of the Radia map file must
     1142be in small letters, otherwise the code can’t find the file. \\
     1143\hline
     1144\end{tabular}
     1145\end{table}
     1146
     1147\vspace{0.05in}
     1148\textit{Example:}
     1149 \latticedef{WIGSLIC:}{insertion,}{N = 10, scaling1=1.0, scaling2=1.0, method=2, file1="/home/sources/physmach/tracy2.7/w150g11pole60\_oppose\_radia\_pour\_tracy.txt", file2= "/home/sources/physmach/brunelle/tracy-2.7/w150g11pole20\_fin.dat";}
     1150     
     1151 All the parameters for ‘insertion’ is optional, the default value for scaling1 and scaling2 are 1,
     1152the default ‘method’ is 3 which means spline interpolation, the default ‘N’ is 1, the default
     1153values for all the other parameters are 0.
     1154
     1155\subsection{RF CAVITY}
     1156
     1157\latticedef{Element\_Name}{cavity,}{Frequency = RF frequency, Voltage = RF voltage, Phase = synchrotron 
     1158                           Phase, harnum = harmonic number of the RF cavity;}
     1159
     1160
     1161\begin{table}[htbp]
     1162\centering
     1163\caption{Parameters of RF cacity.}
     1164\label{tab:RFCavity-para}
     1165\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     1166\hline
     1167\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
     1168\hline
     1169\textbf{frequency} & [Hz] & ??? &  RF frequency  \\
     1170\hline
     1171\textbf{voltage} & [Volt] & ??? &  RF voltage  \\
     1172\hline
     1173\textbf{phase} & [degree] & ??? & synchrotron phase \\
     1174\hline
     1175\textbf{harnum} & - & ??? & harmonic number \\
     1176\hline
     1177\end{tabular}
     1178\end{table}
     1179
     1180
     1181\vspace{0.05in}
     1182\textit{Example:}
     1183\latticedef{CAV:}{Cavity,}{Frequency = 499.95e6, Voltage=1.22e6, phase = 30, harnum=328;}
     1184
     1185The harmonic number of the RF cavity is mandatory, and the other parameters of “cavity” are
     1186optional, the default values are 0.
     1187
     1188\subsection{CORRECTOR}
     1189
     1190\latticedef{Element\_Name:}{corrector,}{horizontal/vertical, method = integrated method;}
     1191
     1192\begin{table}[htbp]
     1193\centering
     1194\caption{Parameters of correctors.}
     1195\label{tab:corrector-para}
     1196\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
     1197\hline
     1198\textbf{Horizontal / vertical} & - & ??? & “horizontal”: horizontal corrector; “vertical”: vertical
     1199 corrector \\
     1200\hline
     1201\textbf{method} & - & ??? & 1, 2, 4. Order of symplectic integration method.
     1202Value ‘1’ means 1st order, ‘2’ means 2nd order, and ‘4’ means 4th order \\
     1203\hline
     1204\end{tabular}
     1205\end{table}
     1206
     1207
     1208\vspace{0.05in}
     1209\textit{Example 1:}
     1210\latticedef{CH:}{corrector,}{horizontal, method=intmeth;}
     1211It defines a horizontal corrector.
     1212
     1213\vspace{0.05in}
     1214\textit{Example 2:}
     1215\latticedef{CV:}{corrector,}{vertical, method=intmeth;}
     1216It defines a vertical corrector.
     1217
     1218The parameters of “corrector” are optional, the default value for ‘method’ is 0.
     1219
     1220\notespace{NOTES:}
     1221For a lattice with correctors, user must specify the name of  corrector in the Tracy
     1222input file with the commands:
     1223           \tracycommand{h\_corr}{HCM}
     1224                         or
     1225           \tracycommand{v\_corr}{VCM}
     1226Here \tracypara{HCM} is the name of the corrector defined in the lattice for horizontal
     1227orbit correction (????); \tracypara{VCM} is the name of the corrector defined in the
     1228lattice for vertical orbit correction.
     1229
     1230
     1231\subsection{MARKER}
     1232
     1233\latticedef{Element\_Name:}{marker;}{}
     1234
     1235\subsection{BEAM POSITION MONITOR (To be updated)}
     1236 BPM is a special marker in the lattice; the “symbol” name must be “BPM” (???). User can
     1237define the BPM as:????
     1238\latticedef{BPM:}{type;}{}
     1239
     1240Normally Its type is defined as “Marker” type, but in order to include the misalignment
     1241error of BPM into the lattice, it must be defined as “Beam Position Monitor” type
     1242which is in fact multipole type, since only the element with multipole type is saved
     1243with displacement error, field error, etc.
     1244
     1245\notespace{NOTES:}
     1246For lattice with BPMs, user must specify the name of  BPM in the Tracy input file
     1247 with the command:
     1248                    \latticedef{bpm}{beaPosMonitor}
     1249Here “beaPosMonitor” is the name of the BPMs defined in the lattice.
     1250
     1251\subsection{GIRDER}
     1252  Girder is a special element, it’s the girder used in the real machine to support the magnetic elements and other elements. It is defined as:
     1253                   Symbol: type;
     1254
     1255  Normally Its type is defined as “Marker” type, but in order to include the misalignment error of girder into the lattice, it must be defined as “multipole” type, since only the element with multipole type is saved with displacement error, field error, etc.
     1256  For convenience, it’s better to define the beginning of the girder and also the end of the girder, and the elements between the beginning and end of the girders are the elements who are put on the girder in the real machine.
     1257
     1258Notice:
     1259For lattice with girders,
     1260 User must specify the name of  girder in the input file “*.prm” with the commands:
     1261                                   gs       Girder\_Start
     1262                                   ge       Girder\_End
     1263
     1264Here ‘Girder\_Start’ is the name of the start of girder defined in the lattice; ‘Girder\_End’ is the name of the end of girder defined in the lattice.
     1265
     1266\subsection{SOLENOID...TO BE UPDATED...}
     1267
     1268
     1269\subsection{ELEMENT BLOCK}
     1270  To construct the element block, use the following format:
     1271           Symbol: elem1, elem2,
., block1,block2;
     1272Here “Symbol” is the name of the element block, and “elem1”, “elem2”, “block1”, “block2” are the element or sub element blocks in this element block.
     1273  If there are N the same element/block subsequently, user can use ‘N*element/block’ to simply the definition. For example:
     1274                        SINJ: SD1a, ssep, 3*SEP,esep,SD1c,eHU600,SD1d;
     1275In this example element block, there are 9 elements/blocks, and 3 elements/blocks “SEP” subsequently.
     1276
     1277\subsection{LINE}
     1278 User can define the cell structure using the command:
     1279
     1280             CELL : $\langle$ block name $\rangle$, SYMMETRY=$\langle$ symmetry $\rangle$;
     1281
     1282$\langle$ block name $\rangle$ is the name of a block; $\langle$ symmetry $\rangle$ is the number of super symmetry or the number of the block in the ring.
     1283
     1284Example:
     1285
     1286         CELL: BL1, Symmetry=12;
     1287
     1288This example defines the cell with block “BL1”, and the number of super symmetry is 12. The output of the Tracy3 with symmetry large than 1 will give the
     1289tunes and chromaticities in one symmetric period.
     1290
     1291\subsection{RING}
     1292To define the ring, use the command:
     1293               RING: elem, block
.
     1294It’s similar to define an element block, but must with the fixed symbol name “RING”. For example:
     1295RING: DEBUT,SUP1,SUP2,SUP3,SUP4,CAV,FIN;
     12965.1.23  End line
     1297 To end the lattice file, user needs to use the following command at the end of the lattice file:
     1298End;
     1299This command is mandatory.
     1300
     1301
     1302\section{Commands}
    4381303  The following commands turn on the boolean flags in the code to set the machine parameters and carry on different calculations. All these commands are optional; user can choose whichever they need. If user wants to use the flag, they can write the flag in the script, if they do not want to use it, they can delete or comment out (add “\#” at the beginning of command line) the flag. The Boolean flags in the user input script have the following features:
    4391304If the flags are not active, then the default values for all the boolean commands are false.
    … …  
    4721337
    4731338The parameters and the default values of “PrintTrackFlag” are shown in Table .
     1339
     1340\begin{table}[h]
     1341\centering
     1342\caption{}
     1343\label{}
     1344\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1345\hline
     1346\hline
     1347\end{tabular*}
     1348\end{table}
     1349
    4741350Table   Parameters of command "PrintTrackFlag".
    4751351Name
    … …  
    5121388-
    5131389
     1390\subsection{PrintTrackElemFlag}
     1391To print the coordinates tracked (NOT around COD) at a certain element to a file, use the command:
     1392PrintTrackFlag           track\_file        x    px   y  py  delta    ctau     nelem1 nelem2
     1393
     1394For example:
     1395PrintTrackFlag           track.out         0.001     0.0    0.0    0.0    0.0    0.0     50 1 2
     1396
     1397The parameters and the default values of “PrintTrackElemFlag” are shown in Table .
     1398
     1399\begin{table}[h]
     1400\centering
     1401\caption{}
     1402\label{}
     1403\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1404\hline
     1405\hline
     1406\end{tabular*}
     1407\end{table}
     1408
     1409Table   Parameters of command "PrintTrackElemFlag".
     1410Name
     1411Description
     1412Default value
     1413Unit
     1414track\_file
     1415File to save the tracked coordinates around each lattice element
     1416track.out
     1417-
     1418x
     1419Start tracking horizontal coordinate
     14200.001
     1421[m]
     1422px
     1423Start tracking horizontal canonical momentum px normalized by reference momentum p0, that is: px = px/p0.  Normally px is approximate as horizontal deviation with unit [rad].
     14240.0
     1425
     1426-
     1427y
     1428Start tracking vertical coordinate
     14290.0
     1430[m]
     1431py
     1432Start tracking vertical canonical momentum py normalized by reference momentum p0, that is: py = py/p0. Normally px is approximate as vertical deviation with unit [rad].
     14330.0
     1434
     1435-
     1436delta
     1437Start tracking relative energy offset
     14380.0
     1439-
     1440ctau
     1441Start tracking longitudinal coordinate
     14420.0
     1443[m]
     1444nelem1
     1445index of start lattice element for tracking
     1446
     1447nelem2
     1448index of end lattice element for tracking
     1449
    5141450\subsection{PrintTwissFlag}
    5151451
    … …  
    5331469 \#
    5341470Where “\#” denotes the command line, the meanings of the above parameters are shown in Table .
     1471
     1472\begin{table}[h]
     1473\centering
     1474\caption{}
     1475\label{}
     1476\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1477\hline
     1478\hline
     1479\end{tabular*}
     1480\end{table}
     1481
    5351482Table   Parameters in the output file of close orbit.
    5361483Name
    … …  
    6651612
    6661613The meanings of parameters and default values of command “AmplitudeTuneShiftFlag” are shown in Table . If user uses the command AmplitudeTuneShiftFlag without parameters, then the code will use all the default values.
     1614
     1615\begin{table}[h]
     1616\centering
     1617\caption{}
     1618\label{}
     1619\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1620\hline
     1621\hline
     1622\end{tabular*}
     1623\end{table}
     1624
    6671625Table     Parameters of the command to calculate tune shift with amplitude
    6681626Parameters
    … …  
    7041662The meaning of parameters and default values of this command are shown in Table .
    7051663If user uses command EnergyTuneShiftFlag without parameters, then the code will use all the default values.
     1664
     1665\begin{table}[h]
     1666\centering
     1667\caption{}
     1668\label{}
     1669\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1670\hline
     1671\hline
     1672\end{tabular*}
     1673\end{table}
     1674
    7061675Table   Parameters of the command to calculate tune shift with energy
    7071676parameter
    … …  
    7221691   
    7231692\subsection{FmapFlag}
    724 Frequency map analysis for on momentum particle
     1693Frequency map analysis for on momentum particle.
     1694Track the coordinates (x, px, y, py, delta, ctau) of the particle,
     1695the coordinates (x, px, y, py) are tracked around the closed orbit;
     1696while (delta, ctau) is tracked around the zero orbit.
     1697
     1698The grid of the particle is x= 1e-6 + xcod ~ xmax + xcod, with the
     1699step size xmax/nturn,
     1700z= 1e-6 + zcod ~ zmax + zcod, with the
     1701step size ymax/nturn; px = 0 + pxcod; pz = 0 + pzcod;
     1702ctau = 0; delta = set value.
    7251703
    7261704To do frequency map analysis for the on momentum particle, use the command:
    727 FmapFlag   fmap\_file    nxpoint   nypoint    nturn  xmax   ymax   delta   diffusion
     1705FmapFlag   fmap\_file    nxpoint   nypoint    nturn  xmax   ymax   delta   diffusion \\
     1706or
     1707FmapFlag   fmap\_file    nxpoint   nypoint    nturn  xmax   ymax   delta   diffusion printloss \\
     1708
    7281709 For example:
    729 FmapFlag   fmap.out   31   21   516   0.025   0.005   0.0   true
     1710FmapFlag   fmap.out   31   21   516   0.025   0.005   0.0   true 
     1711or
     1712FmapFlag   fmap.out   31   21   516   0.025   0.005   0.0   true  true
     1713
     1714
    7301715The meaning of parameters and default values of this command are shown in Table . If user uses command FmapFlag without parameters, then the code will use all the default values.
     1716
     1717\begin{table}[h]
     1718\centering
     1719\caption{}
     1720\label{}
     1721\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1722\hline
     1723\hline
     1724\end{tabular*}
     1725\end{table}
     1726
    7311727Table   Parameters of the command to do frequency map analysis for on momentum particle.
    7321728Parameters
    … …  
    743173921
    7441740nturn
    745 Number of turns for tracking
     1741Number of turns for tracking; if ``diffusion'' is
     1742true, then the tunes will calculated in the first Nturn
     1743and then the second Nturn, and the tune difference
     1744between these two tunes is the tune diffusion.
    7461745516
    7471746xmax
    … …  
    75517540.0
    7561755diffusion
    757 Boolean flag to compute tune diffusion
     1756Boolean flag, true/false; to compute tune diffusion at the first N turns and second N turns.
    7581757true
    7591758
     1759printloss (optional)
     1760Boolean flag, true/flase; print out the last information of the tracked particleto and external file? If true, the output file is ``fmap\_file.loss''.
    7601761\subsection{FmapdpFlag}
    7611762Frequency map analysis for off momentum particle \\
    … …  
    7631764To do frequency map analysis for the off momentum particle, use the command:
    7641765FmapdpFlag   fmapdp\_file    nxpoint    nepoint    nturn    xmax  emax  y  diffusion
     1766or
     1767FmapdpFlag   fmapdp\_file    nxpoint    nepoint    nturn    xmax  emax  y  diffusion printloss
     1768
    7651769The meaning of parameters and default values are shown in Table .  If user only uses the command FmapdpFlag but without defining all the parameters, then the code uses the default values.
     1770
     1771\begin{table}[h]
     1772\centering
     1773\caption{}
     1774\label{}
     1775\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1776\hline
     1777\hline
     1778\end{tabular*}
     1779\end{table}
     1780
    7661781Table  Parameters of the command “FmapdpFlag”.
    7671782parameters
    … …  
    7931808true
    7941809
     1810printloss (optional)
     1811Boolean flag, true/flase; print out the last information of the tracked particleto and external file? If true, the output file is ``fmapdp\_file.loss''.
     1812
     1813
    7951814\subsection{ErrorCouplingFlag}
    7961815Add coupling by the random rotation of the full quadrupoles \\
    … …  
    8271846-0.05   100   1026   0.0001
    8281847The meaning of parameters and default values are shown in Table . If user uses MomentumAccFlag without parameters, then the code will use the default values.
     1848
     1849\begin{table}[h]
     1850\centering
     1851\caption{}
     1852\label{}
     1853\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1854\hline
     1855\hline
     1856\end{tabular*}
     1857\end{table}
     1858
    8291859Table   Parameters of the command to calculate momentum acceptance
    8301860parameter
    … …  
    9211951FitTune4Flag      Q1a  Q1b  Q2a  Q2b  nux  nuz
    9221952The parameters of this command are shown in Table .
     1953
     1954\begin{table}[h]
     1955\centering
     1956\caption{}
     1957\label{}
     1958\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     1959\hline
     1960\hline
     1961\end{tabular*}
     1962\end{table}
     1963
    9231964Table  Parameters of the command “FitTune4Flag”.
    9241965Parameters
    … …  
    9561997FitChromFlag     SX1    SX2    epsilon\_x    epsilon\_z
    9571998The parameters of this command are shown in Table .
     1999
     2000\begin{table}[h]
     2001\centering
     2002\caption{}
     2003\label{}
     2004\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     2005\hline
     2006\hline
     2007\end{tabular*}
     2008\end{table}
     2009
    9582010Table    Parameters of the command “FitChromFlag”.
    9592011Parameters
    … …  
    10632115
    10642116The meanings of the above commands and the default values used to do ID compensation using quadrupoles are shown in Table .
     2117
     2118\begin{table}[h]
     2119\centering
     2120\caption{}
     2121\label{}
     2122\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     2123\hline
     2124\hline
     2125\end{tabular*}
     2126\end{table}
     2127
    10652128Table   Parameters of commands to do ID compensation using quadrupoles.
    10662129Parameters
    … …  
    11072170
    11082171
     2172
     2173
     2174
     2175
     2176
     2177
     2178Frequency map analysis for on momentum particle, command ``FmapFlag''.
     2179\begin{itemize}
     2180\item
     2181Frequency map analysis for off momentum particle, command ``FmapdpFlag''.
     2182\item
     2183Track momentum acceptance at lattice elements, command ``MomentumAccFlag''.
     2184\end{itemize}
     2185
     2186\subsection{Compile}
     2187The commonly used compilers for parallel computation are MPI 2, and Intel MPI which is based on MPI 2. For the cluster of SOLEIL Synchrotron, Intel MPI is installed. To get the parallel Tracy work, three files of the non-parallel version Tracy need to be modified.
     2188The details are shown in the following steps.
     2189\begin{enumerate}
     2190\item
     2191The path of included files of Intel MPI is added in ``Makefile.am'' under
     2192path ``\$HOME/TracyIII/tracy/tracy/src'' (shown in BLUE color):
     2193
     2194          INCLUDES = -I../inc -I\$(NUM\_REC)/inc
     2195          -I/opt/intel/impi/3.2.2.006/include64 
     2196\item
     2197 The execute file, source file, paths of included files and library of Intel
     2198MPI are modified in ``Makefile.am'' under path ``\$HOME/TracyIII/tracy/tools''
     2199 (shown in BLUE color):
     2200
     2201bin\_PROGRAMS = psoltracy
     2202
     2203soltracy\_SOURCES  = soltracy.cc  nrutil.c nrcheck.c   
     2204  nrlinwww.c   nrframe.c ../tracy/src/tracy\_lib.cc   ->
     2205  psoltracy\_SOURCES  = psoltracy.cc  nrutil.c  nrcheck.c   
     2206  nrlinwww.c   nrframe.c   ../tracy/src/tracy\_lib.cc
     2207
     2208  LIBS = -L\$(NUM\_REC)/lib
     2209  -L/opt/intel/impi/3.2.2.006/lib64   -L\$(LIBPATH) 
     2210    -lrecipes\_c\_icc -lstdc++ -lgfortran -lmpichcxx
     2211 
     2212INCLUDES = -I\$(TRACY\_LIB)/tracy/inc -I\$(NUM\_REC)/inc
     2213  -I/opt/intel/impi/3.2.2.006/include64
     2214\item
     2215The compilers used in the parallel computing are defined in the ``make\_for\_psoltracy.sh'' located in path ``\$HOME/TracyIII'' as (shown in BLUE color):
     2216
     2217CC = mpiicc
     2218
     2219                CXX = mpiicpc
     2220
     2221                F77 = mpiifort
     2222
     2223Depending on the compilers used to do parallel computation, user needs to
     2224update the compilers in ``make\_for\_psoltracy.sh'' and the paths of included
     2225files and library which are shown above with blue color.
     2226
     2227 After updating compilers, paths of included files and library for parallel
     2228computation, user can run
     2229
     2230make\_for\_psoltracy.sh
     2231
     2232under the shell script to compile the parallel Tracy. After compilation,
     2233the execute file ``psoltracy'' is automatically generated under the
     2234path ``\$HOME/TracyIII/tracy/tools''.
     2235
     2236
     2237\end{enumerate}
     2238
     2239\subsection{Run}
     2240  As the non-parallel version Tracy, user needs to write the commands in a script which must be with the file extension “.prm”. The syntaxes to define the script “*.prm” are the same for both non-parallel and parallel Tracy.
     2241  To run the parallel Tracy, user need to contact the administrator of their cluster to know how to run parallel programs on the cluster. For the cluster on Synchrotron SOLEIL, the nodes used to do parallel computation are assigned by PBS (Portable Batch System), so a script is need. For example, user define the input script “test.prm” to tell Tracy what jobs are need to be done on the cluster,  define script “lance\_tracy3\_parallel.sh” to assign the numbers of CPUs to do parallel computation and lance job to the SOLEIL cluster. and then type the following command under the bash shell to submit the job and run the parallel Tracy on the cluster:
     2242
     2243    lance\_tracy3\_parallel.sh     test.prm
     2244
     2245\section{ User input script}
     2246  There are two types of keywords in the user input script. The first type is to set the file, the file names, and define parameters for the related calculations; the key words for such definitions are ended with the characters “Flag”. The second type is to define Boolean commands with or without parameters to do different calculations. The rules of the definition of input scripts are:
     2247The blank lines and lines starting with "\#" (comment line) are ignored by the code.
     2248Keywords without “Flag” as the final 4 characters are NOT executed according to the defined sequence in user input script. If the same command keywords are defined many times in the user script, only the last defined keyword is executed.
     2249The commands with the last 4 characters as “Flag” are executed according to the sequence in the code.
     2250The definition of lattice file at the beginning of the user script is mandatory. If the lattice file is with any of the following elements: horizontal correctors, vertical correctors, girders, BPM, skew quadrupoles, user must declare the element name at the beginning of input script.
     2251One keyword command uses one line. User can not define more than one command at the same line.   
     2252Except explanation, all commands with Boolean flag are the generic commands, and can be used on all the lattice of the ring.
     2253\subsection{  File path}
     2254   In the user input script, user can specify the name of the files which are used in the calculation, such as the lattice file, multipole field error file, misalignment error file, vacuum chamber file. When specifying the file name, user can provide the absolute path for the file which is not located at the current path, such as: “/home/physmach/Tracy3/tracy/soleil.lat”; or for convenience, user provides the filename without absolute path, but put the files at a certain directory and then specific this directory using the command:
     2255                       in\_dir            user\_defined\_path
     2256        For example:
     2257                       in\_dir                /home/zhang/codes/TracyIII/lattice/
     2258
     2259This command tells the code all the files specified in the script are located at the directory “/home/zhang/codes/TracyIII/lattice/”. If user declares the files without absolute path and does not set the directory through command in\_dir; or the files specified in the script are not found at the current working path, the code will give an error message and stop running.
     2260
     2261\section{  File names}   
     2262
     2263\subsection{Lattice file name}
     2264In the input script, user must define the lattice name, this is mandatory. The command is:   
     2265lat\_file            lattice\_file\_name
     2266Here “lattice\_file\_name” is the lattice file name without “.lat” extension. For example, the following command sets the lattice file of SOLEIL ring:
     2267lat\_file   solamor2\_reglage\_focalisation\_chcvqt\_thicksextu\_LQPintermediaire\_QFF
     2268  In Tracy 3, after reading the lattice, Twiss parameters are automatically printed to the file “linlat.out”.                                 
     2269  If one of these elements (Horizontal/vertical correctors or beam position monitors, or girders, or skew quadrupoles.) are defined in the lattice file, for example to read the misalignment errors of the lattice element and then do orbit correction, to read multipole field errors (SOLEIL lattice), etc.; user MUST specify the names of these elements using the corresponding commands in the “*.prm” script:
     2270h\_corr             HCM
     2271v\_corr             VCM
     2272gs                     GS
     2273ge                     GE
     2274bpm\_name     BPM
     2275qt                     QT
     2276Here “HCM” is the name of horizontal correctors used for horizontal orbit correction, or the horizontal correctors on which the multipole field errors are added in SOLEIL lattice;  “VCM” is the name of vertical correctors used for vertical orbit correction, or the vertical correctors on which the multipole field errors are added in SOLEIL lattice; “GS” is the name of the start girder;  ‘GE’ is the name of the end girder; “BPM” is the name of beam position monitors defined in the lattice file; “QT” is the name of the skew quadrupoles defined in the lattice.  Generally, user needs to define horizontal, vertical correctors and BPMs when reading the misalignment errors or correcting closed orbit distortion 
     2277
     2278\subsection{Multipole field error file name (SOLEIL lattice)}
     2279  User can read the multipole field errors on SOLEIL lattice from an external file; the file is specified in the user script using the following command:
     2280multipole\_file           multipole\_file\_name
     2281Here “multipole\_file\_name” is the user defined multipole field error file, the format of this file is given in section Error: Reference source not found.
     2282
     2283If the multipole field errors of horizontal, vertical correctors and skew quadrupoles are defined in the “multipole\_file”, user MUST specify the names of these lattice elements in the “*.prm” file as the following example:
     2284h\_corr      CH
     2285v\_corr      CV
     2286qt              QT
     2287Here “CH”, “CV” and “QT” are the names of horizontal, vertical correctors, and skew quadrupoles respectively which are defined in the lattice file.
     2288
     2289\subsection{Files of multipole field errors of correctors and skew quadrupoles (SOLEIL lattice)}
     2290  Horizontal, vertical correctors and skew quadrupoles are integrated with the sextupole quadrupoles on SOLEIL storage ring. To define the multipole field errors on these elements, user need to define the orders and relative strengths of multipole field errors in the multipole  field error file (section Error: Reference source not found) and specify the file name in the user input script “*.prm” (section Multipole field error file name), then specify the file names as the following example:
     2291fic\_hcorr         corh.txt
     2292fic\_vcorr         corv.txt
     2293fic\_skew          corqt.txt
     2294Here “corh.txt” and “corv.txt” are the files with measured current values corh, corv, corqt (with unit [Ampere]) for the horizontal, vertical correctors and skew quadrupoles respectively. Based on the measured current values, user can get the integrated field strength as:
     2295Hcorr\_strength [T.m] = corh *\_convHcorr /brho; (horizontal correctors)
     2296Vcorr\_strength [T.m] = corv *\_convVcorr /brho;  (vertical correctors)
     2297Qt\_strength [T.m] = corqt *\_convQt /brho;  (skew quadrupoles)
     2298here brho is the momentum rigidity, and the conversion constants between current and field are \_convHcorr = 8.14e-4, \_convVcorr = 4.642e-4, \_convQt = 93.83e-4.
     2299  For SOLEIL lattice, the SAME ORDER of multipole field errors on the same elements are added together, so the SAME ORDER of horizontal/vertical, skew quadrupoles, and sextupoles are added together since these elements are integrated at the same magnets.
     2300
     2301\subsection{ File to define field strength of virtual coupling source elements (SOLEIL lattice)}
     2302  On SOLEIL storage ring, the coupling is thought to come from the rotation of quadrupoles and vertical displacements of sextupoles. The strengths of these coupling sources are written in a file, then read by the following command:
     2303virtualskewquad\_file   virtual\_skew\_quad\_currents.txt
     2304
     2305Here “virtual\_skew\_quad\_currents.txt” is the user defined file with strength of vertical coupling source.
     2306  In order to use this command to read the virtual sources of coupling, user needs to define the virtual coupling element as a skew quadrupole in the lattice file:
     2307SQ: quadrupole, tilt=45.0, K= 0.0, method=4, N=1;
     2308and this virtual coupling element MUST be with the name “SQ”. Now there 152 elements defined as the virtual coupling sources in the SOLEIL lattice. The syntaxs to define skew quadrupole are explained in section .
     2309  The measured current value qtcorr[i] of the ith coupling source is converted to the corresponding integrated skew quadrupole field strength corr\_strength as
     2310corr\_strength [m-1] = qtcorr[i]*conv/brho;
     2311here brho is momentum rigidity, and the conversion constant conv is 93.88e-4 [A-1.T].
     2312
     2313\subsection{Cut off value}
     2314  Set the cut off value of all random distribution (Gaussian distribution) to “n” times of the RMS value sigma:
     2315normalcut       n
     2316
     2317\section{Physics: Hamiltionian}
     2318The dynamic motion of a conserved system can be described by a Hamiltonian. For an accelerator system without radiation
     2319damping (energy loss) and RF cavities (energy gain), the motion of a single electron in the magnetic field can be described using the
     2320following Hamitonian in the curvilinear coordinate system (Merz...)
     2321\begin{eqnarray}
     2322H (x,P_x; y, P_y; -t, \delta; s) &=&  L + V  \\
     2323                                 &=& -(1+h_{\mathrm{ref}}x)[\sqrt(P^2 - (P_x - eA_x)^2 - (P_y - eA_y)^2 ) + eA_z(x,P_x; y, P_y,s)]  \\
     2324P^2 & =& P_x^2 + P_y^2 + P_z^2
     2325\end{eqnarray}
     2326$h_{\mathrm{ref}}$ is the curvature of reference orbit inside the dipole.
     2327The $(x,P_x; y, P_y; -t, \delta)$ are the canonical cooridinates of the $H$, and $P_x, P_y, P-z$ are respectively the
     2328horizontal, vertical, and longitudinal mechanical momentums. A more convienent way is to expand the electron motion
     2329around the motion of a reference particle with total momentum $P_0$, so
     2330\begin{eqnarray}
     2331\frac{1}{P_0}H (x,P_x; y, P_y; -t, \delta; s) &=& \\
     2332H (x,p_x; y, p_y; -t, \delta; s) &=& -(1+h_{\mathrm{ref}}x)\sqrt((1+\delta)^2 - (p_x - \frac{e}{P_0}A_x)^2 - (p_y - \frac{e}{P_0}A_y)^2 ) + \frac{e}{P_0}A_z(x,p_x; y, p_y,s) \\
     2333                                &=& -(1+h_{\mathrm{ref}}x)\sqrt((1+\delta)^2 - (p_x - \frac{1}{B \rho}A_x)^2 - (p_y - \frac{1}{B \rho}A_y)^2 ) + \frac{1}{B \rho}A_z(x,p_x; y, p_y,s)
     2334\end{eqnarray}
     2335with
     2336\begin{eqnarray}
     2337p_x &=& \frac{P_x}{P_0}  \\
     2338p_y &=& \frac{P_y}{P_0}  \\
     2339p &=& \frac{P}{P_0} = \frac{\Delta P + P_0}{P_0} = (1+\delta)   \\
     2340\delta &=& \frac{\Delta P}{P_0} \\
     2341B \rho &=& \frac{P_0}{e} (magnetic rigidity)
     2342\end{eqnarray}
     2343
     2344With some operations (J. Bengtsson's linear transverse dynamics for sotrage ring with applications to the low energy antiproton ring (LEAR) at CERN; Tracy 2 manual.),
     2345the Hamitonian can be expressed with the canonical coordinates $(x,p_x; y, p_y; -ct, \delta; s)$ (Tracy-2 Manual, J. Bengtsson)
     2346
     2347\begin{align*}
     2348%\label{Tracy:Exact:H}
     2349H (x,p_x; y, p_y; -ct, \delta; s) \\
     2350&=-(1+h_{\mathrm{ref}}x)(\sqrt{(1+\delta)^2 - (p_x - \frac{A_x}{B \rho})^2 - (p_y - \frac{A_y}{B \rho})^2}  + \frac{A_z}{B \rho}) + \delta  \\
     2351&= -(1+h_{\mathrm{ref}}x)(\sqrt{(1+\delta)^2 - (p_x - \frac{A_x}{B \rho})^2 - (p_y - \frac{A_y}{B \rho})^2 }) + h_{\mathrm{ref}} x \frac{A_z}{B \rho}  \\
     2352& + \frac{A_z}{B \rho} + \delta  \\
     2353&= \underbrace{-(1+h_{\mathrm{ref}}x)\sqrt{(1+\delta)^2 - (p_x - \frac{A_x}{B \rho})^2 - (p_y - \frac{A_y}{B \rho})^2 )}}_\text{kinetic energy} \\
     2354& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}}_\text{Gemometic components due to the curvilinear coordinate inside the dipole}\\
     2355& +\underbrace{\frac{A_z}{B \rho}}_\text{magnet contribution}  \\
     2356& +\underbrace{\delta}_\text{due to the canonical coordinate $-ct$ instead of $-t$}\\ 
     2357A_z & =A_z(x,p_x; y, p_y,s)
     2358\end{align*}
     2359
     2360The equation is the exact Hamitonian used in Tracy. The $A_x$ are due to the longidutinal fringe field, this is an natural results due to the Maxwell Equation; $h_{\mathrm{ref}}$ is not zero only inside the dipoles.
     2361
     2362For the system without fringe field of the magnet, or only consider the field inside the body of the magnet, $A_x = 0$ and $A_y = 0$,
     2363so the Hamiltonian is
     2364\begin{align}
     2365\label{eqn:exact:H:NoFF}
     2366H (x,p_x; y, p_y; -ct, \delta; s) \\
     2367&= \underbrace{-(1+h_{\mathrm{ref}}x)\sqrt{(1+\delta)^2 - p_x^2 - p_y^2)}}_\text{kinetic energy} \\
     2368& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}}_\text{Gemometic components due to the curvilinear coordinate inside the dipole}\\
     2369& +\underbrace{\frac{A_z}{B \rho}}_\text{magnet contribution}  \\
     2370& +\underbrace{\delta}_\text{due to the canonical coordinate $-ct$ instead of $-t$}\\ 
     2371\end{align}
     2372
     2373From eqn.~\ref{eqn:exact:H:NoFF}, it is easy to get the map of the particle inside different lattice elements.
     2374
     2375
     2376\subsection{Map of drift}
     2377\label{H:drift}
     2378
     2379In the drift, $A_z = 0$, and $h_{\mathrm{ref}}$ = 0, from eqn.~\ref{eqn:exact:H:NoFF}, we can get the Hamiltonian
     2380inside a drift is
     2381\begin{align}
     2382\label{eqn:H:exact:drift}
     2383H (x,p_x; y, p_y; -ct, \delta; s) = -\sqrt{(1+\delta)^2 - p_x^2 - p_y^2)} + \delta
     2384\end{align}
     2385
     2386In large ring, in order to increase the tracking speed, we can expand the sqare root in
     2387eqn.~\ref{eqn:H:exact:drift} to get the approximate Hamitonian.
     2388That is,
     2389\begin{align}
     2390\label{eqn:H:approxi:drift}
     2391H (x,p_x; y, p_y; -ct, \delta; s) &= -(1+\delta) \left[ 1 - \frac{p_x^2 + p_y^2}{2 (1+\delta)^2} \right] + \delta\\
     2392                                  &= \frac{p_x^2 + p_y^2}{2(1+\delta)}
     2393\end{align}
     2394
     2395
     2396From eqn.~\ref{eqn:H:exact:drift}, it is easy to get the map inside the drift for the
     2397\textbf{small ring}:
     2398\begin{align}
     2399x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = \frac{p_{x0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2400y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}= \frac{p_{y0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2401(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} =-\frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}}+1 \\
     2402or \\
     2403(ct)^{'} = \frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}}-1 \\
     2404p_x  = p_{x0} \\
     2405p_y  = p_{y0} \\
     2406\delta = \delta_0
     2407\end{align}
     2408
     2409From eqn.~\ref{eqn:H:approxi:drift}, it is easy to get the map inside the drift for the
     2410\textbf{big ring}:
     2411\begin{align}
     2412x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = \frac{p_{x0}}{1+\delta_0} \\
     2413y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}= \frac{p_{y0}}{1+\delta_0} \\
     2414(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} =-\frac{p_{x0^2}+p_{y0}^2}{2(1+\delta_0)} \\
     2415or \\
     2416(ct)^{'} = \frac{p_{x0^2}+p_{y0}^2}{2(1+\delta_0)} \\
     2417p_x  = p_{x0} \\
     2418p_y  = p_{y0} \\
     2419\delta = \delta_0
     2420\end{align}
     2421
     2422\subsection{Map of mutipoles}
     2423 From eqn.~\ref{eqn:exact:H:NoFF}, we can get the Hamiltonian
     2424inside a multipole without fringe field is
     2425\begin{align}
     2426\label{eqn:H:exact}
     2427H (x,p_x; y, p_y; -ct, \delta; s) \\
     2428=& \underbrace{-\sqrt{(1+\delta)^2 - p_x^2 - p_y^2}+\delta}_\text{H drift} \\
     2429& \underbrace{-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}}_\text{H kick} \\
     2430& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho}}_\text{H kick} 
     2431\end{align}
     2432
     2433In eqn.~\ref{eqn:H:exact}, the Hamiltonian is decomposed into two part, one is the Hamiltonian
     2434of the drift which is due to the kinetic energy of the system (section~\ref{H:drift}), another part is the kick
     2435due to the multipoles which will give the kick to the particle.
     2436Now we only need to focus on the Hamiltonian of the multipoles which induces the kick map:
     2437\begin{align}
     2438\label{eqn:H:exact:multipole}
     2439H (x,p_x; y, p_y; -ct, \delta; s) \\
     2440&=-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} \\
     2441& +\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho}
     2442\end{align}
     2443
     2444Similarly, by expand the sqare root in eqn.~\ref{eqn:H:exact}, we can get the approximate Hamiltonian
     2445of the multipole as
     2446\begin{align}
     2447\label{eqn:H:approxi:multipole}
     2448H (x,p_x; y, p_y; -ct, \delta; s) \\
     2449&=-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} \\
     2450& +\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho} \\
     2451&=-h_{\mathrm{ref}} x \delta + \frac{1}{2}h_{\mathrm{ref}} h_{B} x^2 - \frac{A_z}{B \rho}+(h_B - h_{\mathrm{ref}})x
     2452\end{align}
     2453where $h_{\mathrm{ref}}$ is the curvature due to the curlininear coordinates inside the dipole,
     2454$h_{\mathrm{ref}} = 1/\rho_{ref}$;
     2455$h_{\mathrm{bend}}$ is due to the bending curvature of the dipole which is determined by the dipole
     2456field, $h_{\mathrm{bend}} = 1/ \rho_{bend}$. $h_{\mathrm{ref}} \neq 0$ only inside dipoles.
     2457
     2458In the dipole, $A_z \neq 0$, and $h_{\mathrm{ref}} \neq $ 0, so
     2459from eqn.~\ref{eqn:H:exact:multipole}, we can get the kick map due to the dipole
     2460in the \textbf{small ring} which use the exact Hamiltonian:
     2461\begin{align}
     2462\label{eqn:kickmap:exact}
     2463x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = h_{\mathrm{ref}} x_0 \frac{p_{x0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2464y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  h_{\mathrm{ref}} x_0 \frac{p_{y0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2465p_x^{'}  = -\frac{\partial H}{\partial y_0} = h_{\mathrm{ref}} \sqrt{(1+\delta_0)^2 - p_{x0}^2 - p_{y0}^2} - h_{\mathrm{bend}} - h_{\mathrm{ref}}h_{\mathrm{bend}}x - \frac{B_y}{B \rho}\\
     2466p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
     2467(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} =-h_{\mathrm{ref}} x_0 \frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2468or \\
     2469(ct)^{'} = h_{\mathrm{ref}} x_0 \frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
     2470\delta = \delta_0 \\
     2471B \rho = \frac{p_0}{e}
     2472\end{align}
     2473where
     2474\begin{align}
     2475\frac{\partial A_z}{\partial x} = - B_y \\
     2476\frac{\partial A_z}{\partial y} = B_x
     2477\end{align}
     2478since
     2479\begin{align}
     2480A_x = 0 \\
     2481A_y =0
     2482\end{align}
     2483inside the body of the multipoles, and
     2484\begin{align*}
     2485\vec{B} = \Delta \times \vec{A}  \\
     2486\hat{x} & \hat{y} & \hat{z} \\
     2487\frac{\partial}{x} &  \frac{\partial}{y} &  \frac{\partial}{z} \\
     2488A_x  & A_y & A_z \\
     2489\end{align*}
     2490
     2491
     2492In the dipole, $A_z \neq 0$, and $h_{\mathrm{ref}} \neq $ 0, so
     2493from eqn.~\ref{eqn:H:approxi:multipole}, we can get the kick map due to the dipole
     2494in the \textbf{big ring} which use the exact Hamiltonian:
     2495\begin{align}
     2496\label{eqn:kickmap:approxi}
     2497x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = h_{\mathrm{ref}} x_0 \frac{p_{x0}}{1+\delta_0} \\
     2498y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  h_{\mathrm{ref}} x_0 \frac{p_{y0}}{1+\delta_0} \\
     2499p_x^{'}  = -\frac{\partial H}{\partial y_0} = h_{\mathrm{ref}} \delta_0 - (h_{\mathrm{bend}} - h_{\mathrm{ref}}) - h_{\mathrm{ref}}h_{\mathrm{bend}}x - \frac{B_y}{B \rho}\\
     2500p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
     2501(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} =\frac{-h_{\mathrm{ref}} x_0}{1+\delta_0} \frac{-(p_{x0}^2+p_{y0}^2)}{2(1+\delta_0)} \\
     2502or \\
     2503(ct)^{'} =-\frac{h_{\mathrm{ref}} x_0}{1+\delta_0} \frac{(p_{x0}^2+p_{y0}^2)}{2(1+\delta_0)} \\
     2504\delta^{'} = 0
     2505\end{align}
     2506
     2507For other multipoles (quadrupoles, sextupole, decapole, octupole, etc), the curvilinear coordinate is
     2508the cartesian coordinates, that is $h_{ref}$ = 0, so from eqn.~\ref{eqn:kickmap:exact}, the kick map for
     2509these multipoles in the small ring is: 
     2510\begin{align}
     2511\label{eqn:kickmap:exact:multipole}
     2512x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = 0 \\
     2513y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  0 \\
     2514p_x^{'}  = -\frac{\partial H}{\partial y_0} = - (h_{\mathrm{bend}} + \frac{B_y}{B \rho})\\
     2515p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
     2516(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} = 0\\
     2517or \\
     2518(ct)^{'} = 0 \\
     2519\delta^{'} = 0
     2520\end{align}
     2521
     2522With $h_{ref} = 0$, from eqn:~\ref{eqn:kickmap:approxi}, the kick map for these
     2523multipoles (quadrupoles, sextupole, decapole, octupole, etc) in the big ring is:
     2524\begin{align}
     2525\label{eqn:kickmap:approxi:multipole}
     2526x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = 0 \\
     2527y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  0 \\
     2528p_x^{'}  = -\frac{\partial H}{\partial y_0} = - (h_{\mathrm{bend}} + \frac{B_y}{B \rho})\\
     2529p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
     2530(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} = 0\\
     2531or \\
     2532(ct)^{'} = 0 \\
     2533\delta^{'} = 0
     2534\end{align}
     2535
     2536From the eqn~\ref{eqn:kickmap:exact} to eqn.~\ref{eqn:kickmap:approxi:multipole}, it's clear
     2537that the kick map from the main body of dipoles are different in the small ring and big ring;
     2538while the kick map from the main body of other type of multipoles are the same in small
     2539rings and big rings.
     2540
     2541
     2542
     2543
     2544
     2545
     2546
     2547
     2548\section{Magnetic field}
     2549
     2550A. Dragt ....(Lie methods for acceleator........)
     2551
     2552\section{FF of dipole}
     2553\subsection{kick map}
     2554E. Forest ...........
     2555
     2556\section{FF of quadrupole}
     2557\subsection{kick map}
     2558
     2559
    11092560\section{ Lattice file}
     2561In the lattice, RF cavity must be defined!!! Otherwise Tracy will give the error message:
     2562\textcolor{red}{Elem\_GetPos: there are no kids in family 0 ()}. This obigatory is for the
     2563correct calculation of positive/negtive momentum compaction factor.
     2564
     2565
     2566
    11102567The followings are the rules to define a lattice file used in Tracy 3. The curvelinear coordinates are
    11112568used. \textbf{The ideal particle or design particle sees the perfect magnetic field in all magnets, and its}
    … …  
    11822639                                                           CODeps= 1.0d-15;
    11832640These definitions are mandatory.
    1184 
    1185 \subsection{drift}
    1186 To define a drift element, the format is:
    1187                                            Symbol: drift ,  L = length ;
    1188 â€œSymbol” is the user defined element name, “drift” is a keyword to denote this element is a drift, and using keyword “L”, user can define the drift length of the element with unit [m].
    1189   For example:
    1190                       SD1a : drift, L= 0.900000;
    1191   The definition of the length of the drift element is mandatory.
    1192 
    1193 \subsection{bending}
    1194 The bending magnet in Tracy is a symplectic element.
    1195 The independent variable $s$ inside the dipole harmitonian is the arc length,
    1196 so the length of the dipole is defined the curved path length of the design
    1197 particle inside the dipole.
    1198 
    1199 To define a bending magnet, the format is:
    1200 
    1201 Element\_name: \textbf{bending}, \textbf{L} = length, \textbf{T} = total bending angle,
    1202 \textbf{T1} = entrance angle, \textbf{T2}=exit angle,
    1203 \textbf{gap} = full gap between two poles, \textbf{edge\_effect1} = 1/0, 
    1204 \textbf{edge\_effect2} = 1/0, \textbf{K} = quadrupole component field strength,
    1205 \textbf{method} = integration\_method, \textbf{N} = Number of slice;
    1206  
    1207 Here ``Element\_name'' is the user defined element name; ``bending'' is a keyword to denote
    1208 this element is a dipole; all the other parameters are explained in Table~\ref{tab:dipole-para}.
    1209 
    1210 \begin{table}[h]
    1211 \centering
    1212 \caption{Parameters of dipole in the lattice file.}
    1213 \label{tab:dipole-para}
    1214 \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
    1215 \hline
    1216 \textbf{Symbol}    &  \textbf{Units}               & \textbf{Parameter}    \\
    1217 \hline
    1218 \textbf{L}     & length which is a curved path length of
    1219                 the design particle inside the dipole.
    1220                 L = $\rho * \theta$, where $\rho$ is the
    1221                 bending radius of the dipole, and $\theta$
    1222                is the bending angle of the dipole.            &  m \\
    1223 \hline
    1224 \textbf{T}     & total bending angle                      & degree \\
    1225 \hline
    1226 \textbf{T1}    & Entrance angle                           &  degree \\
    1227 \hline
    1228 \textbf{T2}    & Exit Angle                               &  degree \\
    1229 \hline
    1230 \textbf{K}     & (For combined dipoles) quadrupole field
    1231           strength if magnet length L not equal to 0 or
    1232           integrated field strength if L=0.        &   m1 (L!=0) /unitless (L=0) \\
    1233 \hline                                             
    1234 \textbf{Method}  &   1,2,4.
    1235             Symplectic integration method. The
    1236             value ``1'' means $1^{\mathrm{st}}$ order,
    1237            ``2'' means $2^{\mathrm{nd}}$ order,
    1238            and ``4'' means $4^{\mathrm{th}}$ order.   & - \\
    1239 \hline
    1240 \textbf{Gap}     &   Distance between two poles of the dipole,
    1241             the gap size determine the fringe field.
    1242             If the gap size is 0, then the dipole has
    1243             no fringe field (\textcolor{red}{??????}).   &       m \\
    1244 \hline
    1245 \textbf{edge\_effect1} & 1/0.
    1246                 ``1'' to turn on the edge focusing effect
    1247                   and the fringe field at the entrance of
    1248                   the dipole. ``0'' to turn off the two effects.  &   - \\
    1249 \hline
    1250 \textbf{edge\_effect2} & 1/0.
    1251                 ``1'' to turn on the edge focusing effect
    1252                   and the fringe field at the exit of
    1253                   the dipole.
    1254                   ``0'' to turn off the two effects. &      - \\
    1255 \hline
    1256 \textbf{N}      &   number of slices when the dipole is treated in the code & - \\
    1257 \hline
    1258 \end{tabular*}
    1259 \end{table}
    1260  
    1261 For example:
    1262 
    1263 {** bending **}
    1264 
    1265 beta\_gap=37e-3;
    1266 
    1267 tracy\_gap=beta\_gap*2*0.724;
    1268 
    1269 BEND1 : \textbf{bending}, \textbf{L} = 1.05243, \textbf{T} = 11.25, \textbf{T1} = 5.5906,
    1270 \textbf{T2} = 5.67658, \textbf{K} = 0.00204,gap=tracy\_gap,
    1271 \textbf{edge\_effect1} = 1, \textbf{edge\_effect2} = 1, \textbf{N} = 4,
    1272 \textbf{method} = intmeth;
    1273 
    1274   The parameters of ``bending'' are optional, the default values for the missing parameters are 0,
    1275  and the default value for ``method'' is also 0.
    1276 
    1277 
    1278 Attension:
    1279 
    1280 In the lattice of ELEGANT, BETA, the dipole angles are defined with the unit [rad]. But in TRACY, the unit is [degree].
    1281 
    1282 \subsection{quadrupole}
    1283 To define a quadrupole element, the format is:
    1284 Symbol: quadrupole, L = length, tilt = tilt angle, K = field strength, FF1 = 1[0],       
    1285                                      FF2=1[0], FFscaling = scaling factor of the field, method =
    1286                                      integration\_method, N=Number of slice;
    1287 
    1288 Here “Symbol” is the user defined element name; “quadrupole” is a keyword to denote this element is a quadrupole or parts of a quadrupole; all the other parameters are explained in Table .
    1289 Table   Parameters of quadrupoles in the lattice file.
    1290 Symbol
    1291 Parameter
    1292 Units
    1293 L
    1294 Length of the quadrupole
    1295 [m]
    1296 Tilt
    1297 tilt angle of the quadrupole;
    1298 if ‘tilt’ is non-zero, then the quadrupole is a skew quadruple.
    1299 [degree]
    1300 K
    1301 If L  0,
    1302 then Gradient, .
    1303 If L= 0,
    1304 integrated field strength of this quadrupole component.
    1305 [m-2] (If L  0)
    1306 
    1307 
    1308 
    1309 [m-1] (If L =  0)
    1310 FF1
    1311 1 or 0.
    1312 1 means taking into account the fringe field at the left edge.
    1313 0  means not taking into account the fringe field at the left edge(user should notice, in order to take into account the fringe field of the quadrupoles, user also need  to use “QuadFringeOnFlag” in the user input script)
    1314 
    1315 -
    1316 FF2
    1317 1 or 0.
    1318 1 means taking into account the fringe field at the right edge.
    1319  0  means not taking into account the fringe field at the right edge(user should notice, in order to take into account the quadrupole fringe field, user need also to set “QuadFringeOnFlag” in the user input script)
    1320 
    1321 -
    1322 Method
    1323 Order of symplectic integration method.
    1324 Value “1” means 1st order, “2” means 2nd order, and “4” means 4th order.
    1325 1,2,4
    1326 N
    1327 Pieces of the quadrupole to be cut when it is treated in the code.
    1328 -
    1329 
    1330 Example:
    1331 {** Quadrupole **}
    1332 Nq=8/2; {Number of slices}
    1333 dgsurg=1.00;
    1334 dgsurgL=1.00;
    1335 quadfringe=1.0;
    1336 LQC=0.3602;
    1337 
    1338 QP1a: quadrupole, L=LQC/2, K= -1.073038*dgsurg, FF1=quadfringe, FF2=0,
    1339               FFscaling =1, method=intmeth, N=Nq;
    1340 The parameters of “quadrupole” are optional, the default value for “method” is 4, the default value for “FFscaling” is 1, the default value for the other parameters are 0.
    1341 5.1.9 Skew quadrupole
    1342 The skew quadrupole is a special type of quadrupole, with a non-zero tilt angle. For example:
    1343 QT: quadrupole, tilt=45.0, K= 0.0, method=intmeth, N=1;
    1344 Notice:
    1345 For lattice with skew quadrupoles,
    1346 User must specify the name of  skew quadrupole in the input file “*.prm” with the commands:
    1347 qt       skewquad
    1348 Here “skewquad” is the name of the skew quadrupoles defined in the lattice.
    1349 
    1350 \subsection{sextupole}
    1351 To define one sextupole, the format is:
    1352 
    1353 Symbol: sextupole, L = length, K = field strength, FF1 = 1/0, FF2=1/0,
    1354            method = integration\_method, N=Number of slice;
    1355 Here “symbol” is the user defined element name; “sextupole” is a keyword to denote this element is a sextupole; all other parameters are explained in Table .
    1356 Table   Parameters of sextupoles in the lattice file.
    1357 Symbol
    1358 Parameter
    1359 Units
    1360 L
    1361 Length of the element
    1362 [m]
    1363 K
    1364 If L  0,
    1365 Gradient, .
    1366 
    1367 If L= 0,
    1368 integrated field strength with unit [m-2] of this quadrupole component.
    1369 [m-3] (If L  0)
    1370 
    1371 
    1372 
    1373 [m-2] (If L =  0)
    1374 FF1
    1375 1 or 0.
    1376 1 means taking into account the fringe field at the left edge.
    1377 0  means not taking into account the fringe field at the left edge
    1378 
    1379 FF2
    1380 1 or 0.
    1381 1 means taking into account the fringe field at the right edge.
    1382  0  means not taking into account the fringe field at the right edge
    1383 
    1384 Method
    1385 Order of symplectic integration method.
    1386  Value “1” means 1st order, “2” means 2nd order, and “4” means 4th order.
    1387 1,2,4
    1388 N
    1389 pieces of this element to be cut
    1390 
    1391 
    1392 For example:
    1393 NqSx=1; {Number of slices}
    1394 coef=1.0/0.16;
    1395 method4sextu = 4;
    1396 sextfringe = 0;
    1397 
    1398 SX1 : sextupole, L=0.16, K =  1.719190*coef, method=method4sextu, N = NqSx,
    1399                               FF1=sextfringe, FF2=sextfringe;
    1400   The parameters of “sextupole” are optional, the default value for “method” is 4, the default value for the other parameters is 0.
    1401 
    1402 \subsection{ multipole}
    1403   To define a multipole, the format is:
    1404 Symbol: Multipole, L= $\langle$ length $\rangle$, T =$\langle$ bending angle $\rangle$,
    1405 T1=$\langle$ entrance angle $\rangle$, T2=$\langle$ exit angle $\rangle$,
    1406 tilt=$\langle$ roll angle $\rangle$, HOM = (i, $\langle$ $b_i$ $\rangle$, $\langle$ $a_i$ $\rangle$,
    1407 j, $\langle$ $b_j$ $\rangle$, $\langle$ $a_j$ $\rangle$,
.$n$, $\langle$ $b_n$ $\rangle$, $\langle$
    1408 $a_n$ $\rangle$), $N$ =$\langle$ number of slices $\rangle$, method = $\langle$ method $\rangle$;
    1409 Here ``symbol'' is the user defined element name; ``multipole'' is a keyword to denote
    1410 this element is a multipole; all other parameters are explained in Table~\ref{tab:mult-para}.
    1411 
    1412 \begin{table}[h]
    1413 \centering
    1414 \caption{Parameters of the multipoles.}
    1415 \label{tab:mult-para}
    1416 \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.1\linewidth} |p{0.45\linewidth} | p{0.15\linewidth} | c |}
    1417 \hline
    1418 \textbf{Symbol}    & \textbf{Units}               & \textbf{Parameter}  & \textbf{Default}   \\
    1419 \hline
    1420 \textbf{L}         & Length of the multipole & m   & 0.0 \\
    1421 \hline
    1422 \textbf{T}         & Total bending angle     & degree & 0.0  \\
    1423 \hline
    1424 \textbf{T1}        & Entrance angle          & degree & 0.0 \\
    1425 \hline
    1426 \textbf{T2}        & Exit Angle              & degree & 0.0  \\
    1427 \hline
    1428 \textbf{Tilt}      & Tilt angle of the
    1429                      quadrupole; if ``tilt''
    1430                      is non-zero, then the
    1431                      quadrupole is a skew
    1432                      quadruple.              & degree  & 0.0 \\
    1433 \hline
    1434 \textbf{HOM}       & Multipole field components
    1435                      of the element. The format
    1436                      is \textit{n}, \textit{$b_{n}$},
    1437                      \textit{$a_n$}, etc.
    1438 
    1439                      \textit{n} is order of
    1440                       the multipole
    1441                      field in US. notation, n=1 means dipole errors,
    1442                      n=2 is quadrupole errors, n=3 is sextupole field errors,
    1443                      n=4 is octuple field errors, n=5 is decuple field errors, etc. \\
    1444                      \textit{$b_n$} is $n^{\mathrm{th}}$
    1445                      component of the upright multipole
    1446                      field with the unit [$\frac{1}{m^{n}}$];
    1447                      \textit{$a_n$} is $n^{\mathrm{th}}$ component
    1448                       of the skew multipole field with the
    1449                       unit [$\frac{1}{m^n}$]. &  - & (0, 0.0, 0.0)  \\
    1450 \hline
    1451 \textbf{N}         & Pieces of this element to be cut  & - & 0 \\
    1452 \hline
    1453 \textbf{Method}    & 1,2,4.
    1454                      Symplectic integration method.
    1455                       1 is $1^{\mathrm{st}}$ order, 2 is
    1456                       $2^{\mathrm{nd}}$ order, 4 is
    1457                       $4\mathrm{th}$ order.             & - & 0\\   
    1458 
    1459 \hline
    1460 \end{tabular*}
    1461 \end{table}
    1462 
    1463 The multipole field components $a_n$ and $b_n$ are defined as
    1464 \begin{eqnarray}   
    1465 b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0} \\
    1466 a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0} \\
    1467 B \rho & = & \frac{p_0}{e}
    1468 \end{eqnarray}
    1469 $B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, $e$ is the electric charge.
    1470 
    1471 If the magnetic field $\vec{B^{tip}}$ is measured at the location with the radius $r_0$, then
    1472 $b_n$ and $a_n$ are defined as
    1473 \begin{eqnarray*}
    1474 b_n & = & \frac{1}{B \rho} \frac{B_y^{tip}}{r_0^{n-1}}\\
    1475 a_n & = & \frac{1}{B \rho} \frac{B_x^{tip}}{r_0^{n-1}} \\
    1476 \vec{B^{tip}} & = & B_y^{tip} \hat{y} +  B_x^{tip} \hat{x} 
    1477 \end{eqnarray*}
    1478 
    1479  The $n^{th}$ order magnetic field is
    1480  \begin{equation}
    1481  B_y^n + i * B_x^n = (b_n + i*a_n) * (x + i*y)^n
    1482  \end{equation}
    1483  The total magnetic field with $1^{st}$ to $n^{th}$ order field components can be calculated using 
    1484  \begin{eqnarray}
    1485 \label{eqn:total:field}
    1486  B_y + i * B_x & = & (b_n + i*a_n) * (x+i*y)*(x + i*y)^{n-1} + O(n-1) \\
    1487              & = & [(b_n*x - a_n) + b_{n-1} + i*(a_n*x + b_n*y + a_{n-1})]*(x+i*y)^{n-1} + O(n-2) \\
    1488               & ...&
    1489  \end{eqnarray}
    1490 The eqn.~\ref{eqn:total:field} is used in Tracy3 to calculate the effective fields of the
    1491 magnet. This equation clearly shows that, all the field errors gives the same effect the
    1492 beam: horizontal focusing and vertical decusing.
    1493  But since the field strength of the
    1494 $n^{th}$ order magnet is proportial to the $n^{th}$ order of $x/y$ and $x/y$ at the
    1495 entrance of the magnet is small, so the higher $n$ is, the weak of the $n^{th}$ order multipole
    1496 field is.
    1497 
    1498 
    1499 Example 1:
    1500 
    1501 B: multipole, L=0.70, T=10.0, T1=5.0, T2=5.0, HOM = (1, -1.0, 0), N=8, Method=2;
    1502 
    1503 In this example, the multipole is a dipole with field component  $b_1$ = -1.0, or the
    1504 field strength is $B_{y0}$, and the field direction is down. This field gives a horizontal
    1505 focusing to the electron.
    1506 
    1507 Example 2:
    1508 
    1509                QF: multipole, L=0.70, HOM = (1, 2.50, 0.0, 4, 1.01e7, 0.0), N=8, Method=4;
    1510 
    1511 In this example, the multipole is a dipole with $4^{th}$ order upright multipole filed errors (octupole),
    1512 and $b_4$ = 1.01e7. 
    1513 
    1514 To add multipole errors in the defined lattice files, user can also define the multipoles
    1515 inside a separate file (Section~\ref{sec:mult:field:error}) (???? To be checked, can this routine mesured with
    1516 the general one???).
    1517 \subsection{ wiggler (To be updated.)}
    1518 To define a wiggler, the format is:  (To be updated

..)
    1519 symbol: Wiggler, L  = $\langle$ length $\rangle$,BoBrhoV = $\langle$ B/Brho $\rangle$,BoBrhoH = $\langle$ B/Brho $\rangle$,
    1520                Lambda  = $\langle$ period $\rangle$,kxV     = $\langle$ [m] $\rangle$,kxH     = $\langle$ [m] $\rangle$,phi     = $\langle$ phase $\rangle$,
    1521                harm(n, kxV, BoBrhoV, kxH, BoBrhoH, phi), N = $\langle$ no of integration steps $\rangle$,
    1522                Method  = $\langle$ method $\rangle$;
    1523 
    1524 Here “symbol” is the user defined element name; “wiggler” is a keyword to denote this element is a wiggler; all other parameters are explained in Table .
    1525 Table   The parameters of wigglers in a lattice file.
    1526 Symbol
    1527 Parameter
    1528 Units
    1529 L
    1530 Length of the wiggler
    1531 [m]
    1532 BoBrhoV
    1533 the normalized vertical field
    1534 [m-1]
    1535 BoBrhoH
    1536 the normalized horizontal field
    1537 [m-1]
    1538 Labmda
    1539 period length
    1540 [m]
    1541 kxV
    1542 
    1543 [m]
    1544 kxH
    1545 
    1546 [m]
    1547 phi
    1548 
    1549 [degree]
    1550 harm
    1551 
    1552 
    1553 N
    1554 No of integration steps
    1555 
    1556 Method
    1557 Symplectic integration method.
    1558 1 is 1st order, 2 is 2nd order, 4 is 4th order.
    1559 
    1560 
    1561     Example 1:
    1562 U143: wiggler, L=4.80, K=0.5, Lambda=0.15, N=20, Method=0;
    1563    
    1564 Example 2:
    1565 EPU:  wiggler, L=4.80, Lambda=0.15, N=20, Method=0,
    1566                                  harm=(3, kxV\_3, BoBrhoV\_3, kxH\_3, BoBrhoH\_3, phi\_3);
    1567 \subsection{field map (To be updated

..)}
    1568 To read field map from a file, use the format: 
    1569 $\langle$ symbol $\rangle$ : Fieldmap, L     = $\langle$ length [m] $\rangle$, N     = $\langle$ no of integration steps $\rangle$,
    1570                                       file1 = $\langle$ file name (lower case) $\rangle$;
    1571   Here “symbol” is the user defined element name; “Fieldmap” is a keyword to denote this element is a Fieldmap; all other parameters are explained in Table .
    1572 Table    Parameters of field map in the lattice file.
    1573 Symbol
    1574 Parameter
    1575 Units
    1576 L
    1577 Length of the field map
    1578 [m]
    1579 file1
    1580 field map file
    1581 
    1582 N
    1583 No of integration steps
    1584 
    1585 
    1586 
    1587 â€˜L’ is the length of the element, ‘N’ is the number of integration steps in the code, ‘file1’ is the field map file.
    1588 
    1589  Example:
    1590 FM: Fieldmap, L = 1.0, N = 20, file1 = "U19\_Bxyz.dat";
    1591 
    1592 \subsection{Insertion device}
    1593 To define the insertion device, the format is:
    1594    Symbol : insertion ,  scaling1 = 1/0, scaling2=1/0,method = interpolation\_method,
    1595          N=Number of slice, file1 = name of the file with 1st order radia map, 
    1596          file2 = name of the file with 2nd order radia map;
    1597   Here “symbol” is the user defined element name; “insertion” is a keyword to denote this element is an insertion device; all other parameters are explained in Table .
    1598 Table    parameters of the insertion devices in the lattice file.
    1599 Symbol
    1600 Parameter
    1601 Units
    1602 scaling1
    1603 scaling factor for the 1st order field map
    1604 
    1605 scaling2
    1606 scaling factor for the 2nd order map
    1607 
    1608 method
    1609 the order of symplectic interpolation method in the code, the value of 1 is linear interpolation, 3 is spline interpolation.
    1610 
    1611 N
    1612 pieces of this element is cut when it is treated in the code
    1613 
    1614 file1
    1615 The 1st order of insertion device field are read from the files generated by RADIA.
    1616 If user does not specify the file name with the file path, then the code will look for the files in the current working directory. The path of the Radia map file must be in small letters, otherwise the code can’t find the file.
    1617 
    1618 file1
    1619 The 2nd order of insertion device field are read from the files generated by RADIA.
    1620 If user does not specify the file name with the file path, then the code will look for the files in the current working directory. The path of the Radia map file must be in small letters, otherwise the code can’t find the file.
    1621 
    1622 
    1623 Example:
    1624    WIGSLIC:  insertion, N = 10, scaling1=1.0, scaling2=1.0, method=2,  file1="/home/sources/physmach/tracy2.7/w150g11pole60\_oppose\_radia\_pour\_tracy.txt", file2= "/home/sources/physmach/brunelle/tracy-2.7/w150g11pole20\_fin.dat";
    1625      
    1626   All the parameters for ‘insertion’ is optional, the default value for scaling1 and scaling2 are 1, the default ‘method’ is 3 which means spline interpolation, the default ‘N’ is 1, the default values for all the other parameters are 0.
    1627 
    1628 \subsection{RF cavity}
    1629  To define the RF cavity, use the command:
    1630 Symbol: cavity, Frequency = RF frequency, Voltage = RF voltage, Phase = synchrotron 
    1631                            Phase, harnum = harmonic number of the RF cavity;
    1632 Here “symbol” is the element name, “cavity” means that this element is a RF cavity; all the other parameters are explained in Table .
    1633 Table   Parameters of RF cacity in the lattice file.
    1634 Symbol
    1635 Parameter
    1636 Units
    1637 frequency
    1638 RF frequency
    1639 [Hz]
    1640 voltage
    1641 RF voltage
    1642 [Volt]
    1643 phase
    1644 synchrotron phase
    1645 [degree]
    1646 harnum
    1647 harmonic number
    1648 -
    1649 
    1650 
    1651  Example:
    1652       CAV: Cavity, Frequency = 499.95e6, Voltage=1.22e6, phase = 30, harnum=328;
    1653  
    1654  The harmonic number of the RF cavity is mandatory, and the other parameters of “cavity” are optional, the default values are 0.
    1655 
    1656 \subsection{corrector}
    1657 To define the corrector, use the command:
    1658 Symbol: corrector, horizontal/vertical, method = integrated method;
    1659 Here “symbol” is the element name, “corrector” means that this element is a corrector; all the other parameters are explained in
    1660 Table   parameters of correctors in the lattice file.
    1661 Symbol
    1662 Parameter
    1663 Units
    1664 Horizontal / vertical
    1665 â€œhorizontal” means the element is a horizontal corrector; “vertical” means the element is a vertical corrector
    1666 -
    1667 method
    1668 Order of symplectic integration method.
    1669 Value ‘1’ means 1st order, ‘2’ means 2nd order, and ‘4’ means 4th order
    1670 1,2,4
    1671                
    1672  Example:
    1673 {** Horizontal correctors **}
    1674 CH  : corrector, horizontal, method=intmeth;
    1675 {** Vertical correctors **}
    1676 CV  : corrector, vertical, method=intmeth;
    1677 
    1678   The parameters of “corrector” are optional, the default value for ‘method’ is 0.
    1679 
    1680 Notice:
    1681 The “symbol” of correctors are special!!!!
    1682 For a lattice with correctors,
    1683 User must specify the name of  corrector in the input file “*.prm” with the commands:
    1684                             h\_corr         HCM
    1685                          or
    1686                            v\_corr         VCM
    1687 Here “HCM” is the name of the corrector defined in the lattice for horizontal orbit correction; “VCM” is the name of the corrector defined in the lattice for vertical orbit correction.
    1688 
    1689 
    1690 \subsection{Marker}
    1691 To define a marker, use the command:
    1692 Symbol: marker;
    1693 Here “symbol” is the name of the element, “marker” means the element is a marker in the lattice, it does not have length or field strength, etc.
    1694 
    1695 \subsection{BPM (To be updated)}
    1696   BPM is a special marker in the lattice; the “symbol” name must be “BPM” (???). User can
    1697 define the BPM as:
    1698 BPM   : type;
    1699 
    1700   Normally Its type is defined as “Marker” type, but in order to include the misalignment error of BPM into the lattice, it must be defined as “Beam Position Monitor” type which is in fact multipole type, since only the element with multipole type is saved with displacement error, field error, etc.
    1701 
    1702 Notice:
    1703 For lattice with BPMs,
    1704 User must specify the name of  BPM in the input file “*.prm” with the commands:
    1705                             bpm       beaPosMonitor
    1706 Here “beaPosMonitor” is the name of the BPMs defined in the lattice.
    1707 
    1708 \subsection{Girder}
    1709   Girder is a special element, it’s the girder used in the real machine to support the magnetic elements and other elements. It is defined as:
    1710                    Symbol: type;
    1711 
    1712   Normally Its type is defined as “Marker” type, but in order to include the misalignment error of girder into the lattice, it must be defined as “multipole” type, since only the element with multipole type is saved with displacement error, field error, etc.
    1713   For convenience, it’s better to define the beginning of the girder and also the end of the girder, and the elements between the beginning and end of the girders are the elements who are put on the girder in the real machine.
    1714 
    1715 Notice:
    1716 For lattice with girders,
    1717  User must specify the name of  girder in the input file “*.prm” with the commands:
    1718                                    gs       Girder\_Start
    1719                                    ge       Girder\_End
    1720 
    1721 Here ‘Girder\_Start’ is the name of the start of girder defined in the lattice; ‘Girder\_End’ is the name of the end of girder defined in the lattice.
    1722 
    1723 \subsection{Element block}
    1724   To construct the element block, use the following format:
    1725            Symbol: elem1, elem2,
., block1,block2;
    1726 Here “Symbol” is the name of the element block, and “elem1”, “elem2”, “block1”, “block2” are the element or sub element blocks in this element block.
    1727   If there are N the same element/block subsequently, user can use ‘N*element/block’ to simply the definition. For example:
    1728                         SINJ: SD1a, ssep, 3*SEP,esep,SD1c,eHU600,SD1d;
    1729 In this example element block, there are 9 elements/blocks, and 3 elements/blocks “SEP” subsequently.
    1730 
    1731 \subsection{Cell}
    1732  User can define the cell structure using the command:
    1733 
    1734              CELL : $\langle$ block name $\rangle$, SYMMETRY=$\langle$ symmetry $\rangle$;
    1735 
    1736 $\langle$ block name $\rangle$ is the name of a block; $\langle$ symmetry $\rangle$ is the number of super symmetry or the number of the block in the ring.
    1737 
    1738 Example:
    1739 
    1740          CELL: BL1, Symmetry=12;
    1741 
    1742 This example defines the cell with block “BL1”, and the number of super symmetry is 12. The output of the Tracy3 with symmetry large than 1 will give the
    1743 tunes and chromaticities in one symmetric period.
    1744 
    1745 \subsection{Ring}
    1746 To define the ring, use the command:
    1747                RING: elem, block
.
    1748 It’s similar to define an element block, but must with the fixed symbol name “RING”. For example:
    1749 RING: DEBUT,SUP1,SUP2,SUP3,SUP4,CAV,FIN;
    1750 5.1.23  End line
    1751  To end the lattice file, user needs to use the following command at the end of the lattice file:
    1752 End;
    1753 This command is mandatory.
    17542641
    17552642\section{Multipole field error file}
    … …  
    17792666Bn defines the upright component of the magnetic field, then for the component of a skew quadrupole or a vertical corrector, Bn = 0
    17802667An defines the skew component of the magnetic field, then for the component of a dipole or upright quadrupole, An = 0.
    1781 The line start with ‘\#’ is comment line.
    1782 The blank line in the multipole definition file is neglected by the code.
     2668The line start with ‘\#’ is a comment line.
     2669The blank lines in the multipole definition file are neglected by the code.
    17832670
    17842671There are two ways to define the multipole field errors strength, one is to define the measured field errors at the pole tip location $r_0$,
    1785 then $b_n$ and $a_n$ are respectively the scale coefficient of the main magnetic field coeffeicient, for example, to define the decupole field
     2672then $b_n$ and $a_n$ are respectively the scale coefficient of the main magnetic field coeffeicient. For example, to define the decupole field
    17862673errors inside a horizontal bending dipole with coefficient $b_1$, we define the normal scale coefficience as $c_5$ and skew scale coefficience
    17872674as $d_5$, then the $b_5$ component of this decupole is $c_5$ * $b_1$ and the skew coefficience $a_5$ is $d_5$ * $b_1$; that is
    … …  
    17892676 b_5 &=& \frac{1}{B \rho} \frac{c_5 * B_0}{r_0^5}  \\
    17902677 a_5 &=& \frac{1}{B \rho} \frac{d_5 * B_0}{r_0^5} \\
    1791  b_1 &=& \frac{1}{B \rho} B_0
    17922678\end{eqnarray*}
    1793 This method is the simplest way to define the multipole errors inside a lattice element.
     2679where
     2680\begin{equation}
     2681 b_1 = \frac{1}{B \rho} B_0.
     2682\end{equation}
     2683This method is the simplest way to define the multipole errors inside a lattice element. The default scaling factors $c_n$ and $d_n$ are 1.
    17942684
    17952685Another way is to direct define the multipole field coefficiences $b_n$ and $a_n$, that is, set $r_0 = 0$.
    … …  
    19152805\#  name       x(m)      y(m)      r (rad)
    19162806\#-----------------------------------------------------------------------
     2807\begin{table}[h]
     2808\centering
     2809\caption{}
     2810\label{}
     2811\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     2812\hline
     2813\hline
     2814\end{tabular*}
     2815\end{table}
     2816
    19172817girder  sys   100.0e-6  100.0e-6            0.5e-03
    19182818quad    sys    30.0e-6   30.0e-6       80.0e-06
    … …  
    19322832\#  name       x(m)      y(m)      r (rad)
    19332833\#-----------------------------------------------------------------------
     2834\begin{table}[h]
     2835\centering
     2836\caption{}
     2837\label{}
     2838\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.5\linewidth} | p{0.15\linewidth} |}
     2839\hline
     2840\hline
     2841\end{tabular*}
     2842\end{table}
     2843
    19342844girder  rms   100.0e-6  100.0e-6            0.5e-03
    19352845quad    rms    30.0e-6   30.0e-6       80.0e-06
Note: See TracChangeset for help on using the changeset viewer.