source: TRACY3/trunk/tracy/tracy/doc/soltracy3_userManual_developer.tex @ 32

\documentclass[fleqn]{article}
\author{Jianfeng Zhang \footnote{LAL, Orsay, France.Email: \href{mailto:zhangj@lal.in2p3.fr}{zhangj@lal.in2p3.fr}}}
\title{Soltracy3 mannual for developpers}

%% left align the long equations in the 'aligned' enviroment
\usepackage[fleqn]{amsmath}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage[colorlinks=true,urlcolor=magenta,citecolor=blue]{hyperref}
\usepackage{color}
\usepackage{setspace}


%% auto center the sentence in the line
\newenvironment{tightcenter}{%
   \vspace{0.02in} 
 \setlength\topsep{0pt}
  \setlength\parskip{0pt}
  \begin{center}
}{%
  \end{center}
\vspace{0.02in} 
 }

%% auto wrap a long word
\newcommand*\wrapletters[1]{\wr@pletters#1\@nil}
\def\wr@pletters#1#2\@nil{#1\allowbreak\if&#2&\else\wr@pletters#2\@nil\fi}

% define the file path font
\newcommand{\pathfont}[1]{\textit{\wrapletters{#1}}} 
% define the font and color of the Tracy command in Tracy file
\newcommand{\tracycommand}[2]{\begin{tightcenter} 
                               \textsf{\textcolor{red}{#1}} \quad \textsf{\textcolor{blue}{#2}} 
                              \end{tightcenter}}
\newcommand{\tracycomm}[1]{\textsf{\textcolor{red}{#1}}}
\newcommand{\tracypara}[1]{\textsf{\textcolor{blue}{#1}}}

% lattice element definition 
\newcommand{\latticedef}[3]{\begin{tightcenter}
                               \textsf{\textcolor{black}{#1}}   
                               \textsf{\textcolor{red}{#2}} \quad \textsf{\textcolor{blue}{#3}} 
                              \end{tightcenter}}
\newcommand{\elemname}[1]{\textsf{\textcolor{black}{#1}}}
\newcommand{\elemkeyword}[1]{\textsf{\textcolor{red}{#1}}}
\newcommand{\elempara}[1]{\textsf{\textcolor{blue}{#1}}}

\newcommand{\notespace}[1]{\vspace{0.1in}\textbf{#1} \vspace{0.05in}}


\begin{document}

\maketitle
\tableofcontents

\onehalfspacing

\section{Change Log}

\begin{itemize}
\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 
entrance edge effect and fringe field of the dipole are turned on, with ``edge\_effect1 = 0'',
this effects are turned off. These two effects at the exit of the dipole are controlled by 
``edge\_effect2''.
\end{itemize}

\section{Introduction}
Tracy is a code to do long term tracking, and is written in the mixture of c and c++ by Johann Bengsston 
and other scientists (???). 

This manual is for SOLEIL version Tracy which is maintained and developped by 
L. Nadolski and J. Zhang in Synchrotron SOLEIL. The former manuals of Tracy are in the file folder 
``tracy/tracy/doc'' of the Tracy3 code.



\begin{description}
\item[Rotation angle]
The user can define the design rotation angle  
of the magnetic lattice element in the lattice file.
\item{parameters of the lattice element: rotation, field, misalignment errors?}
The user can define systematic
and random rotation errors, the systematic and random displacement error, and systematic and random multipole field error 
of the lattice element in an external file (see section.~\ref{}), these 
variables can't be defined in the lattice file as an element parameters.

\item{Simulation method: matrix or tracking?}
There are two types of simulation in Tracy, Matrix method (Taylor's nonsymplectic map) and symplectic tracking. The default mode is the symplectic tracking. User can active the matrix mode by setting globval.MatMeth in the source code...(Need to update in the input script to active this mode. Be careful, during the 
lattice reading, the t2init() will active the tracking mode...)

\item{Define RING or transfer line type in the lattice file}
  in Lattice\_Read() of t2lat.cc, it seems like we can define a transfer line
  in Tracy, using the variable V.Symmetry != 0, how to define a transfer line
  in the lattice?  ANSWER: RingType = 1;  {define the ring}, or RingType = 0; 
 {define the transfer line}.  


   The variable is: globval.RingType = 1/0, 1: ring, 0: transfer line.
  
\end{description}


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. 

   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.
Attention: 
In the user defined file, such as the user input script, the file to define multipole field errors or alignment errors, or the file to define vacuum chambers, the maximum numbers of column is 130 (Not including comment line which starts with symbol \#.), and the spaces between each parameters or variables can’t contain “TAB” key, otherwise the code can’t work properly. This is because the routine to read the user defined input file is written in C. These limits will be improved in the future development. 
Although 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”.   

  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”. 

\section{ Non-parallel version Tracy}
\subsection {Compile}
The make file of Tracy is generated by ``automake''. Based on the compilers used, 
user needs to update “\textsf{\wrapletters{make\_for\_gcc.sh}}” under 
path ``\pathfont{\$HOME/TracyIII/}'' 
or the ``Makefile.am'' under path ``\pathfont{\$HOME/TracyIII/tracy/tracy/src}'' 
and ``\pathfont{\$HOME/TracyIII/tracy/tools}''. The compilers used on the server 
``metis'' of SOLEIL Synchrotron are ``gfortran'', and ``gcc''.

To compile the code, run the command under the shell terminal:
\begin{tightcenter}
 \textsf{make\_for\_gcc.sh}     \qquad   \textsf{opt} 
\end{tightcenter}
Then the executive file ``soltracy'' is automatically 
generated under path ``\pathfont{\$HOME/TracyIII/tracy/tools}''.   

\subsection{Run}
 To execute Tracy, the user needs to define an input file with the 
 the lattice file names and the related commands (section~\ref{}).
 The name of the input file can be any valid characters. Although 
 there is no limitation to the extension of the file, the extension 
 ``.prm'' is preferred. For example, To run the user defined input file 
 ``Input\_test.prm'', user can type the command:
\begin{tightcenter}
  \textsf{soltracy}       \qquad        \textsf{Input\_test.prm}
\end{tightcenter}

\section{ Parallel version Tracy}
In order to reduce the tracking time, the parallel version Tracy can be used 
on the cluster. Until now, the following three features of Tracy are 
parallelized:
\begin{itemize} 
\item 
Frequency map analysis for on momentum particle, command ``FmapFlag''.
\item 
Frequency map analysis for off momentum particle, command ``FmapdpFlag''.
\item 
Track momentum acceptance at lattice elements, command ``MomentumAccFlag''.
\end{itemize}

\subsection{Compile}
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. The details are shown in 
the following steps.
\begin{enumerate}
\item
The path of included files of Intel MPI is added in ``Makefile.am'' under 
path ``\pathfont{\$HOME/TracyIII/tracy/tracy/src}'' (shown in BLUE color):

          \wrapletters{INCLUDES = -I../inc -I\$(NUM\_REC)/inc \quad
          -I/opt/intel/impi/3.2.2.006/include64}

\item
 The execute file, source file, paths of included files and library of Intel 
MPI are modified in ``Makefile.am'' under path ``\pathfont{\$HOME/TracyIII/tracy/tools}''
 (shown in BLUE color):

bin\_PROGRAMS = psoltracy 

soltracy\_SOURCES  = \texttt{soltracy.cc  nrutil.c nrcheck.c    }
\texttt{  nrlinwww.c   nrframe.c ../tracy/src/tracy\_lib.cc $\rightarrow$}

  psoltracy\_SOURCES  = \texttt{psoltracy.cc  nrutil.c  nrcheck.c   
  nrlinwww.c   nrframe.c   ../tracy/src/tracy\_lib.cc}

  LIBS =  \texttt{\wrapletters{-L\$(NUM\_REC)/lib \quad
          -L/opt/intel/impi/3.2.2.006/lib64   \quad -L\$(LIBPATH)  \quad
          -lrecipes\_c\_icc \quad -lstdc++ \quad -lgfortran \quad -lmpichcxx}}
 
INCLUDES = \texttt{\wrapletters{-I\$(TRACY\_LIB)/tracy/inc \quad -I\$(NUM\_REC)/inc 
                   \quad  -I/opt/intel/impi/3.2.2.006/include64}}

\item
The compilers used in the parallel computing are defined in the 
``\wrapletters{make\_for\_psoltracy.sh}'' located in path ``\$HOME/TracyIII'' 
as (shown in BLUE color):

                 CC = \texttt{mpiicc}

                CXX = \texttt{mpiicpc}

                F77 = \texttt{mpiifort}

Depending on the compilers used to do parallel computation, user needs to 
update the compilers in ``make\_for\_psoltracy.sh'' and the paths of included 
files and library which are shown above with blue color. 

After updating compilers, paths of included files and library for parallel 
computation, user can run 
\begin{tightcenter}
\textsf{make\_for\_psoltracy.sh}
\end{tightcenter}
under the shell script to compile the parallel Tracy. After compilation, 
the execute file ``psoltracy'' is automatically generated under the 
path ``\pathfont{\$HOME/TracyIII/tracy/tools}''.
\end{enumerate}


\subsection{Run}
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. 

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 \texttt{test.prm} to tell Tracy what jobs are need to be done on the 
cluster,  define script \textsf{\wrapletters{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:
\begin{tightcenter}
  \textsf{lance\_tracy3\_parallel.sh  \qquad   test.prm}
\end{tightcenter}


\section{ User input script}
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:
\begin{itemize}
\item
The blank lines and lines starting with ``\#'' (comment line) are ignored 
by the code. 
\item
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.
\item
The commands with the last 4 characters as ``Flag'' are executed according 
to the sequence in the code.
\item
The definition of lattice file at the beginning of the user script is mandatory.
\item
If the horizontal correctors, or vertical correctors, or girders, Beam Position
Monitors, or skew quadrupoles are defined in the lattice file, user must 
declare the element name at the beginning of Tracy input file. 
\item
One keyword command uses one line. User can not define more than one command 
at the same line.    
\item
Except explanation, all commands with Boolean flag are the generic commands, 
that is, the commands are not machine dependent.
\end{itemize}

\subsection{File path}
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 without
file path in the Tracy input file, Tracy will look for the file in the current 
work path. Otherwise, user need to provide the absolute path of the file which is 
not located at the current path, such as: ``\texttt{\wrapletters{/home/physmach/Tracy3/tracy/soleil.lat}}''.
Another method is to provide the filename without absolute path, but put all the 
called external files at a certain directory, and this directory is defined in the
Tracy input file using the command:
                \tracycommand{in\_dir}{user\_defined\_path}
For example,
                \tracycommand{in\_dir}{/home/zhang/codes/TracyIII/lattice/}
This example tells the code all the files defined with absolute file path in the Tracy 
input file are located 
at the directory \pathfont{/home/zhang/codes/TracyIII/lattice/}. If user declares the files 
without absolute path and does not set the directory through command \textsf{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.

\section{File names}   

\subsection{Lattice file name}
In the input script, user must define the lattice name, this is mandatory. 
The command is: 

\tracycommand{lat\_file}{lattice\_file\_name}

Here \tracypara{lattice\_file\_name} is the lattice file name without the extension ``.lat''. 
For example, the following command sets the lattice file of SOLEIL ring:
\tracycommand{lat\_file}{solamor2}

n Tracy 3, after reading the lattice, Twiss parameters are automatically printed to the 
file \textsl{linlat.out}.                                 
  
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 Tracy input file: 
\tracycommand{h\_corr}{HCM}
\tracycommand{v\_corr}{VCM}
\tracycommand{gs}{GS}
\tracycommand{ge}{GE}
\tracycommand{bpm\_name}{BPM}
\tracycommand{qt}{QT}
Here \tracypara{HCM} is the name of horizontal correctors for horizontal orbit correction, 
or the horizontal correctors on which the multipole field errors are added in SOLEIL lattice; 
\tracypara{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; 
\tracypara{GS} is the name of the start girder; \tracypara{GE} is the name of the end girder; 
\tracypara{BPM} is the name of beam position monitors defined in the lattice file; the 
                BPM acts as both horizontal BPM and vertical BPM. 
\tracypara{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.  

\subsection{Multipole field error file name (SOLEIL lattice)}
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: 
\tracycommand{multipole\_file}{multipole\_file\_name}
Here \tracypara{multipole\_file\_name} is the user defined multipole field error file, 
the format of this file is given in section~\ref{}.

If the multipole field errors of horizontal, vertical correctors and skew quadrupoles 
are defined in the \tracypara{multipole\_file}, user MUST specify the names of these 
lattice elements in the Tracy input file as the following example: 
\tracycommand{h\_corr}{CH}
\tracycommand{v\_corr}{CV}
\tracycommand{qt}{QT}
Here \tracypara{CH}, \tracypara{CV} and \tracypara{QT} are the names of horizontal, 
vertical correctors, and skew quadrupoles respectively which are defined in the lattice file.

\subsection{Files of multipole field errors of correctors and skew quadrupoles (SOLEIL lattice)}
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:
\tracycommand{fic\_hcorr}{corh.txt}
\tracycommand{fic\_vcorr}{corv.txt}
\tracycommand{fic\_skew}{corqt.txt}
Here \tracypara{corh.txt} and \tracypara{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:\\
\vspace{0.02in}
\texttt{Hcorr\_strength [T.m] = corh *\_convHcorr /brho; (horizontal correctors) \\}
\vspace{0.02in}
\texttt{Vcorr\_strength [T.m] = corv *\_convVcorr /brho;  (vertical correctors)} \\
\vspace{0.02in}
\texttt{Qt\_strength [T.m] = corqt *\_convQt /brho;  (skew quadrupoles)} \\
\vspace{0.02in}

Here 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. 
  
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.

\subsection{ File to define field strength of virtual coupling source elements (SOLEIL lattice)}
 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: 
\tracycommand{virtualskewquad\_file}{virtual\_skew\_quad\_currents.txt}

Here \tracypara{virtual\_skew\_quad\_currents.txt} is the user defined file with strength 
of vertical coupling source. 

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:
\latticedef{SQ:}{quadrupole,}{tilt=45.0, K= 0.0, method=4, N=1;}
and 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 .
  The measured current value qtcorr[i] of the ith coupling source is converted to the corresponding integrated skew quadrupole field strength corr\_strength as
corr\_strength [m-1] = qtcorr[i]*conv/brho;
here brho is momentum rigidity, and the conversion constant conv is 93.88e-4 [A-1.T].

\subsection{Cut off value}
  Set the cut off value of all random distribution (Gaussian distribution) to “n” times of the RMS value sigma:
normalcut       n

\section{Physics: Hamiltionian}
The lattice elements in Tracy can be classified into two types: drift and multipoles (thick or thin).

The dynamic motion of a conserved system can be described by a Hamiltonian. For an accelerator system 
without radiation
damping (energy loss) and RF cavities (energy gain), the motion of a single electron in the magnetic field can be described using the 
following Hamitonian in the curvilinear coordinate system (Merz...)
\begin{eqnarray}
H (x,P_x; y, P_y; -t, \delta; s) &=&  L + V  \\
                                 &=& -(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)]  \\
P^2 & =& P_x^2 + P_y^2 + P_z^2
\end{eqnarray}
$h_{\mathrm{ref}}$ is the curvature of reference orbit inside the dipole. 
The $(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 
horizontal, vertical, and longitudinal mechanical momentums. A more convienent way is to expand the electron motion
around the motion of a reference particle with total momentum $P_0$, so
\begin{eqnarray}
\frac{1}{P_0}H (x,P_x; y, P_y; -t, \delta; s) &=& \\
H (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) \\
                                &=& -(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) 
\end{eqnarray}
with 
\begin{eqnarray}
p_x &=& \frac{P_x}{P_0}  \\
p_y &=& \frac{P_y}{P_0}  \\
p &=& \frac{P}{P_0} = \frac{\Delta P + P_0}{P_0} = (1+\delta)   \\
\delta &=& \frac{\Delta P}{P_0} \\
B \rho &=& \frac{P_0}{e} (magnetic rigidity)
\end{eqnarray}

With 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.),
the Hamitonian can be expressed with the canonical coordinates $(x,p_x; y, p_y; -ct, \delta; s)$ (Tracy-2 Manual, J. Bengtsson)

\begin{align*} 
%\label{Tracy:Exact:H}
H (x,p_x; y, p_y; -ct, \delta; s) \\
&=-(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  \\ 
&= -(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}  \\
& + \frac{A_z}{B \rho} + \delta  \\ 
&= \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} \\
& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}}_\text{Gemometic components due to the curvilinear coordinate inside the dipole}\\ 
& +\underbrace{\frac{A_z}{B \rho}}_\text{magnet contribution}  \\
& +\underbrace{\delta}_\text{due to the canonical coordinate $-ct$ instead of $-t$}\\  
A_z & =A_z(x,p_x; y, p_y,s)
\end{align*}

The 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.

For 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$,
so the Hamiltonian is
\begin{align}
\label{eqn:exact:H:NoFF}
H (x,p_x; y, p_y; -ct, \delta; s) \\
&= \underbrace{-(1+h_{\mathrm{ref}}x)\sqrt{(1+\delta)^2 - p_x^2 - p_y^2)}}_\text{kinetic energy} \\
& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}}_\text{Gemometic components due to the curvilinear coordinate inside the dipole}\\ 
& +\underbrace{\frac{A_z}{B \rho}}_\text{magnet contribution}  \\
& +\underbrace{\delta}_\text{due to the canonical coordinate $-ct$ instead of $-t$}\\  
\end{align}

From eqn.~\ref{eqn:exact:H:NoFF}, it is easy to get the map of the particle inside different lattice elements.


\subsection{Map of drift}
\label{H:drift}

In the drift, $A_z = 0$, and $h_{\mathrm{ref}}$ = 0, from eqn.~\ref{eqn:exact:H:NoFF}, we can get the Hamiltonian
inside a drift is
\begin{align}
\label{eqn:H:exact:drift}
H (x,p_x; y, p_y; -ct, \delta; s) = -\sqrt{(1+\delta)^2 - p_x^2 - p_y^2)} + \delta
\end{align}

In large ring, in order to increase the tracking speed, we can expand the sqare root in 
eqn.~\ref{eqn:H:exact:drift} to get the approximate Hamitonian.
That is,
\begin{align}
\label{eqn:H:approxi:drift}
H (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\\
                                  &= \frac{p_x^2 + p_y^2}{2(1+\delta)}
\end{align}


From eqn.~\ref{eqn:H:exact:drift}, it is easy to get the map inside the drift for the 
\textbf{small ring}:
\begin{align}
x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = \frac{p_{x0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}= \frac{p_{y0}}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\ 
(-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 \\
or \\
(ct)^{'} = \frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}}-1 \\
p_x  = p_{x0} \\
p_y  = p_{y0} \\
\delta = \delta_0
\end{align}

From eqn.~\ref{eqn:H:approxi:drift}, it is easy to get the map inside the drift for the 
\textbf{big ring}:
\begin{align}
x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = \frac{p_{x0}}{1+\delta_0} \\
y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}= \frac{p_{y0}}{1+\delta_0} \\ 
(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} =-\frac{p_{x0^2}+p_{y0}^2}{2(1+\delta_0)} \\
or \\
(ct)^{'} = \frac{p_{x0^2}+p_{y0}^2}{2(1+\delta_0)} \\
p_x  = p_{x0} \\
p_y  = p_{y0} \\
\delta = \delta_0
\end{align}

\subsection{Map of mutipoles}
 From eqn.~\ref{eqn:exact:H:NoFF}, we can get the Hamiltonian
inside a multipole without fringe field is
\begin{align}
\label{eqn:H:exact}
H (x,p_x; y, p_y; -ct, \delta; s) \\
=& \underbrace{-\sqrt{(1+\delta)^2 - p_x^2 - p_y^2}+\delta}_\text{H drift} \\
& \underbrace{-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}}_\text{H kick} \\
& + \underbrace{\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho}}_\text{H kick}  
\end{align}

In eqn.~\ref{eqn:H:exact}, the Hamiltonian is decomposed into two part, one is the Hamiltonian
of the drift which is due to the kinetic energy of the system (section~\ref{H:drift}), another part is the kick
due to the multipoles which will give the kick to the particle.
Now we only need to focus on the Hamiltonian of the multipoles which induces the kick map:
\begin{align}
\label{eqn:H:exact:multipole}
H (x,p_x; y, p_y; -ct, \delta; s) \\
&=-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} \\
& +\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho}
\end{align}

Similarly, by expand the sqare root in eqn.~\ref{eqn:H:exact}, we can get the approximate Hamiltonian 
of the multipole as
\begin{align}
\label{eqn:H:approxi:multipole}
H (x,p_x; y, p_y; -ct, \delta; s) \\
&=-h_{\mathrm{ref}}x \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} \\
& +\frac{x}{\rho} +\frac{x}{2\rho^2}-\frac{A_z}{B \rho} \\
&=-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
\end{align}
where $h_{\mathrm{ref}}$ is the curvature due to the curlininear coordinates inside the dipole,
$h_{\mathrm{ref}} = 1/\rho_{ref}$;
$h_{\mathrm{bend}}$ is due to the bending curvature of the dipole which is determined by the dipole 
field, $h_{\mathrm{bend}} = 1/ \rho_{bend}$. $h_{\mathrm{ref}} \neq 0$ only inside dipoles.

In the dipole, $A_z \neq 0$, and $h_{\mathrm{ref}} \neq $ 0, so 
from eqn.~\ref{eqn:H:exact:multipole}, we can get the kick map due to the dipole
in the \textbf{small ring} which use the exact Hamiltonian:
\begin{align}
\label{eqn:kickmap:exact}
x^{'} = \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)}} \\
y^{'} = \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)}} \\ 
p_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}\\
p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
(-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)}} \\
or \\
(ct)^{'} = h_{\mathrm{ref}} x_0 \frac{1+\delta_0}{\sqrt{(1+\delta_0)^2 -(p_{x0}^2+p_{y0}^2)}} \\
\delta = \delta_0 \\
B \rho = \frac{p_0}{e}
\end{align}
where 
\begin{align}
\frac{\partial A_z}{\partial x} = - B_y \\
\frac{\partial A_z}{\partial y} = B_x 
\end{align}
since
\begin{align}
A_x = 0 \\
A_y =0
\end{align}
inside the body of the multipoles, and 
\begin{align*}
\vec{B} = \Delta \times \vec{A}  \\
\hat{x} & \hat{y} & \hat{z} \\
\frac{\partial}{x} &  \frac{\partial}{y} &  \frac{\partial}{z} \\
A_x  & A_y & A_z \\
\end{align*}


In the dipole, $A_z \neq 0$, and $h_{\mathrm{ref}} \neq $ 0, so 
from eqn.~\ref{eqn:H:approxi:multipole}, we can get the kick map due to the dipole
in the \textbf{big ring} which use the exact Hamiltonian:
\begin{align}
\label{eqn:kickmap:approxi}
x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = h_{\mathrm{ref}} x_0 \frac{p_{x0}}{1+\delta_0} \\
y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  h_{\mathrm{ref}} x_0 \frac{p_{y0}}{1+\delta_0} \\ 
p_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}\\
p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
(-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)} \\
or \\
(ct)^{'} =-\frac{h_{\mathrm{ref}} x_0}{1+\delta_0} \frac{(p_{x0}^2+p_{y0}^2)}{2(1+\delta_0)} \\ 
\delta^{'} = 0 
\end{align}

For other multipoles (quadrupoles, sextupole, decapole, octupole, etc), the curvilinear coordinate is 
the cartesian coordinates, that is $h_{ref}$ = 0, so from eqn.~\ref{eqn:kickmap:exact}, the kick map for 
these multipoles in the small ring is:  
\begin{align}
\label{eqn:kickmap:exact:multipole}
x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = 0 \\
y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  0 \\
p_x^{'}  = -\frac{\partial H}{\partial y_0} = - (h_{\mathrm{bend}} + \frac{B_y}{B \rho})\\
p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} = 0\\
or \\
(ct)^{'} = 0 \\
\delta^{'} = 0 
\end{align}

With $h_{ref} = 0$, from eqn:~\ref{eqn:kickmap:approxi}, the kick map for these 
multipoles (quadrupoles, sextupole, decapole, octupole, etc) in the big ring is:
\begin{align}
\label{eqn:kickmap:approxi:multipole}
x^{'} = \frac{dx}{ds} = \frac{\partial H}{\partial p_{x0}} = 0 \\
y^{'} = \frac{dy}{ds} = \frac{\partial H}{\partial p_{y0}}=  0 \\
p_x^{'}  = -\frac{\partial H}{\partial y_0} = - (h_{\mathrm{bend}} + \frac{B_y}{B \rho})\\
p_y^{'}  = -\frac{\partial H}{\partial y_0} = \frac{1}{B \rho} \frac{\partial A_z}{\partial y_0} = \frac{B_x}{B \rho}\\
(-ct)^{'} = \frac{d(-ct)}{ds} = \frac{\partial H}{\partial \delta_0} = 0\\
or \\
(ct)^{'} = 0 \\
\delta^{'} = 0 
\end{align}

From the eqn~\ref{eqn:kickmap:exact} to eqn.~\ref{eqn:kickmap:approxi:multipole}, it's clear 
that the kick map from the main body of dipoles are different in the small ring and big ring;
while the kick map from the main body of other type of multipoles are the same in small
rings and big rings.








\section{Magnetic field}

A. Dragt ....(Lie methods for acceleator........)

\section{FF of dipole}
\subsection{kick map}
E. Forest ...........

\section{FF of quadrupole}
\subsection{kick map}


\section{Machine mode}
\subsection{Transfer line}
Tracy can simulate the transfer line (TL), to calculate some features
of this type of the machine, for example, to transfer the twiss functions
and the orbits. User can define the TL type in the lattice file 
using the command:
\tracycommand{RingType = 0}{}

Since the symplecticity is not important to the transfer map of a 
TL, the twiss functions and orbits of a TL is calculated using 
a 6-dimensional (6D) linear Taylor transfer matrix.

\begin{itemize}
\item The initial phase of the TL is 0.
\item The initial parameters of the TL (alpha, beta, mu, and orbit) are
      defined in the file ``soleilcommon.cc''.
      Maybe these parameters can be defined in the lattice file or ``*.prm''
      in the future.
\item The calculated optical functions at i-th lattice element can be called 
      using: Cell[i] $\rightarrow$ Alpha, Cell[i] $\rightarrow$ Beta, 
      Cell[i]$\rightarrow$ Nu,Cell[i] $\rightarrow$ Eta, 
      Cell[i] $\rightarrow$ Etap.
\item The optical functions (alpha, beta, mu), orbits will be automatically
      calculated and saved in the file ``cod.out''. 
\item
If the BPMs are defined in the lattice file, and the BPMs names are declared
in the ``*.prm'' file with the command: 
\tracycommand{bpm\_name}{BPMs names}
then the 6D orbits at the BPM positions will be saved in the 
file ``6Dcod.out''.
\item See also section \ref{sec:general:files}.
\end{itemize}

Called functions: Cell\_Twiss\_M() in t2ring.cc.

The functions with ``...M()'' are for the transfer line. 

\subsection{Ring}
User can define the ring type in the lattice file using the command: 
\tracycommand{RingType = 1}{}

If this machine type is not defined, then the default machine type 
is ring.

\begin{itemize}
\item
The momentum compaction factor is calculated and printed to the terminal.
\item
 The twiss functions, and COD files will be automatically printed to 
a file ``cod.out''.
\item
If the BPMs are defined in the lattice, and the BPMs names are declared 
in the ``*.prm'' file using the command:
\tracycommand{bpm\_name}{BPM names}

then the 6D closed orbit at the position of the BPMs will be saved in 
a file ``6Dcod.out''.
\item 
See also section \ref{sec:general:files}.
\end{itemize}

\section{General print files}
\label{sec:general:files}

After reading the lattice file, Tracy will print several files with the general informations of 
the lattice.
\subsection{*.sum}
 This file is with the same name as the lattice file but with the file extertion ``*.sum''.
 This file is with the information: 


\begin{flushleft}
\textbf{general inforamtion} \\
\end{flushleft}

\begin{tabular}{l l l}
  dPcommon     =  1.000e-10 &dPparticle   =  0.000e+00 &Energy [GeV] = 0.050\\
  MaxAmplx [m] = 0.000e+00 &MaxAmply [m] = 0.000e+00 &RFAccept [\%] = +/- 100.00 \\
  MatMeth      =  FALSE&      Cavity\_On    =  FALSE&Radiation\_On = FALSE\\
  bpm          =  0    &                         qt           = 0 & \\ 
  hcorr         =  0   &                        vcorr        =  0 & \\
  Chambre\_On   = FALSE&            &  \\     
  alphac       =   0.0000e+00 & & \\
  nux          =   1.382583 &     nuy  =  0.859382 & \\
  ksix         =    0.000000&      ksiy  =   0.000000 &  \\
\end{tabular}


\begin{description}
\item[dPcommon]: relative energy spread.
\item[dPparticle]: 
\item[Energy]: beam energy [GeV].
\item[MaxAmplx]: maximum horizontal aperture size.
\item[MaxAmply]: maximum vertical aperture size.
\item[RFAccept [\%]]: RF acceptance.
\item[MatMeth]: use linear transfer matrix or tracking? True/false.
\item[Cavity\_On]: with RF cavity or not?
\item[Radiation\_On]: synchrotron radiation is on or off?
\item[bpm]: number of BPMs. If the user doesn't specify the name of the BPM 
  in the ``*.prm'' file, then this value is 0, it means that Tracy think 
  there is no BPMs defined in the lattice? (need to check...)
\item[qt]: number of skew quadrupoles. If the user doesn't specify the name 
   of the qt in the ``*.prm'' file, then this value is 0, it means that 
   Tracy think there is no skew quadrupoles defined in the lattice? (need to 
check...)
\item[hcorr]: number of horizontal correctors. If the user doesn't specify the name of the hcorr in the 
            ``*.prm'' file, then this value is 0, it means that Tracy think there
            is no horizontal correctors defined in the lattice? (need to check...)
\item[vcorr]: number of vertical correctors. If the user doesn't specify the name of the vcorr in the 
            ``*.prm'' file, then this value is 0, it means that Tracy think there
            is no vertical correctors defined in the lattice? (need to check...)
\item[Chambre\_On]: read the vacuum chamber definition from an external file? If it is true, then
                    an external file with the definition of the vacuum chamber aperture must
                    be defined in the ``*.prm'' file.
\item[alphac]: first order momentum compaction factor. For a transfer line, this variable is 0.
\item[nux]: horizontal phase advance for a transfer line; horizontal tune for the ring. This 
            variable is normalized by 2$\pi$.
\item[nuy]: vertical phase advance for a transfer line; vertical tune for the ring. This 
            variable is normalized by 2$\pi$.
\item[ksix]: horizontal chromaticity. This variable is only valid for a ring; it is 0 for a transfer line.
\item[ksiy]: vertical chromaticity. This variable is only valid for a ring; it is 0 for a transfer line.
\end{description}

This file also has the 6$\times$6 transfer matrix (one turn map for a ring):

\begin{flushleft} 
\textbf{OneTurn matrix}: \\
matrix: 
\end{flushleft}

\begin{tabular}{l l l l l l}
 -1.397484e+00&   1.028931e+01&   0.000000e+00&   0.000000e+00&  -1.089759e-02&   0.000000e+00\\
 1.025593e-01&  -1.470689e+00&   0.000000e+00&   0.000000e+00&   1.695979e-01&   0.000000e+00\\
 0.000000e+00&   0.000000e+00&   5.943899e-01&  -5.866019e+00&   0.000000e+00&   0.000000e+00\\
 0.000000e+00&   0.000000e+00&   5.043746e-01&  -3.295264e+00&   0.000000e+00&   0.000000e+00\\
 0.000000e+00&   0.000000e+00&   0.000000e+00&   0.000000e+00&   1.000000e+00&   0.000000e+00\\
 0.000000e+00&   0.000000e+00&   0.000000e+00&   0.000000e+00&   0.000000e+00&   0.000000e+00\\
 & & & & & \\
\end{tabular}
\\

Finally, the twiss parameters at the entrance of the first element is saved: 
\begin{flushleft}
\textbf{Twiss parameters at entrance}:\\
\end{flushleft}

\begin{tabular}{l l l l}
   Betax [m] =  8.100e+00&  Alphax = -0.000e+00& Etax [m] =  0.000e+00& Etaxp =  0.000e+00\\
   Betay [m] =  8.100e+00&  Alphay = -0.000e+00& Etay [m] =  0.000e+00& Etayp =  0.000e+00\\
\end{tabular}

\subsection{Twiss file}
This file is with the twiss functions at the end of all lattice elements, 
the file name is the same as the lattice file name, but with the file extension
``*.twi''. 

\begin{tabular}{l l l l l l l l l l l l} 
name & s & alphax & betax & nux & etax & etapx & alphay & betay & nuy & etay & etapy \\
     &[m]&        & [m]   &     & [m]  &       &        & [m]   &     & [m]  &       \\
     &   &        &       &     &      &       &        &       &     &      &        \\
\end{tabular}
where
\begin{description}
\item[name]: name of the lattice element.
\item[$s$ [m]]: longitudinal position of the element.
\item[alphax $\alpha_x$]: horizontal alpha.
\item[betax $\beta_x$ [m]]: horizontal beta functions.
\item[betay $\beta_y$ [m]]: vertical beta functions.
\item[etax $\eta_x$ [m]]: horizontal linear dispersion funciton.
\item[etay $\eta_y$[m]]: vertical linear dispersion funciton.
\item[etapx $\mathrm{d} \eta_x /mathrm{d}s$]: horizontal linear dispersion 
           funciton $\eta_x$ with respective to longitudinal coordinate $s$.
\item[etapy $\mathrm{d} \eta_y /mathrm{d}s$]: vertical linear dispersion 
           funciton $\eta_y$ with respective to longitudinal coordinate $s$.
\item[nux $\nu_x$]: horizontal phase advance of the transfer line, or 
                    horizontal tune of the ring. 
                    This value is normalized by $2 \pi$.
\item[nuy $\nu_y$]: vertical phase advance of the transfer line, or 
                    vertical tune of the ring. 
                    This value is normalized by $2 \pi$.
\end{description}

\subsection{Lattice elements property file}
Each time when running Tracy, the design values of lattice
elements will be printed to the file ``flat\_file.dat''.
This file is a very important file to check the Tracy is 
correctly running.

The printed properties of one lattice element are (also see MML)
different for the elment type: drift and multipoles (thick or thin). 




\begin{flushleft}
\textbf{\color{blue}{drift}}: 
\end{flushleft}


\begin{flushleft}
\textbf{1st line:} \\
Name; familylist number;  \\
kid number; \\
index number in the lattice, for example, ``1'' means the first element; \\

\textbf{2nd line}: 
type; method, N  \\


\textbf{type:} type of the lattice element defined in Tracy: \\

\begin{tabular}{l l}
 marker     &     -1 \\
 drift      &     0\\
 multipole  &     1\\
 cavity     &     2\\
 thin kick  &     3\\
 wiggler    &     4\\
 kick\_map  &      6\\
\end{tabular}


\textbf{method:} symplectic integration method.
        For drift, method = 0. \\


\textbf{N:}   number of pieces of the elements to be cut.
     For drift, N = 0. \\



\textbf{3rd line:}
MaxamplX0, MaxamplX1, MaxamplY0, MaxamplY1. \\
\begin{tabular}{r l}
MaxamplX0: & minimum horizontal aperture size;\\
MaxamplX1: & maximum horizontal aperture size;\\
MaxamplY0: & minimum vertical aperture size;\\
MaxamplY1: & maximum vertical aperture size;\\
\end{tabular}

\textbf{4th line:} 
Element length. \\




\textit{For example:}  \\

\begin{tabular}{l l l l}
 sd1l       &        1  &  1  &   2 \\
   0  &  0 &   0 & \\
  0.000e+00 & 0.000e+00 &  0.000e+00 &  0.000e+00 \\
  2.000e-01 & & & \\
\end{tabular}
\end{flushleft}


\begin{flushleft}
\textbf{\color{blue}{multipoles:}}

Depending on the elements length, the printed information of thick 
and thin multipoles are different. But both types of multipoles have 
the following general informations as the drift: \\

\textbf{1st line:} \\ 
Name; familylist number;  kid number; index number in the 
lattice, for example, ``1'' means the first element;\\

Name: element name. \\



\textbf{2nd line:}  
type; method, N 

\textbf{type:} type of the lattice element defined in Tracy: \\
\begin{tabular}{l l}
 marker   &      -1\\
 drift    &       0\\
 thick multipole &      1\\
 cavity    &      2\\
 thin multipole &     3\\
 wiggler       &  4\\
 kick\_map     &   6\\
\end{tabular}

\textbf{method:} symplectic integration method defined in the lattice, or 
        the default method for this element.\\

\textbf{N:}   number of pieces of the elements to be cut defined in the 
     lattice or the default value ``1''.\\

\textbf{3rd line:} 
MaxamplX0, MaxamplX1, MaxamplY0, MaxamplY1.\\

\begin{tabular}{r l}
MaxamplX0:& minimum horizontal aperture size;\\
MaxamplX1:& maximum horizontal aperture size;\\
MaxamplY0:& minimum vertical aperture size;\\
MaxamplY1:& maximum vertical aperture size;\\
\end{tabular}

\textbf{For a thick multipoles,}  \\
\textbf{4th line:} 
DsX, DsY, PdTpar, PdTsys, PdTrms*PdTrnd. \\


\textbf{DsX:} horizontal displacement error of the element. \\
\textbf{DsY:} vertical displacement error of the element. \\
\textbf{PdTpar:} total designed rotation angle [degree]. \\
\textbf{PdTsys:} systematic designed rotation angle  \\
        defined in the lattice.[degree]. \\
\textbf{PdTrms*PdTrnd:} random rotation errors of the element multiplied 
        by a scale factor PdTrnd. The default value of 
        PdTrnd is 0.  \\

\textbf{For a thin multipole:} \\
\textbf{4th line:}  
DsX, DsY, PdTsys+ PdTrms*PdTrnd.\\

\textbf{DsX:} horizontal displacement error of the element. \\
\textbf{DsY:} vertical displacement error of the element.\\
\textbf{PdTsys + pdTrm*PdTrnd:} 
The sum of the systematic field components and random multipole field 
components, field components of the same order are added.\\
\textbf{PdTsys:} systematic designed rotation angle 
        defined in the lattice.[degree].\\
\textbf{PdTrms*PdTrnd:} random rotation errors of the element multiplied
        by a scale factor PdTrnd. The default value of 
        PdTrnd is 0.  \\

   

\textbf{5th line:}  PL, Pirho, PTx1, PTx2, PH1, PH2, Pgap \\

\begin{tabular}{l p{10cm}}
PL: & length of the element [m]. \\
Pirho: & curvature of the radius of the dipole,1/rho [1/m]. Pirho 
       denotes the 
       bending angle of the dipole, since Pirho = $\frac{\theta}{180}*\pi/L$\\
PTx1: & entrance angle of the dipole, [degree].\\
PTx2: & exit angle of the dipole, [degree].\\
PH1: & bending curvature of the entrance pole face of dipole, [degree].\\
PH2: & bending curvature of the exit pole face of dipole, [degree].\\
Pgap: & full dipole gap, [m].   \\
\end{tabular}

The definitions of PTx1, PTx2, PH1, PH2, Pgap can be found on P116 SAC-75.

\textbf{6th line:}
nmpole, n\_design \\

\begin{tabular}{l p{10cm}}
nmpole: & multipole field order of the element. The value is 0 for dipole. \\
n\_design:& design order of the multipole field of the element. \\
\end{tabular}

The value of n\_design is: \\
\begin{tabular}{l l}
0: & All \\
1: & dipole (n = 1).\\
2: & quadrupole (n = 2).\\
3: & sextupole (n = 3).\\
4: & octupole (n = 4).\\
5: & decuple (n = 5). \\
6: & dodecapule (n = 6).\\
\end{tabular}

\textbf{
7th line and then:}
i, HOMmax+i,  HOMmax-i \\

\begin{tabular}{l l }
i: & multipole field order of the element. \\
HOMmax+i: & normal multipole field components, normalized by $B\rho$.\\
HOMmax-i: & skew multipole field components, normalized by $B\rho$.\\
\end{tabular}
\textbf{Notes}:\\
\begin{itemize}
\item For a dipole element, there is no multipole field components.
      This is due to the kick map from the expanded Hamiltonian,
      the vector component of the dipole is treated separated from
      other multipoles, and the contribution of the dipoles are 
      included in the curvature of radius of the dipole $1/rho$. 

\item The non-zero multipole field components will be printed from 1-th order to
      the maximum order Porder. 
\end{itemize}


\textit{For example:} \\

\begin{tabular}{ l l l l l l l}
bend1       &      17  &  1 &  15 & & & \\
     1 &  4 &  4 & & & &\\
  0.0000e+00 &  0.0000e+00 & 0.0000e+00 & 0.0000e+00 & & & \\
  0.0000e+00 &  0.0000e+00 & 0.0000e+00 &  0.0000e+00 & & & \\
  2.7645e-01 & 2.8409e+00 &  0.0000e+00 &  0.0000e+00 & 0.0000e+00 &  0.0000e+00 & 0.0000e+00 \\
    0 & 1 & & & & & \\
     &  & & &  & & \\
\end{tabular}


\begin{tabular}{ l l l l l l l}
sx1         &      22  &  1 &  13 \\
   1  &  4 &   4 & \\
  0.0000e+00 & 0.0000e+00 & 0.0000e+00 &  0.0000e+00& & &  \\
  0.0000e+00 & 0.0000e+00 & 0.0000e+00 & 0.0000e+00& & & \\
  9.9999e-07 & 0.0000e+00 & 0.0000e+00 & 0.0000e+00 & 0.0000e+00 &   0.0000e+00 & 0.0000e+00 \\
   1 & 3 & & & & & \\
   3 & -8.9672e+06&  0.0000e+00& & & & \\
\end{tabular}

\end{flushleft}

\begin{flushleft}
\textbf{Cavity} \\
 RF cavity.
\end{flushleft}


\textbf{1st line:}
Name; familylist number;  kid number; index number in the 
lattice, for example, ``1'' means the first element; \\

\textbf{2nd line:} type; method, N   \\

\textbf{type:} type of the lattice element defined in Tracy:  \\
 cavity          2

\textbf{method:} symplectic integration method defined in the lattice, or 
        the default method for this element.\\

\textbf{N:}   number of pieces of the elements to be cut defined in the 
     lattice or the default value ``1''.\\

\textbf{3rd line:} 
MaxamplX0, MaxamplX1, MaxamplY0, MaxamplY1.\\

\begin{tabular}{l l}
MaxamplX0:& minimum horizontal aperture size;\\
MaxamplX1:& maximum horizontal aperture size;\\
MaxamplY0:& minimum vertical aperture size;\\
MaxamplY1:& maximum vertical aperture size;\\
 & \\
\end{tabular}

\textbf{4th line:}
Pvolt/energy, 2*pi*Pfreq/co, phase, energy. \\

\begin{tabular}{l l}
Pvolt/energy:& RF voltage normalized by beam energy [eV].  \\
2*pi*pfreq/c0:& RF frequency normalized by the speed of light. \\ 
phase:& RF phase [degree]. \\
energy:& beam energy [eV].\\
& \\
\end{tabular}

\begin{flushleft}
\textbf{marker} \\
\end{flushleft}

\textbf{1st line:}
Name; familylist number;  kid number; index number in the 
lattice, for example, ``1'' means the first element;\\

\textbf{2nd line: }
type; method, N  \\
  

type: type of the lattice element defined in Tracy:
marker   -1

\textbf{3rd line:} 
MaxamplX0, MaxamplX1, MaxamplY0, MaxamplY1.\\

\begin{tabular}{l l}
MaxamplX0:& minimum horizontal aperture size;\\
MaxamplX1:& maximum horizontal aperture size;\\
MaxamplY0:& minimum vertical aperture size;\\
MaxamplY1:& maximum vertical aperture size;\\
& \\
\end{tabular}


\textit{For example:}\\
 \begin{tabular}{l l l l}
debut     &        56 &   1 &   1\\
  -1 &  0 &  0 & \\
  0.0000e+00 & 0.0000e+00 & 0.0000e+00 & 0.0000e+00 \\
\end{tabular}

\begin{flushleft}
\textbf{wiggler}: \\
\textbf{insertion device}:
\end{flushleft}




\subsection{File of the ring closed orbit or orbit of the transfer line}
The horizontal and vertical closed orbits of the ring lattice or the orbits 
of the transfer line
at all lattice elements are be printed to the file ``cod.out''.

The user can also choose to print the orbit at the position of BPM, but 
the name of the BPM must be defined at the beginning of the ``*.prm'' file,
since both the horizontal and vertical orbits will be printed at the BPM position,
it is only needed to define a general BPM in the lattice file.

\begin{tabular}{ l l l l l l l l l l l l l l}
   i &name &s& code & betax & nux & betay & nuy & xcod & ycod & dSx & dSy & dipx & dipy\\
\end{tabular}

\begin{tabular}{l p{10cm}}
i: & lattice element index. \\
name: & name of the lattice element.\\
s: & longitudinal position of the element [m].\\
code:& code type of the element.  \\
               & drift:         0.0 \\
              & dipole:          0.5 \\
              & focusing quadrupole:  1 \\
              & defocusing quadrupole:  -1 \\
              &focusing sextupole: 1.5 \\
              & defocusing sextupole:  -1.5 \\
              & bpm:      2.0; \\
               & only when the name of the bpms are defined in 
                              the ``*.prm'' file, this value is 2.0, otherwise
                              Tracy will not find them. \\
              others:  &  0.0 \\
betax:& horizontal beta function [m].\\
nux: & horizontal tune (normalized by $2 \pi$).\\
betay:& vertical beta function [m].\\
nuy: & vertical tune (normalized by $2 \pi$).\\
xcod:& horizontal closed orbit, [mm]. \\
ycod:& vertical closed orbit, [mm].\\
dSx:& horizontal displacement error, [mm].\\
dSy:& vertical displacement error, [mm].\\
dipx:& horizontal kick angle, only valid for horizontal correctors, [mrad].\\
dipy:& vertical kick angle, only valid for vertical correctors, [mrad].\\
 & \\
\end{tabular}

\textit{For example:} \\
\begin{tabular}{l l l l l l l l l l l l l l }
\multicolumn{14}{l}{drift:} \\
2& sd5& 0.78& 0.0&  3.873&  0.033&  2.137&  0.065& -0.002&  0.000&  0.000&  0.000& -0.000&  0.000\\
\hline
\multicolumn{14}{l}{quadrupole:} \\
5& qp1& 0.93& -1.0&  4.403&  0.039&  2.035&  0.076& -0.002&  0.000&  0.000&  0.000& -0.000&  0.000\\
\hline
\multicolumn{14}{l}{dipole:} \\
10& dip& 2.16&  0.5&  0.126&  0.196&  7.446&  0.148&  0.001&  0.000&  0.000&  0.000& -0.000&  0.000\\
\hline
\multicolumn{14}{l}{corrector:} \\
14 & ch01& 2.29&  0.0&  0.127&  0.420&  8.950&  0.150&  0.001&  0.000&  0.000&  0.000&  0.010&  0.000\\
\hline
\multicolumn{14}{l}{defocusing sextupole:} \\
19& sx3&  2.59& -1.5&  2.566&  0.523&  7.225&  0.155&  0.005&  0.000&  0.000&  0.000& -0.000&  0.000 \\
\hline
\multicolumn{14}{l}{focusing sextupole:} \\
27& sx2&  3.06&  1.5&  9.603&  0.535&  2.375&  0.176&  0.010&  0.000&  0.000&  0.000& -0.000&  0.000\\
\end{tabular}




\subsection{6-Dimensional (6D) closed orbit or 6D orbit of the transfer line}
If the BPMs are defined in the lattice, and the BPM names are defined 
in the user input file ``*.prm'' using the command:
\tracycommand{bpm\_names}{BPMx}

then Tracy will print out the 6D closed orbit of the ring or the 6D orbit 
of the transfer line at the locations of the BPMs to a file ``6Dcod.out''.
The printed parameters are: 

i     name  s     x   px    y   py   delta ct

\begin{description}
\item[i]: index of the lattice element.
\item[name]: name of the lattice element.
\item[s]: longitudinal position of the element, [m].
\item[x]: horizontal orbit at the end of the element, [mm].
\item[px]: derivative of the horizontal orbit $x$ with respective to $s$ at the end of the element.
\item[y]: vertical orbit at the end of the element, [mm].
\item[py]: derivative of the vertical orbit $y$ with respective to $s$ at the end of the element.
\item[delta]: energy spread.
\item[ct]: longitudinal displacement with respective to the reference particle.
\end{description}

\textit{For example:}\\ 
\begin{tabular}{l l l l l l l l l}
 3&     bpmx&  7.75e-01& -2.09e-03&  1.53e-03&  0.00e+00&  0.00e+00&  0.00e+00&  9.16e-13 \\
\end{tabular}


\section{Lattice file}
In the lattice, RF cavity with the correct harmonic number must be defined!!! 
Otherwise Tracy will give the error message:
\textcolor{red}{Elem\_GetPos: there are no kids in family 0 ()}. This obigatory is for the 
correct calculation of positive/negtive momentum compaction factor.
To deactive the RF cavity, the cavity voltage can be defined as 0.


The followings are the rules to define a lattice file used in Tracy 3. The curvelinear coordinates are
used. \textbf{The ideal particle or design particle sees the perfect magnetic field in all magnets, and its}
\textbf{orbit is used as the reference orbit and base of the curvilinear coordinate}. Since the reference orbit
is a curve inside the dipoles and a straight line in other lattice elements (drifts and the magnets except
dipoles), so the length of the dipole is the the path length of the reference particle inside the dipole
which is equal to $\rho*\theta$ where $\rho$ is the bending radius of the dipole and $theta$ is the bending angle
with unit [rad], and all the other magnet lengths are the straight length of the magnets.

Due to the same reason, the curvature of the curvilinear cooridnates h = 1/$\rho$ is not zero only inside dipole;
in other magnets and drift h = 0, and the curvilinear coordinates goes to cartesian cooridnates.
As a result, the independent variable $s$ inside the dipole harmitonian is the arc length, while the staight 
length in other lattice elements.

\subsection{Lattice}
The $n^{th}$ field component of the lattice element is defined as in Tracy (n = 1, 2, 3, 4 ...):
\begin{eqnarray*}
b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0} \\
a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0} \\
B \rho & = & \frac{p_0}{e}
\end{eqnarray*}
$B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, $e$ is the electric charge.
For example, for sextupole,  n = 3, so $b_3$ and $a_3$ are defined as 
\begin{eqnarray*}
b_3 & = & \frac{1}{B \rho} \frac{1}{2} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0} \\
a_3 & = & \frac{1}{B \rho} \frac{1}{2} \frac{\partial^{2} B_x }{\partial x ^{2}}|_{x=0,y=0} 
\end{eqnarray*}.

 \notespace{NOTES:} 
In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the definition of are the same as in \textbf{Tracy}. 
While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the order of the field compoent start from 0, that is
n = 0, 1, 2, 3, ..., and the $n^{th}$ field strength components of the lattice element $b_n$ and $a_n$ are defined as
\begin{eqnarray*}
b_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_y }{\partial x ^{n}}|_{x=0,y=0} \\
a_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_x }{\partial x ^{n}}|_{x=0,y=0} \\
B \rho & = & \frac{p_0}{e}
\end{eqnarray*}
For example, for sextupole,  n = 3, its field component $b_2$ and $a_2$ are defined as 
\begin{eqnarray*}
b_2 & = & \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0} \\
a_2 & = & \frac{1}{B \rho} \frac{\partial^{2} B_x }{\partial x ^{2}}|_{x=0,y=0} 
\end{eqnarray*}.


                                
\subsection{Syntax}
Every line embraced by “{}” is comment line. For example:

          {*****drift space *****} 

Each sentence is ended by ‘;’ or no punctuation. 
Tracy is not sensitive to capital/small letters in the lattice.
User can define any lattice element with any valid name (but must start with a character) they want, but the element type is fixed. 
For 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.

\subsection{Variables}
  User can define variables in the lattice file. For example:
\begin{tightcenter}
                   \textsf{Intmeth = 4};
\end{tightcenter}
Then when the code is running,  the variable \textsf{intmeth} in the lattice 
file will be replaced by \textsf{4}.

Tracy accept math operation. For example, 
\latticedef{DL1: }{drift,}{L = 0.1*2 + 0.1-0.01;}

\subsection{Start line}
  The lattice file must begin with the sentence: 
\begin{tightcenter}
                \textsf{define} \quad    \textsf{lattice};
\end{tightcenter}
This definition is mandatory.

\subsection{Global variables}
 After define the ring, user needs to define the system parameters of the lattice:
\begin{tabular}{l p{10cm}}
\textbf{RingType = 1/0;} & define the machine type: ring or transfer line. 1 defines the ring, 0 defines the transfer line. This variable definition is optional, the default machine type is ring. \\
\textbf{Energy = ;} & the beam energy with unit [GeV]. This variable definition is 
mandatory. \\
\textbf{dP = ;} & the relative momentum offset of the particle. This variable defintion is mandatory. \\
\textbf{CODeps = ;} & the convergence for the algorism to find the closed orbit. This variable definition is mandatory. \\
\end{tabular}

\vspace{0.05in} 
\begin{flushleft}
\textit{Example:} \\
\end{flushleft}
\begin{tabular}{r c l}
      Energy &= & 2.739; \\
      dP    & = & 1.0d-10; \\
     CODeps & = & 1.0d-15; \\
\end{tabular}

\subsection{DRIFT}

                  \latticedef{Name:}{drift,}{L = $\langle \dots \rangle$;}

\begin{table}[htbp]
\centering
\caption{Parameters of dipole in the lattice file.}
\label{tab:dipole-para}
%\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth} |p{0.1\linewidth} | p{0.6\linewidth} |}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
\hline
\textbf{L}  & [m]     & 0.0 & Length.  \\ 
\hline
\end{tabular}
\end{table}
The definition of the length of a drift is mandatory.

\vspace{0.05in} 
\textit{Example:}
                      \latticedef{SD1a:}{drift,}{L= 0.900000;}

\subsection{DIPOLE}

\latticedef{Element\_name:}{bending,}{L = $\langle \dots \rangle$, T = $\langle \dots \rangle$,
T1 = $\langle \dots \rangle$, T2=$\langle \dots \rangle$, 
H1 = $\lbrack \dots \rbrack$, H2= $\lbrack \dots \rbrack$,
gap = $\lbrack \dots \rbrack$, edge\_effect1 = $\lbrack \dots \rbrack$,  
edge\_effect2 = $\lbrack \dots \rbrack$, K =$\lbrack \dots \rbrack$, 
method = $\langle \dots \rangle$, N = $\langle \dots \rangle$;}
 


 \begin{table}[tbp]
 \centering
 \caption{Parameters of dipole in the lattice file.}
 \label{tab:dipole-para}
%% \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|l|c|c|p{0.4\linewidth}|}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
 \hline
 \textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
 \hline
 \textbf{L}       & [m] & 0.0             &  Curved path length of 
  the design particle inside the dipole. L = $\rho * \theta$, where $\rho$ is the 
  bending radius of the dipole, and $\theta$ is the bending angle of the dipole.   \\
  \hline
 \textbf{T}     &[degree] & 0.0          & Total bending angle                      \\
 \hline
 \textbf{T1}    &[degree] & 0.0 & Entrance angle                            \\
  \hline
\textbf{T2}    &[degree] & 0.0 & Exit Angle \\
\hline
\textbf{K}     &   L $\neq$ 0, m$^{-2}$. \newline  L = 0, m$^{-1}$. & 0.0 
               & L $\neq$ 0, quadrupole field strength; \newline L = 0, integrated field strength. \\
\hline                                             
\textbf{Method}  & - & 4 &   1,2,4. Symplectic integration method. The 
            value ``1'' means $1^{\mathrm{st}}$ order, ``2'' means $2^{\mathrm{nd}}$ order, 
           and ``4'' means $4^{\mathrm{th}}$ order.    \\ 
\hline
\textbf{Gap}    &[m] & 0.0 &   Distance between two poles of the dipole, 
            the gap size determine the fringe field. If the gap size is 0, then the dipole has 
            no fringe field (\textcolor{red}{??????}).   \\ 
\hline
\textbf{edge\_effect1} & - & 0 & 1/0.
                ``1'' to turn on the edge focusing effect and the fringe field at the entrance of 
                  the dipole. ``0'' to turn off the two effects. \\
\hline
 \textbf{edge\_effect2} & - & 0 & 1/0. ``1'' to turn on the edge focusing effect and the 
  fringe field at the exit of the dipole. ``0'' to turn off the two effects. \\
\hline 
\textbf{N}      & - & 1 &  number of cut slices. \\
 \hline
 \end{tabular}
 \end{table}

\vspace{0.05in} 
\textit{Example}:\\
\vspace{0.05in}
\textsf{beta\_gap=37e-3; tracy\_gap=beta\_gap*2*0.724;}
\latticedef{BEND1 :}{ bending,}{L = 1.05243, T = 11.25, T1 = 5.5906, 
T2 = 5.67658, K = 0.00204, gap=tracy\_gap, 
edge\_effect1 = 1, edge\_effect2 = 1, N = 4, 
method = intmeth;}


 \begin{figure}
\includegraphics[width=0.8\linewidth]{bend_curve}
\caption{Field boundaries of the dipoles. $T1$
                is the entrance angle; $T2$ is the exit angle; $H1$ is 
                the radius of curvature of the entrance pole face; $H2$ is
                for the exit pole face; $\rho$ is the local radius of the 
                design 
                orbit in the dipole.}
\label{fig:bend_curve}
\end{figure}


\vspace{0.05in}
\textbf{Attention:}
\begin{itemize}
\item 
The bending magnet in Tracy is a symplectic element.
The independent variable $s$ inside the dipole harmitonian is the arc length,
so the length of the dipole is defined the curved path length of the design
particle inside the dipole.
\item 
One can refer to the definition of $T1$,$T2$, $H1$, $H2$ on page 116 of SLAC-75 for more 
information.
\item
In the lattice files of ELEGANT, MADX and BETA, the dipole angles are defined with the unit [rad]. 
But in TRACY, the unit is [degree].
\item
BETA dipole gap is the Elegant gap; but Tracy dipole gap is different from 
the definition in both BETA and Elegant. 
Tracy definition of dipole with fringe field: \\
\textsf{
beta\_gap=0.04;
{tracy\_gap=beta\_gap*2*1/6;}
{Due to the Tanh-like fringe field, K1=0.2, and tracy\_gap = beta\_gap *2* FINT (K brown para.)}
tracy\_gap = beta\_gap*2*0.348;}

\begin{tabular}{l l l l l l l}
 DIP: & bending, & L=0.27646, &T= 45,& T1=0,& T2=0, gap=tracy\_gap, \\
& edge\_effect1=1, &edge\_effect2=1,&method=intmeth,& N=4; & &  \\
& & & & & & \\
\end{tabular} 

\textbf{Elegant} definition of dipole with dipole fringe field: \\
\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;}
\end{itemize}

\subsection{QUADRUPOLE}
\textbf{Definition:} \\
\latticedef{Element\_Name:}{ quadrupole,}{ L = $\lbrack \dots \rbrack$, tilt = $\lbrack \dots \rbrack$, 
                            K =$\lbrack \dots \rbrack$, FF1 =  $\lbrack \dots \rbrack$,       
                            FF2= $\lbrack \dots \rbrack$, FFscaling =  $\lbrack \dots \rbrack$, 
                            method = $\lbrack \dots \rbrack$, N= $\langle \dots \rangle$;}

\begin{table}[htbp]
\centering
\caption{Parameters of quadrupoles in the lattice file.}
\label{tab:quad-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description}    \\
\hline
         L & [m] &  0.0 & Length of the quadrupole \\
\hline
        Tilt & [degree] & 0.0  & tilt angle of the quadrupole. 
                                 If ‘tilt’ is non-zero, then the 
                                 quadrupole is a skew quadruple. \\
\hline
       K &  L $\neq$ 0, [m$^{-2}$]. \newline L = 0, [m$^{-1}$]. & 0.0 &  L $\neq$ 0, Gradient 
$\frac{\frac{\partial B_y }{\partial x}}{B \rho}$; \newline  L = 0, integrated field strength 
$\frac{\frac{\partial B_y }{\partial x} L }{B \rho}$. \\
  \hline                  
   FF1 & - & 0  & 1 or 0. \newline 
                   1: to avtive fringe field at the left edge. \textsf{QuadFringeOnFlag}
   should be set in the Tracy input file. 0: left fringe field off. \\
\hline
   FF2 & - & 0  & 1 or 0. \newline 
                   1: to avtive fringe field at the right edge. \textsf{QuadFringeOnFlag}
   should be set in the Tracy input file. 0: right fringe field off. \\
\hline
FFscaling & - & 1 & Scaling factor of the dipole fringe field. \\
\hline
Method & - & 4 & 1,2,4. Order of symplectic integration method.  
Value ``1'' means 1st order, ``2'' means 2nd order, and ``4'' means 4th order. \\
\hline
N & - & 1 & Pieces of the quadrupole to be cut when it is treated in the code. \\
\hline
\end{tabular}
\end{table}



Example: \\

\textsf{Nq=8/2; dgsurg=1.00; dgsurgL=1.00; quadfringe=1.0; LQC=0.3602;}
\latticedef{QP1a:}{quadrupole,}{ L=LQC/2, K= -1.073038*dgsurg, FF1=quadfringe, FF2=0, 
              FFscaling =1, method=intmeth, N=Nq;}

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. 

\subsection{SKEW QUADRUPOLE}

The skew quadrupole is a quadrupole with a 45 [degree] tilt angle. For example:
\latticedef{QT:}{quadrupole,}{tilt=45.0, K= 0.0, method=intmeth, N=1;}

\notespace{NOTES:} 
If skew quadrupoles are defined in the lattice file with a name \tracypara{skewquad},
User must specify the name of  skew quadrupole in the tracy input file using
the commands:
\tracycommand{qt}{skewquad}  

\subsection{SEXTUPOLE}

\latticedef{Element\_Name:}{sextupole,}{L = $\lbrack \dots \rbrack$, K = $\lbrack \dots \rbrack$,
 FF1 = $\lbrack \dots \rbrack$, FF2=$\lbrack \dots \rbrack$,method = $\lbrack \dots \rbrack$, 
 N=$\lbrack \dots \rbrack$;}


 \begin{table}[htpb]
 \centering
 \caption{Parameters of sextupoles in the lattice file.}
 \label{tab:sext-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\hline
\textbf{L}        [m] &   & 0.0 & Length\\
\hline
\textbf{K}         &L $\neq$ 0, [m$^{-3}$]. \newline L = 0, [m$^{-2}$]. & 0.0 &
                   If L $\neq$ 0, 
                   $K  = \frac{1}{2} \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0}$,   
                     $B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, 
                     $e$ is the electric charge. If L = 0, K is the integrated field 
             strength $L\frac{1}{2} \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0}$ \\    
\hline
 \textbf{FF1}      & - & 0 & \textbf{1} or \textbf{0}. \textbf{1}: tringe on the fringe field at the 
                      left edge. \textbf{0}: tringe off the fringe field at the     
                      left edge.\\
 \hline
 \textbf{FF2}      & - & 0 & \textbf{1} or \textbf{0}. \textbf{1}: tringe on the fringe field at the 
                      right edge. \textbf{0}: tringe off the fringe field at the     
                      right edge.\\
 \hline
 \textbf{Method}   & - & 4 & \textbf{1},\textbf{2},\textbf{4}. Order of symplectic integration method.       
                      \textbf{1}: 1st order; \textbf{2}: 2nd order; \textbf{4} 4th order. \\
 \hline
 \textbf{N}       & - & 1 &  Pieces of this element to be cut, used in the symplectic   
                      integration. \\

 \hline
 \end{tabular}
 \end{table}



\textit{Example:} \\
\textsf{NqSx=1; coef=1.0/0.16; method4sextu = 4; sextfringe = 0;} 
\latticedef{SX1:}{sextupole,}{ L=0.16, K =  1.719190*coef, method=method4sextu, N = NqSx, 
                              FF1=sextfringe, FF2=sextfringe;}

The parameters of “sextupole” are optional, the default value for “method” is 4, 
the default value for the other parameters is 0. 


\notespace{NOTES:} 

In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the european notation of 
the order of magnetic field is used. That is n = 1, 2, 3, ...n; and the definition of 
K are the same as in \textbf{Tracy}. 
While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the U.S. notation of the 
order order of the field is used, that is n = 0, 1, 2, 3, ..n. For sextupole,  n = 2, 
and its gradient is defined as 
\begin{equation*}
K_2  =  \frac{1}{B \rho} \frac{\partial^{2} B_y }{\partial x ^{2}}|_{x=0,y=0} 
\end{equation*}

\subsection{MULTIPOLE}

\latticedef{Element\_Name:}{Multipole,}{L= $\lbrack \dots \rbrack$, T =$\lbrack \dots \rbrack$, 
               T1=$\lbrack \dots \rbrack$, T2=$\lbrack \dots \rbrack$, 
tilt=$\lbrack \dots \rbrack$, HOM = (i, $\langle$ $b_i$ $\rangle$, $\langle$ $a_i$ $\rangle$, 
j, $\langle$ $b_j$ $\rangle$, $\langle$ $a_j$ $\rangle$,
.$n$, $\langle$ $b_n$ $\rangle$, $\langle$ 
$a_n$ $\rangle$), $N$ =$\lbrack \dots \rbrack$$\langle$, method =$\lbrack \dots \rbrack$;}

\begin{table}[htpb]
\centering
\caption{Parameters of the multipoles.}
\label{tab:mult-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\hline
\textbf{L}         & [m] & 0.0 & Length \\
\hline
\textbf{T}         & [degree] & 0.0  & Total bending angle \\
\hline
\textbf{T1}        & [degree] & 0.0 & Entrance angle \\
\hline
\textbf{T2}        & [degree] & 0.0 & Exit Angle \\
\hline
\textbf{Tilt}      & [degree] & 0.0 & Rotation angle of the quadrupole; if \tracypara{Tilt}
                     is non-zero, then the quadrupole is a skew quadruple.???? \\
\hline
\textbf{HOM}       & - & (0, 0, 0) & Multipole field components of the element. The format 
                     is \textit{n}, \textit{$b_{n}$}, \textit{$a_n$}, etc. \newline 
                     \textit{n} is order of the multipole 
                     field in U.S. notation (?????), n=1 (dipole field), 
                     n=2 (quadrupole field), n=3 (sextupole field),
                     n=4 (octuple field), n=5 (decuple field).
                     \textit{$b_n$} is $n^{\mathrm{th}}$ component of the upright multipole 
                     field with the unit [$\frac{1}{m^{-n}}$];
                     \textit{$a_n$} is $n^{\mathrm{th}}$ component 
                      of the skew multipole field with the 
                      unit [$\frac{1}{m^-n}$]. \\
\hline
\textbf{N}         & - & 1 & Pieces of this element to be cut \\
\hline
\textbf{Method}    & - & 4 & 1,2,4. Symplectic integration method.
                      1 is $1^{\mathrm{st}}$ order, 2 is $2^{\mathrm{nd}}$ order, 4 is 
                      $4\mathrm{th}$ order. \\
\hline
\end{tabular}
\end{table}

The multipole field components $a_n$ and $b_n$ are defined as
\begin{eqnarray}    
\begin{aligned}
b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0} \\
a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0} \\
B \rho & = & \frac{p_0}{e}
\end{aligned}
\end{eqnarray}
$B \rho$ is the magnetic rigidity, $p_0$ is the design beam momentum, $e$ is the electric charge.

If the magnetic field $\vec{B^{tip}}$ is measured at the location with the radius $r_0$, then 
$b_n$ and $a_n$ are defined as
\begin{eqnarray*}
b_n & = & \frac{1}{B \rho} \frac{B_y^{tip}}{r_0^{n-1}}\\
a_n & = & \frac{1}{B \rho} \frac{B_x^{tip}}{r_0^{n-1}} \\
\vec{B^{tip}} & = & B_y^{tip} \hat{y} +  B_x^{tip} \hat{x}  
\end{eqnarray*}

 The $n^{th}$ order magnetic field is 
 \begin{equation}
 B_y^n + i * B_x^n = (b_n + i*a_n) * (x + i*y)^n
 \end{equation}
 The total magnetic field with $1^{st}$ to $n^{th}$ order field components can be calculated using  
 \begin{equation}
\label{eqn:total:field}
\begin{aligned}
 B_y + i * B_x &= (b_n + i*a_n) * (x+i*y)*(x + i*y)^{n-1} + O(n-1) \\
               &=  [(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) \\
              +&... 
\end{aligned}
 \end{equation}




The eqn.~\ref{eqn:total:field} is used in Tracy3 to calculate the effective fields of the
magnet. This equation clearly shows that, all the field errors gives the same effect the 
beam: horizontal focusing and vertical decusing. But since the field strength of the 
$n^{th}$ order magnet is proportial to the $n^{th}$ order of $x/y$ and $x/y$ at the 
entrance of the magnet is small, so the higher $n$ is, the weak of the $n^{th}$ order 
multipole field is.

\vspace{0.05in}
\textit{Example 1: }

\latticedef{B:}{multipole,}{L=0.70, T=10.0, T1=5.0, T2=5.0, HOM = (1, -1.0, 0), N=8, Method=2;}

In this example, the multipole is a dipole with field component  $b_1$ = -1.0, or the 
field strength is $B_{y0}$, and the field direction is down. This field gives a horizontal 
focusing to the electron.

\vspace{0.05in}
\textit{Example 2:} 

 \latticedef{QF:}{multipole,}{L=0.70, HOM = (1, 2.50, 0.0, 4, 1.01e7, 0.0), N=8, Method=4;}

In this example, the multipole is a dipole with $4^{th}$ order upright multipole filed errors (octupole),
and $b_4$ = 1.01e7.  

To add multipole errors in the defined lattice files, user can also define the multipoles
inside an external file (Section~\ref{sec:mult:field:error}) (???? To be checked, can this 
routine mesured with the general one???).

 \notespace{NOTES:} \\
In \textbf{AT} (Accelerator Toolbox) and \textbf{BETA} code, the definition of are the same
as in \textbf{Tracy}. While In \textbf{MAD8}, \textbf{MADX} and \textbf{ELEGANT}, the order 
of the field compoent start from 0, that is n = 0, 1, 2, 3, ..., and the $n^{th}$ field 
strength components of the lattice element $b_n$ and $a_n$ are defined as
\begin{eqnarray*}
b_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_y }{\partial x ^{n}}|_{x=0,y=0} \\
a_n & = & \frac{1}{B \rho} \frac{\partial^{n} B_x }{\partial x ^{n}}|_{x=0,y=0} \\
B \rho & = & \frac{p_0}{e}
\end{eqnarray*}

\subsection{SOLENOID (to be updated)}

\subsection{WIGGLER (To be updated.)}

\latticedef{Element\_Name:}{Wiggler,}{L  = $\langle$ length $\rangle$,BoBrhoV = $\langle$ B/Brho $\rangle$,
BoBrhoH = $\langle$ B/Brho $\rangle$, Lambda  = $\langle$ period $\rangle$,kxV= $\langle$ [m] $\rangle$,kxH     = $\langle$ [m] $\rangle$,phi     = $\langle$ phase $\rangle$,
               harm(n, kxV, BoBrhoV, kxH, BoBrhoH, phi), N = $\langle$ no of integration steps $\rangle$,
               Method  = $\langle$ method $\rangle$;}


\begin{table}[htbp]
\centering
\caption{The parameters of wigglers in a lattice file.}
\label{tab:wiggler-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\textbf{L} & [m] & 0.0 & Length \\ \hline
\textbf{BoBrhoV} & ??? & ??? & the normalized vertical field \\ \hline
\textbf{BoBrhoH} & ??? & ??? &  the normalized horizontal field \\ \hline
\textbf{Labmda} & [m] & ??? & period length  \\ \hline
\textbf{kxV} & [m] & ??? & ??? \\ \hline
\textbf{kxH} & [m] & ??? & ??? \\ \hline
\textbf{phi} & [degree] & ??? & ??? \\ \hline
\textbf{harm} & ??? & ??? & ??? \\ \hline
\textbf{N} & - & - & No of integration steps \\ \hline
\textbf{Method} & - & - &  Symplectic integration method.
1 is 1st order, 2 is 2nd order, 4 is 4th order.\\
\hline
\end{tabular}
\end{table}

\vspace{0.05in}
\textit{ Example 1:}
\latticedef{U143:}{wiggler,}{L=4.80, K=0.5, Lambda=0.15, N=20, Method=0;}

\vspace{0.05in}    
\textit{Example 2:}
\latticedef{EPU:}{wiggler,}{L=4.80, Lambda=0.15, N=20, Method=0,
                                 harm=(3, kxV\_3, BoBrhoV\_3, kxH\_3, BoBrhoH\_3, phi\_3);}

\subsection{FIELD MAP (To be updated

..)}

\latticedef{Element\_Name:}{Fieldmap,}{L = $\langle$ length [m] $\rangle$, N = $\langle$ 
            no of integration steps $\rangle$, file1 = $\langle$ file name (lower case) $\rangle$};

\begin{table}[htbp]
\centering
\caption{Parameters of field map in the lattice file.}
\label{tab:fieldmap-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\hline
\textbf{L} & [m] & 0.0 & Length \\ \hline
\textbf{L} & [m] & 0.0 & Length of the field map \\ 
\hline
\textbf{N} & - & ??? & the number of integration steps \\
\hline
\textbf{file1} & - & ??? & field map file \\
\hline
\end{tabular}
\end{table}

\vspace{0.05in}
\textit{Example:}
\latticedef{FM:}{Fieldmap,}{L = 1.0, N = 20, file1 = "U19\_Bxyz.dat";}


\subsection{INSERTION DEVICE (to be updated)}

\latticedef{Element\_Name:}{insertion,}{scaling1 = 1/0, scaling2=1/0,method = interpolation\_method, 
         N=Number of slice, file1 = name of the file with 1st order radia map,  
         file2 = name of the file with 2nd order radia map;}

\begin{table}[htbp]
\centering
\caption{Parameters of the insertion devices.}
\label{tab:insertiondevice-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\textbf{scaling1} & - & ??? &  scaling factor for the 1st order field map \\
\hline
\textbf{scaling2} & - & ??? &  scaling factor for the 2rd order field map \\
\hline
\textbf{method} & - & ??? & 1, 3. The order of symplectic interpolation method. 1 is linear 
  interpolation, 3 is spline interpolation.\\
\hline
\textbf{N} & - & ??? & pieces of this element is cut when it is treated in the code \\
\hline
\textbf{file1} & - & ??? & The 1st order of insertion device field are read from the 
files generated by RADIA. 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. \\
\hline
\textbf{file2} & - & ??? & 
The 2nd order of insertion device field are read from the files generated by RADIA.
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. \\
\hline
\end{tabular}
\end{table}

\vspace{0.05in}
\textit{Example:}
 \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";}
     
 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.

\subsection{RF CAVITY}

\latticedef{Element\_Name}{cavity,}{Frequency = RF frequency, Voltage = RF voltage, Phase = synchrotron  
                           Phase, harnum = harmonic number of the RF cavity;}


\begin{table}[htbp]
\centering
\caption{Parameters of RF cacity.}
\label{tab:RFCavity-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.2\linewidth} | p{0.1\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\hline
\textbf{frequency} & [Hz] & ??? &  RF frequency  \\
\hline
\textbf{voltage} & [Volt] & ??? &  RF voltage  \\
\hline
\textbf{phase} & [degree] & ??? & synchrotron phase \\
\hline
\textbf{harnum} & - & ??? & harmonic number \\
\hline
\end{tabular}
\end{table}


\vspace{0.05in}
\textit{Example:}
\latticedef{CAV:}{Cavity,}{Frequency = 499.95e6, Voltage=1.22e6, phase = 30, harnum=328;}

To calculate the stable phase for the lattice with positive or negative 
momentum compaction factor, the definition of the harmonic number of the 
RF cavity is mandatory. The other parameters of RF cavity are 
optional, and their default values are 0. 

\subsection{CORRECTOR}

\latticedef{Element\_Name:}{corrector,}{horizontal/vertical, L = , kick = , roll = , 
           N = , method = integrated method;}

\begin{table}[htbp]
\centering
\caption{Parameters of correctors.}
\label{tab:corrector-para}
\begin{tabular}{| p{0.2\linewidth} | p{0.1\linewidth} | p{0.2\linewidth} | p{0.4\linewidth} |}
\hline
\textbf{Parameter Name}    &  \textbf{Units}      &\textbf{Default}   & \textbf{Description} \\
\hline
\textbf{Horizontal / vertical} & - & horizontal & “horizontal”: horizontal corrector; “vertical”: vertical 
 corrector \\
\hline
\textbf{L}  & [m] & 0.0 & length of the corrector \\
\hline
\textbf{kick} & [rad] & 0.0 & kick angle \\
\hline
\textbf{roll} & - & 0.0 & designed rotation angle  \\
\hline
\textbf{N} & - & 1 & cut piece of the element \\
\hline
\textbf{method} & - & 1, first order & 1, 2, 4. Order of symplectic integration method.
Value ‘1’ means 1st order, ‘2’ means 2nd order, and ‘4’ means 4th order \\
\hline
\end{tabular}
\end{table}


\vspace{0.05in}
\textit{Example 1:} 
\latticedef{CH:}{corrector,}{horizontal, method=intmeth;}
It defines a horizontal corrector.

\vspace{0.05in}
\textit{Example 2:} 
\latticedef{CV:}{corrector,}{vertical, method=intmeth;}
It defines a vertical corrector.

\notespace{NOTES:} 
\begin{itemize}
\item
The corrector type can be used as a corrector to do both orbit correction or as a 
kicker to kick the beam. 
\item
The corrector is treated as a multipole in TRACY, that is, if the length 
of the corrector \textbf{L} is non-zero, then the element is treated as a thick
multipole, if \textbf{L} is zero, then the corrector is treated as a 
thin multipole. 
\item
For a lattice with correctors, user must specify the name of  corrector in the Tracy 
input file with the commands:
           \tracycommand{h\_corr}{HCM}
                         or 
           \tracycommand{v\_corr}{VCM}
Here \tracypara{HCM} is the name of the corrector defined in the lattice for horizontal 
orbit correction (????); \tracypara{VCM} is the name of the corrector defined in the 
lattice for vertical orbit correction.
\end{itemize}


\subsection{BEAM POSITION MONITOR (To be updated)}
 BPM is a special marker in the lattice; the “symbol” name must be “BPM” (???). User can 
define the BPM as:????
\latticedef{BPM:}{type;}{}

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.

\notespace{NOTES:}
For lattice with BPMs, user must specify the name of  BPM in the Tracy input file
 with the command:
                    \latticedef{bpm\_name }{beaPosMonitor}{}
Here ``beaPosMonitor'' is the name of the BPMs defined in the lattice.

\subsection{GIRDER}
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:
                   \latticedef{Symbol:}{ type;}{}

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.
 
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.

\begin{flushleft}
\textbf{Notice:}\\ 
For lattice with girders, User must specify the name of  girder in the 
input file ``*.prm'' with the commands: \\

\begin{tabular}{l l}
gs &      Girder\_Start \\
ge &      Girder\_End \\
& \\
\end{tabular}

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.
\end{flushleft}

\subsection{MARKER}

\latticedef{Element\_Name:}{marker;}{}

\subsection{ELEMENT BLOCK}
\begin{flushleft}
  To construct the element block, use the following format: \\
           \latticedef{Symbol:}{ elem1, elem2,
., block1,block2;}{}
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.  \\

If there are $N$ the same element/block subsequently, user can use 
``$N$*element/block'' to simply the definition. \\
\textbf{For example:} \\
                        \latticedef{SINJ:}{ SD1a, ssep, 3*SEP,esep,SD1c,eHU600,SD1d;}{} 
In this example element block, there are 9 elements/blocks, and 3 elements/blocks ``SEP'' subsequently.

\subsection{LINE}
 User can define the cell structure using the command:

             \latticedef{CELL :} {$\langle$ block name $\rangle$, SYMMETRY=$\langle$ symmetry $\rangle$;}{}

\begin{tabular}{l l}
$\langle$block name $\rangle$: & the name of a block; \\
$\langle$symmetry $\rangle$: & the number of super symmetry or the number of the block in the ring. \\ 
 & \\
\end{tabular}

\textit{Example:} \\

         CELL: BL1, Symmetry = 12; \\

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
tunes and chromaticities in one symmetric period.

\end{flushleft}

\subsection{RING}
To define the ring, use the command:
               \latticedef{RING:}{ elem, block
.}
It’s similar to define an element block, but must with the fixed symbol 
name ``RING''.  \\

\textbf{For example:} \\
\latticedef{RING:}{ DEBUT,SUP1,SUP2,SUP3,SUP4,CAV,FIN;}{}

\subsection{End line}
 To end the lattice file, user needs to use the following command at the end of the lattice file:
End;
This command is mandatory.


\section{Commands}
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:
\begin{flushleft}
\begin{itemize}
\item 
If the flags are not active, then the default values for all the boolean 
commands are false.
\item
The code will execute the command according to the sequence defined in the 
input script ``*.prm''. For example, \\
\begin{tabular}{l l}
(1) & \\
\hline
FitTune4Flag & qp7a qp7b qp9a qp9b 18.18 10.28 \\
\hline
(2) & \\
ReadMultipoleFlag & \\
\hline
(3) & \\
FitTune4Flag & qp7a qp7b qp9a qp9b 18.202 10.317 \\
& \\
\end{tabular}

With the command (1), 
the code will fit tunes to the target tunes (18.18  10.28);  \\
with the command (2), the code 
then read multipole field errors into the lattice; \\
with the command (3), the code 
 then fit the tunes to a new set of values (18.202 10.317).

\item
User can define the same Boolean commands as often as they want 
in the same input script; but user can only define maximum 500 
commands in one input script.  
\item
The user defined script can be used both for both the non-parallel 
and parallel version Tracy; the output files are the same 
for both versions.
\item 
The key words in the user defined input file ``*.prm'' is 
case sensitive, that is, the key word with captical letters 
is different from the one with small letters.
\item 
The variables and lattice element names in Tracy lattice file 
are not case sensitive, user can define the variables and 
lattice elements names with small or captical letters.

\end{itemize}
\end{flushleft}

\subsection{QuadFringeOnFlag }
To activate quadrupole fringe field, use the command:
\tracycommand{QuadFringeOnFlag}{}
in the ``*.prm'' script. With this command, user can define 
the fringe field at the entrance or exit of the quadrupole together 
with the command ``FF1 = 1'' or ``FF2 = 1'' of the quadrupoles 
which are defined in the lattice file; if FF1 or FF2 not equals to 1, 
then there is no fringe field at the entrance or exit of the quadrupoles 
even if QuadFringeOnFlag is active in the ``*.prm'' file.

This flag is a global flag, if user set this flag in the input script, 
it will always have effects until this flag is reset.

\subsection{QuadFringeOffFlag }
To deactivate quadrupole fringe field, use the command:
\tracycommand{QuadFringeOffFlag}{}

With this command, user can deactivate the fringe field at the entrance 
and exit of the quadrupole, even if ``FF1 = 1'' or ``FF2 = 1'' for the 
quadrupole in the lattice file. 
  
This flag is a global flag, if user set this flag in the input script, 
it will always have effects until this flag is reset.

\subsection{RFvoltageFlag}
User can reset the RF voltage by setting ``RFvoltageFlag'' to replace 
the value of RF voltage which is defined in the lattice. For example:
\tracycommand{RFvoltageFlag}{    3000000}

Here ``RFvoltageFlag'' is the name of the keyword command, ``3000000'' is 
the value of RF voltage with the unit [volt].
  
If the ring has more than one RF cavities, the related parameters 
are defined as the total values for one RF cavity.

\subsection{PrintTrackFlag}
To print the coordinates tracked around COD at each element to a file, use the command: 
\tracycommand{PrintTrackFlag}{           track\_file        x    px   y  py  delta    ctau     nturn}

For example: 
\tracycommand{PrintTrackFlag}{           track.out         0.001     0.0    0.0    0.0    0.0    0.0     50}

The parameters and the default values of ``PrintTrackFlag'' are shown in Table \cite{tab:prnttrackflag:para}.

\begin{table}[h]
\centering
\label{tab:prnttrackflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.1\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Name &  Description & Default value & Unit \\
\hline
track\_file & File to save the tracked coordinates around each lattice element & track.out & - \\
\hline
x & Start tracking horizontal coordinate &  0.001 &  [m] \\
\hline
px & Start 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]. & 0.0 & - \\
\hline
y & Start tracking vertical coordinate &  0.0 &  [m] \\
\hline
py & Start 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]. & 0.0 & - \\
\hline
delta & Start tracking relative energy offset  & 0.0 & - \\
\hline
ctau & Start tracking longitudinal coordinate  & 0.0 & [m] \\
\hline
nturn & Number of turn for tracking & 50 & - \\
\hline
\end{tabular*}
\caption{Parameters of command ``PrintTrackFlag''.}
\end{table}



\subsection{PrintTrackElemFlag}
To print the coordinates tracked (NOT around COD) at a certain element to a file, use the command: 
\tracycommand{PrintTrackFlag}{track\_file        x    px   y  py  delta    ctau     nelem1 nelem2}

For example: 
\tracycommand{PrintTrackFlag}{track.out         0.001     0.0    0.0    0.0    0.0    0.0     50 1 2}

The parameters and the default values of ``PrintTrackElemFlag'' are shown in Table \cite{tab:printtrackelemflag:para}.

\begin{table}[h]
\centering
\label{tab:printtrackelemflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.1\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Name & Description & Default value & Unit \\
\hline
track\_file & File to save the tracked coordinates around 
each lattice element. & track.out & - \\
\hline
x & Start tracking horizontal coordinate & 0.001 & [m] \\
\hline
px & Start 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]. &
      0.0 & - \\
y & Start tracking vertical coordinate & 0.0 & [m] \\
\hline
py & Start 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]. & 
      0.0 & - \\
\hline
delta & Start tracking relative energy offset  & 0.0 & - \\
\hline
ctau &Start tracking longitudinal coordinate  &0.0 & [m] \\
nelem1 &index of start lattice element for tracking & - & - \\
\hline
nelem2 & index of end lattice element for tracking & - & - \\
\hline
\end{tabular*}
\caption{Parameters of command ``PrintTrackElemFlag''.}
\end{table}



\subsection{PrintTwissFlag}

Print Twiss parameters to a user defined file \\

With the command ``PrintTwissFlag'', Tracy 3 will print the Twiss 
parameters to a user defined file. The format is:
 \tracycommand{                           PrintTwissFlag}{                user\_defined\_file}

If user use the command PrintTwissFlag but without define the file name, 
then the code will print the Twiss parameters to a default file ``twiss.out''.

\subsection{PrintCODFlag}
Print COD (Close Orbit Distortion) to a user defined file\\

With the command ``PrintCODFlag'', the code will print the close orbit 
distortion to a user defined file. The format is:
 \tracycommand{PrintCODFlag}{                user\_defined\_file}
If user use the command PrintCODFlag but without defining the file name, 
then the closed orbit will be printed to the default file ``printcod.out''.

In Tracy 3, close orbit file ``cod.out'' is automatically generated after 
reading the lattice.

See the details in seciton {}...?????????? 

\subsection{ReadChamberFlag}
Read vacuum chamber setting from an external file \\

  To read the vacuum chamber from the user defined chamber file, use the command:
\tracycommand{ReadChamberFlag}{        Chamber\_example.dat}
  In the file ``Chamber\_example.dat'', user can specify the vacuum limit at the 
different region of the lattice; the format of the chamber file is given in section {}.....?????.

\subsection{ReadfefileFlag}
Read lattice element multipole field errors from an external file \\

  To read the multipole field errors of the lattice elements from the user defined file, use the command:
\tracycommand{ReadfefileFlag}{             dip.fe}

Tracy will read the systematic and random multipole field errors of the 
lattice elements defined in the file ``dip.fe'', and then replace the 
corresponding field components of the elements with the new field errors. 
The formats to specify the systematic and random multipole field errors in 
a file are given in section Error: Reference source not found.

\subsection{ReadaefileFlag}
Read lattice element misalignment errors from a file \\

  To read the misalignment error of the lattice elements from the user defined file, use the command:
\tracycommand{ReadaefileFlag}{             dip.ae}

Tracy will read the systematic and random misalignment errors of the 
lattice elements from the file ``dip.fe'', and replace the misalignment 
errors of the corresponding components of the elements. The formats to 
define the systematic and random misalignment errors of the lattice 
elements in a file are given in section ....??????. 

\subsection{CODCorrectFlag}
\begin{flushleft}
Closed orbit (COD) correction \\

   The orbit distortion is corrected using SVD (Singular Value Decomposition)
 method in Tracy 3. In order to do orbit correction, user needs to call the command
\tracycommand{CODCorrectFlag}{}
and then specify the following parameters in the user defined ``*.prm'' file.
 
Specify the element names of horizontal, vertical correctors, and beam position 
monitors used in the orbit correction as the following examples:
\begin{tabular}{l l}
h\_corr     &  HC \\
v\_corr     &  VC \\
BPM     &   bpm \\
& \\
\end{tabular}

User also need to specify the states of the correctors to trigger 
on/off the correction using the following parameters: \\
\begin{tabular}{l l}
hcorr\_file    &    hcorr\_56nom.state \\
vcorr\_file    &    vcorr\_56nom.state \\
& \\
\end{tabular}

In the file ``hcorr\_56nom.state'', 
\begin{itemize}
\item 
a list of numbers (1 or 0) are 
given to the horizontal correctors, according to the sequence in the lattice; 
``1'' means the corresponding corrector is used for horizontal orbit correction, 
``0'' means this corrector is not used in the horizontal orbit correction. 
The definition rules of vertical corrector states in ``vcorr\_56nom.state'' are 
the same as ``vcorr\_56nom.state''.  
\item 
This parameter defines number of iterations to correct the orbit distortion, 
this value should be an integer number not smaller than 1. \\
n\_orbit       3
\item
This parameter defines number of singular values in H-plane, must be not larger than the number of correctors used for orbit correction \\
nwh           60
\item
This defines number of singular values in V-plane, must be not larger  than the number of correctors used for orbit correction \\
nwv           60
\end{itemize}

 In Tracy 3, during the closed orbit correction: 
\begin{itemize}
\item
Beam response matrices between beam position monitors and 
horizontal/vertical correctors are calculated and written to the 
files ``svdh.out''/ ``svdv.out'', respectively. The maximum number of 
horizontal/vertical correctors used for orbit correction is 250.
\item
The code corrects the closed orbit distortion.
\item 
Horizontal and vertical orbits at the locations of all beam position monitors 
during the correction are saved to the files ``horbit.out'' and 
``vorbit.out'', respectively. 
\item
 A file ``OrScanFile.out'' will be saved with the summaries of the mean 
and RMS values of the orbits before and after correction. 
\item
Finally, Twiss parameters, closed orbit distortion at the lattice elements 
are saved to a summary file ``summary\_miserr\_codcorr.out'', the format of 
this file is explained in Table ....????.
\end{itemize}

\end{flushleft}

\subsection{TuneTracFlag}

Get tunes by tracking \\

  To get tunes by tracking, use command: 
\tracycommand{TuneTracFlag}
  The tunes obtained by tracking are printed on the screen.

\subsection{ChromTracFlag}
Get chromaticities by tracking \\

  To get chromaticity by tracking, use command:
\tracycommand{ChromTracFlag}{}
  The chromaticities obtained by tracking are printed on the screen.

\subsection{AmplitudeTuneShiftFlag}

Tune shift with amplitude \\


  To calculate tune shift with amplitude, one needs to use the following command:
\tracycommand{AmplitudeTuneShiftFlag}{ nudx\_file nudz\_file nxpoint  nypoint nturn  xmax  ymax  delta}

For example:
\tracycommand{AmplitudeTuneShiftFlag}{   nudx.out  nudz.out 50  30  516  0.035  0.02  0.0}

The meanings of parameters and default values of command ``AmplitudeTuneShiftFlag'' 
are shown in Table \cite{tab:amplitudetuneshiftflag:para}. If user uses the command 
AmplitudeTuneShiftFlag without parameters, then the code will use all the default values.

\begin{table}[h]
\centering
\caption{Parameters of the command to calculate tune shift with amplitude.}
\label{tab:amplitudetuneshiftflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Parameters & Meaning & Default & units \\
\hline
nudx\_file & File to save the calculated tune shift with horizontal amplitude & nudx.out & -  \\
 \hline
 nudz\_file & File to save the calculated tune shift with vertical amplitude &  nudz.out & - \\
 \hline
 nxpoint &Number of points in horizontal direction & 31 & - \\
 \hline
 nypoint& Number of points in vertical direction & 21 & - \\
\hline
nturn& Number of turns to track tune & 516 & - \\
\hline
xmax & Maximum amplitude of x & 0.025 & [m] \\
\hline
ymax & Maximum amplitude of y & 0.005 & [m] \\
\hline
delta& Energy offset of the particle 0.0 & - \\
\hline
\end{tabular*}
\end{table}


     
\subsection{EnergyTuneShiftFlag}
Tune shift with energy \\

To calculate tune shift with energy, one needs to use the command:
\tracycommand{EnergyTuneShiftFlag}{  nudp\_file  npoint  nturn  deltamax}

For example:
\tracycommand{EnergyTuneShiftFlag}{   nudptest.out    31    1026    0.06}

The meaning of parameters and default values of this command are shown in Table \cite{tab:energytuneshiftflag:para}.
If user uses command EnergyTuneShiftFlag without parameters, then the code will use all the default values. 

\begin{table}[h]
\centering
\caption{Parameters of the command to calculate tune shift with energy.}
\label{tab:energytuneshiftflag:para}.
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
parameter & meaning & default & units \\
\hline
nudp\_file & File to save the calculated tune shift with energy &
nudp.out & - \\
\hline
npoint & Number of points & 31 & - \\
\hline
nturn & Number of turns  for tracking & 516 & - \\
\hline
deltamax & Maximum energy offset of the particle & 0.06 - \\
\hline
\end{tabular*}
\end{table}


    
\subsection{FmapFlag}
Frequency map analysis for on momentum particle. \\

Track the coordinates (x, px, y, py, delta, ctau) of the particle, 
the coordinates (x, px, y, py) are tracked around the closed orbit;
while (delta, ctau) is tracked around the zero orbit.

The grid of the particle is x= 1e-6 + xcod ~ xmax + xcod, with the 
step size xmax/nturn, 
z= 1e-6 + zcod ~ zmax + zcod, with the 
step size ymax/nturn; px = 0 + pxcod; pz = 0 + pzcod;
ctau = 0; delta = set value. 

To do frequency map analysis for the on momentum particle, use the command:
\tracycommand{FmapFlag}{   fmap\_file    nxpoint   nypoint    nturn  xmax   ymax   delta   diffusion}
or 
\tracycommand{FmapFlag}{   fmap\_file    nxpoint   nypoint    nturn  xmax   ymax   delta   diffusion printloss }

 For example:
\tracycommand{FmapFlag}{   fmap.out   31   21   516   0.025   0.005   0.0   true  }
or 
\tracycommand{FmapFlag}{   fmap.out   31   21   516   0.025   0.005   0.0   true  true}


The meaning of parameters and default values of this command are shown in Table \cite{tab:fmapdpflag:para}. 
If user uses command FmapFlag without parameters, then the code will use all the default values. 

\begin{table}[h]
\centering
\caption{Parameters of the command to do frequency map analysis for on momentum particle.}
\label{tab:fmapdpflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Parameters & meaning & Default & units \\ 
\hline
fmap\_file & File to save the calculated frequency map analysis &
fmap.out & - \\
\hline
nxpoint & Number of points in the horizontal direction &31 & - \\
\hline
nypoint &Number of points in the vertical direction & 21 & - \\
\hline
nturn&Number of turns for tracking; if ``diffusion'' is 
      true, then the tunes will calculated in the first Nturn
      and then the second Nturn, and the tune difference 
      between these two tunes is the tune diffusion. & 516 & - \\
\hline
xmax & Maximum amplitude in the horizontal direction & 0.025& [m] \\
\hline
ymax & Maximum amplitude in the vertical direction & 0.005 & [m] \\
\hline
delta &Energy offset of the particle & 0.0 & - \\
\hline
diffusion & Boolean flag, true/false; to compute tune diffusion at 
the first N turns and second N turns. & true & - \\
\hline
printloss (optional) & 
Boolean flag, true/flase; print out the last information of the tracked 
particleto and external file? If true, the output file is ``fmap\_file.loss''. & - &- \\
\hline
\end{tabular*}
\end{table}



\subsection{FmapdpFlag}
Frequency map analysis for off momentum particle \\

To do frequency map analysis for the off momentum particle, use the command:
FmapdpFlag   fmapdp\_file    nxpoint    nepoint    nturn    xmax  emax  y  diffusion
or 
FmapdpFlag   fmapdp\_file    nxpoint    nepoint    nturn    xmax  emax  y  diffusion printloss

The meaning of parameters and default values are shown in Table \cite{tab:fmapdpflag:para}.  
If user only uses the command ``FmapdpFlag'' but without defining all the parameters, 
then the code uses the default values.

\begin{table}[h]
\centering
\label{tab:fmapdpflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.45\linewidth} |p{0.15\linewidth} | p{0.1\linewidth} |}
\hline
parameters & meaning & default & units \\
\hline
fmapdp\_file & File to save the calculated frequency map analysis &
fmapdp.out & - \\
\hline
nxpoint & Number of points in the horizontal direction &31 & - \\
\hline
nepoint &Number of points for the energy & 21 & - \\
\hline
nturn &Number of turns for tracking&516&-\\
\hline
xmax &Maximum amplitude in the horizontal direction &0.025 & [m]\\
\hline
emax &Maximum energy offset of the particle&0.005 & -\\
\hline
y &Amplitude in the vertical direction& 0.0& [m] \\
\hline
diffusion & Boolean flag to compute tune diffusion & true & - \\
\hline
printloss (optional) &
Boolean flag, true/flase; print out the last information of the tracked 
particle to and external file? If true, the output file 
is ``fmapdp\_file.loss''. & - & \\
\hline
\end{tabular*}
\caption{Parameters of the command ``FmapdpFlag''.}
\end{table}



\subsection{ErrorCouplingFlag}
Add coupling by the random rotation of the full quadrupoles \\

To simulate coupling in the lattice, use can add the random rotation 
error to all the full quadrupole, using the command as the following example:
\tracycommand{ErrorCouplingFlag}{         0    0.0007}

In this example, ``0'' is the random seed number; ``0.0007'' is the RMS value 
of the rotation angles of all the quadrupoles with the unit [rad]. 
  
After setting the rotation error in the lattice, the code will generate a file 
with the file name ``flat\_file\_errcoupling\_full.dat'' at the current working 
directory, user can check the error setting of quadrupoles in this file; then 
the coupling will be calculated and Twiss parameters after adding the random 
rotation errors will be saved to the file ``linlat\_errcoupling.out''.

\subsection{ErrorCoupling2Flag}
Add coupling by random rotation of the half quadrupoles \\

In order to get the beam parameters in the middle of the quadrupoles, each 
quadrupole in the lattice can be cut into two parts. In such case, 
the coupling of the lattice can be generated by random rotation of all the 
half quadrupoles in the lattice, using the command as the following example:
\tracycommand{ErrorCoupling2Flag}{         0    0.0007}

In this example, ``0'' is the random seed number; ``0.0007'' is the RMS value 
of the rotation angle of the quadrupole with the unit [rad]. 

After setting the errors in the lattice, the code will generate a file at 
the current working directory with the file name ``flat\_file\_errcoupling\_half.dat'', 
user can check the error setting of quadrupoles in this file. After adding 
the random rotation errors, the coupling will be calculated and Twiss parameters 
will be saved to the file ``linlat\_errcoupling2.out''.

This command is dedicated for Soleil lattice in which each quadrupole 
is cut into two half quadrupoles. 

\subsection{CouplingFlag}
Calculate coupling and emittance \\

To calculate coupling and emittance, use command: 
\tracycommand{CouplingFlag}{}

After calculation, the coupling and the emittance will be printed on the 
screen, and the Twiss parameters will be automatically saved to the 
file ``linlat\_coupling.out''.

\subsection{MomentumAccFlag}
Calculate momentum acceptance by tracking \\

The following command calculate momentum acceptance at a predefined 
lattice region by tracking: 
\tracycommand{MomentumAccFlag}{   MomAccFile   TrackDim     istart    istop     deltaminp
Deltamaxp     nstepp    deltaminn    deltamaxn   nstepn   turns  zinitial}

\textit{For example:}
\tracycommand{MomentumAccFlag}{   momacc.out      4D     1   209     0.01     0.05    100       -0.01        
-0.05   100   1026   0.0001}

The meaning of parameters and default values are shown in Table \cite{tab:momentumaccflag:para}. 
If user uses MomentumAccFlag without parameters, then the code will use 
the default values.

\begin{table}[h]
\centering
\label{tab:momentumaccflag:para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
parameter & meaning & Default & units \\
\hline
MomAccFile & File to save the tracked momentum acceptance at each 
element; saved in the current directory.& momentumacceptance.out & - \\
\hline
TrackDim & 4D/6D  tracking to get the momentum acceptance & 6D & - \\
\hline
istart &Start element in the lattice for the tracking & 1 & - \\
\hline
istop &End element in the lattice for tracking &108 & - \\
\hline
nstepp &Number of steps to do tracking in the positive energy range &
100 & - \\
\hline
nstepn&Number of steps to do tracking in the negative energy range &100 & - \\
\hline
Deltaminp&Positive start energy of the tracking & 0.01 & - \\
\hline
Deltamaxp & Positive end energy of the tracking & 0.05 & - \\
\hline
Deltaminn & Negative start energy of the tracking & -0.01 & - \\
\hline
Deltamaxn & Negative end energy of the tracking & -0.05 & - \\
\hline
nturns &Number of turn & 1026 & - \\
\hline
zinitial & The initial vertical coordinate which is used to search for 
6D closed orbit. This value should be a small value. & 0.0003 &  [m] \\
\hline
\end{tabular*}
\caption{Parameters of the command to calculate momentum acceptance.}
\end{table}


          
\subsection{ReadMultipoleFlag}
Read multipole field error from a file (SOLEIL lattice) \\

 After defining the file names of multipole field errors on SOLEIL storage 
ring (see section \cite{} and \cite{}), use the command:
\tracycommand{ReadMultipoleFlag}{}
to read multipole field errors and set the corresponding values to SOLEIL 
lattice. The multipole field errors of correctors and skew quadrupoles 
are added on the thick sextupoles which are integrated at the same magnets. 
The format of multipole errors file is given in section \cite{}.

 After setting the multipole field errors in the lattice, the code will 
generate a file at the current working directory, and the file name is 
``flat\_file\_errmultipole.dat'', user can check the field components of 
the lattice elements in this file to verify the multipole field errors.

\subsection{ReadVirtualSkewquadFlag}
Read the sources of coupling from a file (SOLEIL lattice) \\

The sources of coupling on SOLEIL storage ring can be read from an external 
file.  Use the command:
\tracycommand{ReadVirtualSkewquadFlag}{} 
to read and set the field strength to the virtual skew quadrupoles. Currently 
this command only works for Soleil lattice. 

The coupling sources MUST be defined as the skew quadrupoles with the name 
``SQ'', the rules and related information are explained in section \cite{}.

\subsection{FitTuneFlag}
Fit tunes for the lattice with full quadrupole \\

Betatron tunes can be fit using two families of quadrupoles. The command is:
\tracycommand{FitTuneFlag}{      Quad1   Quad2   nux   nuz}

\textit{For example:}
\tracycommand{FitTuneFlag}{      q7 q9   18.202   10.317}

The parameters of this command are shown in Table \cite{tab:fittuneflag:paras}.

\begin{table}[h]
\centering
\label{tab:fittuneflag:paras}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Parameters & Meaning & Default & Units \\
\hline
Quad1 & Quadrupole family used to fit the tunes & - & - \\
\hline
Quad2 & Quadrupole family used to fit the tunes & - & - \\
\hline
nux & Target horizontal tune & 0.0 & - \\
\hline
nuz & Target vertical tune & 0.0 & - \\
\hline
\end{tabular*}
\caption{Parameters of the command ``FitTuneFlag''.}
\end{table}

\begin{itemize}
\item
After fitting the tunes, field strengths of the fitted quadrupoles 
before and after the fitting are printed to the screen; user can 
copy the new quadrupole field strengths to the lattice file for 
further analysis.
\item
``FitTuneFlag'' is a generic command; it works for the lattices with 
full qudrupoles.
\end{itemize}

\subsection{FitTune4Flag}
Fit tunes for the lattice with half quadrupoles \\

For the lattice with each quadrupole cut into two pieces, betatron 
tunes can be fit using two families of quadrupoles. The command is:
\tracycommand{FitTune4Flag}{      Q1a  Q1b  Q2a  Q2b  nux  nuz}

The parameters of this command are shown in Table \cite{tab:fittune4flag:paras}.

\begin{table}[h]
\centering
\label{tab:fittune4flag:paras}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Parameters & Meaning  & Default & Units \\
\hline
Q1a &First half of the quadrupole family used to fit the tunes &- & - \\
\hline
Q1b &Second half of the quadrupole family used to fit the tunes & - & - \\
\hline
Q2a &First half of the quadrupole family used to fit the tunes& - & - \\
\hline
Q2b &Second half of the quadrupole family used to fit the tunes &- & - \\
\hline
nux &Target horizontal tune&0.0 & - \\
\hline
nuz & Target vertical tune & 0.0 & - \\
\hline
\end{tabular*}
\caption{Parameters of the command ``FitTune4Flag''.}
\end{table}



\textit{For example:}
\tracycommand{FitTune4Flag}{      qp7a  qp7b   qp9a  qp9b  18.202 10.317}

In this example, all the variables have the same meaning as the ones 
in the command ``FitTuneFlag'', except ``qp7a'' and ``qp7b'' are the 
two half pieces of the full quadrupole ``qp7'', and ``qp9a'' and ``qp9b'' 
are the two half pieces of the full quadrupole ``qp9''.

\begin{itemize}
\item
 After fitting the tunes, the field strengths of fitted quadrupole 
before and after the fitting are printed to the screen; user can 
copy the new field strengths of quadrupoles to the lattice file 
for further analysis.  
\item  
``FitTune4Flag'' is a command that works for the lattices in 
which each quadrupole are cut into two halves.
\end{itemize}

\subsection{FitChromFlag}
Fit chromaticity \\

Chromaticities can be fit using two families of sextupoles, the command is:
\tracycommand{FitChromFlag}{     SX1    SX2    epsilon\_x    epsilon\_z}

The parameters of this command are shown in Table \cite{tab:fitchromflag:paras}.

\begin{table}[h]
\centering
\label{tab:fitchromflag:paras}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.15\linewidth}|p{0.5\linewidth} |p{0.1\linewidth} | p{0.1\linewidth} |}
\hline
Parameters & Meaning & Default & Unit \\
\hline
SX1 & First sextupole family used to fit the chromaticities & - & - \\
\hline
SX2 & Second sextupole family used to fit the chromaticities & - & - \\
\hline
epsilon\_x & Target horizontal chromaticity & 0.0 & - \\
\hline
epsilon\_z & Target vertical chromaticity & 0.0 & - \\
\hline
\end{tabular*}
\caption{Parameters of the command ``FitChromFlag''.}
\end{table}

\textit{For example:}
\tracycommand{FitChromFlag}{     sx9 sx10   2.0    2.6}

After fitting the chromaticites, the field strengths of fitted 
sextupoles before and after the fitting are printed to the screen; 
user can copy the new field strengths of sextupoles to the lattice 
file for further analysis.  

\subsection{TouschekFlag (TO BE UPDATED)??????}
Touschek lifetime determined by RF acceptance \\

To calculate Touschek lifetime, use the following command:
\tracycommand{TouschekFlag}{}

Here the momentum acceptance is limited by the RF acceptance.

\subsection{IBSFlag (TO BE UPDATED) ????}
Intra Beam Scattering (IBS)  \\


To calculate Intra Beam Scattering, use the command:
\tracycommand{IBSFlag}{}

\subsection{TousTrackFlag (TO BE UPDATED)}
Touschek lifetime determined by the minimum value of RF acceptance 
and momentum acceptance. \\

Touschek lifetime can be calculated by  
\tracycommand{TousTrackFlag}{}

In this case, the energy acceptance at each lattice element is 
limited by the minimum value of RF acceptance and momentum acceptance 
obtained by tracking, and the chamber file MUST be defined in 
the user script.

\subsection{PhaseSpaceFlag}
Obtain phase space by tracking \\

To calculate phase space, use the command: 
\tracycommand{PhaseSpaceFlag}{      Phase\_phase\_file      Phase\_Dim     Phase\_X      Phase\_Px
                                           Phase\_Y     Phase\_Py   Phase\_delta   Phase\_ctau                
                                           Phase\_nturn     damping\_flag}

\textit{For example:}
\tracycommand{PhaseSpaceFlag}{   phasespace.out    6D   1e-6    0.0    1e-6   0.0   0.012   0.0   1000   false}

The meanings of parameters and defaults values of PhaseSpaceFlag are shown in Table~\ref{tab:phasespace-para}. 
If user uses PhaseSpaceFlag without parameters, then the code will use the default values.

\begin{table}[h]
\centering
\label{tab:phasespace-para}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth}|p{0.48\linewidth} |p{0.12\linewidth} | p{0.05\linewidth} |}
\hline
Parameters & Meaning & Default & Unit \\
\hline
Phase\_phase\_file & File to save tracked phase space; 
                              saved in the current directory.     &    phase.out & -\\
\hline
Phase\_Dim  &  4D~/~6D tracking                            &    4D & -\\
\hline
Phase\_X    &  Horizontal coordinate at the start 
                        point of tracking.                        &    0.0  & -\\
\hline
Phase\_Px   &  Horizontal canonical momentum~/~derivative 
                        at the start point of tracking.           &    0.0 & -\\
\hline
Phase\_Y    &  Vertical coordinate at the start point 
                        of tracking.                              &    0.0 & -\\
\hline
Phase\_Py   &  Vertical canonical momentum~/~derivative 
                        at the start point of tracking.           &    0.0 & -\\
\hline
Phase\_delta&  Energy at the start point of tracking     &    0.0 & -\\
\hline
Phase\_ctau &  Longitudinal position at the start point 
                        of tracking.                              &    0.0 & -\\
\hline
Phase\_nturn&  Number of turns for tracking              &    512 & -\\
\hline
Damping\_flag& Boolean flag to turn on~/~off the radiation 
                        damping during the tracking.              &    false & - \\
\hline
\end{tabular*}
\caption{Parameters of the command ``PhaseSpaceFlag'' to calculate phase space.}
\end{table}


\subsection{IDCorrFlag (Tested for TaiWan light source; TO BE CONTINUE DEVELOPPED.)?????}
Insertion device (ID) compensation  \\

To compensate the beta beat introduced by the insertion devices, several 
families of Quadruoples can be used. Defining the following command in 
the ``*.prm'' can active this action:
\tracycommand{IDCorrFlag}{}

User also needs to define the following parameters used for the 
compensation of insertion device like the following example
in Table \ref{tab:idcorrflag:example}:

\begin{table}
\begin{tabular}{l p{10cm}}
\hline
\hline
N\_calls &     1 \\
N\_steps&    1\\
N\_Fam &    11\\
IDCquads& qs1 qs2 qs3 qs4 qs5 ql1 ql2 ql3 q1 q2 q3\\
scl\_dbetax&  5e-1\\
scl\_dbetay&  5e-1\\
scl\_dnux&    0.1\\
scl\_dnuy&    0.1\\
scl\_nux&     1e1\\
scl\_nuy&     1e1\\
ID\_step&    0.7\\
\hline
\hline
\end{tabular}
\label{tab:idcorrflag:example}
\caption{One example to define the parameters to compensate nonlinear dynamics from the 
          insertion device.}
\end{table}

The meanings of the above commands and the default values used 
to do ID compensation using quadrupoles are shown in Table \ref{tab:idcorrflag:paras}.

\begin{table}[h]
\centering
\label{tab:idcorrflag:paras}
\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}|p{0.2\linewidth}|p{0.48\linewidth} |p{0.12\linewidth} | p{0.05\linewidth} |}
\hline
Parameters & Meanings & Default & Units \\
\hline
N\_calls &Number of calls to do ID compensation & 1 & - \\
\hline
N\_steps &Number of steps.& 1 & - \\
\hline
N\_Fam & Number of quadrupole families used to do ID correction.
& 15 & - \\
\hline
IDCquads & Name of quadrupole families used to do ID correction. & - & - \\
\hline
scl\_dbetax & Scaling weight factor of the change step of horizontal 
beta function during the ID correction. & 1 & - \\
\hline
scl\_dbetay & Scaling weight factor of the change step of vertical beta 
function during the ID correction. & 1 & - \\
\hline
scl\_dnux & Scaling weight factor of the change step of horizontal 
tune during the ID correction. & 0.1 & - \\
\hline
scl\_dnuy & Scaling weight factor of the change step of vertical 
tune during the ID correction. & 0.1 & - \\
\hline
scl\_nux & Scaling weight factor of horizontal tune during the 
ID correction. & 100 & - \\
\hline
scl\_nuy &Scaling weight factor of vertical tune during the ID correction.& 100 & - \\
ID\_step & 0.7 & - & - \\
\hline
\end{tabular*}
\caption{Parameters of commands to do ID compensation using quadrupoles.}
\end{table}




\section{Multipole field error file}
\label{sec:mult:field:error}
The multipole field errors of the lattice elements can be defined 
in a file, and then the file is read into the lattice. User can 
define the systematic or random multipole field error of the 
lattice elements. 
  
There are two ways to define the multipole field errors, one way 
is to define the errors for all the families with the same type, 
for example, the error for all the quadrupoles; another way is 
to define the error for each family, for example, the ``Q1'' family 
of the quadrupoles.
  
\subsection{Systematic errors}
To define the systematic multipole field error of the element, 
the user just need to follow the rules as below.
        
This command is commonly used to add the mangets design errors 
in the lattice.

Input format of multipole error:
\tracycommand{keywords/name}{   sys   $r0$, $n$, $An$, $Bn$} 

The parameters of the errors are: 
\begin{description}
\item[keywords:]
type of lattice elements or the family name; the keywords of the 
type of lattice elements are:
\begin{tabular}{l l}
                                dip &        dipole \\
                              quad  &     quadrupole \\
                               sext &      sextupole \\
                              hcorr &     horizontal corrector \\
                              vcorr &     vorizontal corrector \\
                              qt    &       skew quadrupole \\

\end{tabular}

\item[sys:] keyword to denote that user are setting the 
systematic multipole error.
\item[$r0:$]
radius where the multipole field error is measured. 
If $r0$ = 0, then the An and Bn are the integrated 
multipole field strength at the position $x$ = $z$ = 0.

\item[$n$:]
order of multipole field error, in US. notation. 
Dip errors is 1, quadrupole error is 2, sextupole field
 error is 3, decaper field error is 4, octoper field error 
is 5, etc.
\item[$Bn$:] 
$n^{\mathrm{th}}$
integrated upright component of the multipole field.
For the component of a skew quadrupole or a vertical 
corrector, $Bn$ = 0
\item[$An$:] 
$n^{\mathrm{th}}$
integrated skew component of the multipole field.
For the component of a dipole or upright quadrupole, $An$ = 0.
\end{description}

There are two ways to define the multipole field errors strength, 
\begin{itemize}
\item
one is to define the measured field errors at the pole tip 
location $r_0$, then $b_n$ and $a_n$ are respectively the scale 
coefficient of the main magnetic field coeffeicient. 

For example, to define the decupole field errors inside a 
horizontal bending dipole with coefficient $b_1$, we define the 
normal scale coefficience as $c_5$ and skew scale coefficience 
as $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 
\begin{eqnarray*}
 b_5 &=& \frac{1}{B \rho} \frac{c_5 * B_0}{r_0^5}  \\
 a_5 &=& \frac{1}{B \rho} \frac{d_5 * B_0}{r_0^5} \\
\end{eqnarray*}
where 
\begin{equation}
 b_1 = \frac{1}{B \rho} B_0.
\end{equation}

This 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.

\item
Another way is to direct define the multipole field coefficiences $b_n$ 
and $a_n$, that is, set $r_0 = 0$. If the multipole field $\vec{B^{tip}}$ 
are measured at the tips with radius $r_0$, then $b_n$ and $a_n$ can 
be calculated using 
\begin{eqnarray*}    
b_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_y }{\partial x ^{n-1}}|_{x=0,y=0}  =  \frac{1}{B \rho} \frac{B_y^{tip}}{r_0^{n-1}} \\
a_n & = & \frac{1}{B \rho} \frac{1}{(n-1)!} \frac{\partial^{n-1} B_x }{\partial x ^{n-1}}|_{x=0,y=0}  =  \frac{1}{B \rho} \frac{B_x^{tip}}{r_0^{n-1}} \\
\vec{B^{tip}} & = &  B_x^{tip} \hat{x} + B_y^{tip} \hat{y}
\end{eqnarray*}

\end{itemize}


\begin{itemize}
\item
The line start with ``\#'' is a comment line.
\item
The blank lines in the multipole definition file are neglected by the code.
\item
The assigned multipoles errors will be added to the corresponding $n^{th}$ 
order multipole errors of the lattice element.
\end{itemize}


For the soleil lattice, the use can define the multipole errors for 
the type or each family. But to define the multipole error for all the 
quadrupoles, user can NOT define the multipole errors by the type. There 
are two choice: 
\begin{itemize}
\item
one is to define the multipole errors for each quadrupole family;
\item 
second is to define the field errors by quadrupole type, and then define 
the multipole errors on Q2 and Q7 families (the lattice with full quadrupoles) 
or  QP2a, QP2b, QP7a and QP7b families (lattice with quadrupoles which are 
cut into two halves). This is due to that Q2/QP2a/QP2b and Q7/QP7a/QP7b are 
the quadrupoles which have lengths larger than other quadrupoles in the lattice, 
and the multipole errors on them are different from the ones on the 
other short quadrupoles. 
\end{itemize}
   
The following is an example file to define systematic multipole errors on 
Soleil lattice:
\begin{flushleft}

\begin{tabular}{ l l l l l l l l l l l l }   
\#dipole  & & & & & & & & & & & \\
 dip & sys & 20e-3 & 2 & 2.2e-40 & 0.0 & 3 & -3.0e-4 & 0.0  &  & & \\
       4 & 2.0e-5 & 0.0 &  5 &  -1.0e-4 & 0.0 &  6 & -6.0e-5 & 0.0 &  7 & -1.0e-4 & 0.0 \\
& & & & & & & & & & & \\
\end{tabular}


\#quadrupole  \\
\#for all short quadrupoles \\
\begin{tabular}{ l l l l l l l l l l l l}
quad & sys & 30e-3 & 6& 2.4e-4&  0.0&  10& 0.7e-4& 0.0&    14&   0.9e-4&  0.0  \\
& & & & & & & & & & & \\
\end{tabular}

\#for all long quadrupoles qp2 and qp7 \\
\begin{tabular}{ l l l l l l l l l l l l}
  qp2a & sys & 30e-3 & 6 & 0.7e-4 & 0.0 & 10 & 1.9e-4 &  0.0 &  14 & 1.0e-4 & 0.0\\ 
  qp2b & sys & 30e-3 & 6 & 0.7e-4 & 0.0 & 10 & 1.9e-4 &  0.0 &  14 & 1.0e-4 & 0.0\\
  qp7a & sys & 30e-3 & 6 & 0.7e-4 & 0.0 & 10 & 1.9e-4 &  0.0 &  14 & 1.0e-4 & 0.0\\
  qp7b & sys & 30e-3 & 6 & 0.7e-4 & 0.0 & 10 & 1.9e-4 &  0.0 &  14 & 1.0e-4 & 0.0\\
& & & & & & & & & & & \\
\end{tabular}

\#for all short quadrupoles,sextupole mesure quadrupoles longs \\
\begin{tabular}{l l l l l l l l l}
   quad & sys & 30e-3& 3& -1.6e-4&  0.0&   4&  -3.4e-4&   0.0 \\
   & & & & & & & & \\
\end{tabular}

\#for long quadrupoles qp2 and qp7
\begin{tabular}{l l l l l l l l l}
  qp2a &sys& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0\\
  qp2b& sys& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0\\
  qp7a& sys& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0\\
  qp7b& sys& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0 \\
   & & & & & & & & \\
\end{tabular}

\# for sextupoles\\
\begin{tabular}{l l l l l l l l l l l l l l l}
sext& sys&  32e-3&  5&  5.4e-4&   0.0&  7&  3.3e-4& 0.0&  9& -4.7e-4& 0.0&  15& -9.0e-4& 0.0 \\  
    &    &       & 21& -20.9e-4& 0.0&  27&  0.8e-4& 0.0& & & & & &   \\
   & & & & & & & &  & & & & & &  \\
\end{tabular}

\# for horizontal correctors, all An=0 
\begin{tabular}{l l l l l l l l l l l l}
hcorr& sys& 35e-3& 5& 0.430& 0.0&   7& 0.063& 0.0&  11& -0.037& 0.0\\ 
   & & & & & & & &  & & &   \\
\end{tabular}

\# for vertical correctors, all Bn=0
\begin{tabular}{l l l l l l l l l l l l}
  vcorr&  sys&  35e-3&  5&  0.0&  -0.430&   7&   0.0&   0.063&   11&  0.0&   0.037\\ 
& & & & & & & &  & & &   \\
\end{tabular}

\# for sextupole associated skew quadrupole, all Bn=0
\begin{tabular}{l l l l l l}
 qt& sys& 35e-3&  4&  0.0&  -0.0\\
  qt& sys& 35e-3&    4&  0.0&  -0.680\\
\end{tabular}


\end{flushleft}

\subsection{Ramdom error}
To define random multipole field errors on the lattice elements, 
user needs to define the seed of the random errors, and then follow 
the same rule as the ones to define systematic multipole error except 
replacing ``sys'' by ``rms''. 

\textit{For example:}
\tracycommand{seed}{seed\_number}
\tracycommand{quad}{rms    30e-3 6 2.4e-4  0.0  10 0.7e-4 0.0    14   0.9e-4  0.0}

The random multipole error is multiplied by the random scale factor; the new 
value is added to the corresponding components of the magnetic field. 
The random scale factor is generated by a random function which follows 
the normal distribution (mean value is 0 and standard deviation is 1). 
The cut off value for the normal distribution function is 2 times of 
the RMS value. If user does not define seed for the random function 
before the setting of errors, then the code will stop and give an 
error message. 

 Here is example file to define random multipole error in the lattice:

\begin{flushleft}
\#define seed for the ramdom multipole error \\ 
\begin{tabular}{ l l}
 seed     &  1000000 \\
 & \\
\end{tabular}

\#dipole
\begin{tabular}{l l l l l l l l l l l l}
dip& rms&  20e-3& 2& 2.2e-40& 0.0& 3& -3.0e-4& 0.0&  4& 2.0e-5& 0.0 \\
   &    &       & 5&  -1.0e-4& 0.0&  6& -6.0e-5& 0.0&  7& -1.0e-4& 0.0 \\
& & & & & & & & & & & \\
\end{tabular}

\#quadrupole 
\begin{tabular}{l l l l l l l l l l l l }
quad& rms&  30e-3& 3& -1.6e-4&  0.0&   4&  -3.4e-4&   0.0&  6& 2.4e-4&  0.0\\
    &    &       & 10& 0.7e-4& 0.0&    14&   0.9e-4&  0.0& & & \\ 
Q2&  rms& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0&   6& 0.7e-4&  0.0\\
  &     &      &10&  1.9e-4&   0.0&   14& 1.0e-4&  0.0& & & \\
Q7&  rms& 30e-3& 3&  2.9e-4&  0.0&   4&  -8.6e-4&   0.0&   6& 0.7e-4&  0.0\\
  &     &      &10&  1.9e-4&   0.0&   14& 1.0e-4&  0.0& & & \\
& & & & & & & & & & & \\
\end{tabular}
\end{flushleft}


\section{ Misalignment error file}
The misalignment error of the lattice elements can be defined in a file, 
and then the file is read into the lattice. User can define the systematic 
or random misalignment error of the lattice elements. 

There are two ways to define the misalignment error, one way is to 
define the error for all the families in one type, for example, the error 
for all the quadrupoles; another way is to define the error for each family, 
for example, the “Q1” family of the quadrupoles.

The systermatic misalignment error file works for the lattices with full 
or half quadrupoles; the random misalignment error file only works for 
lattice with full quadrupoles. 

\subsection{Systematic errors}
To define the systematic misalignment error of the element, user 
just needs to follow the rules as below.        

input format of misalignment error:
\tracycommand{type/family}{name  sys  dx     dy  dr}

\begin{flushleft}
\begin{description}
\item[keywords:]
type of lattice elements or the name of the family. 

Keywords of the type of lattice elements are: \\
\begin{tabular}{l l}
  All &                  all the elements in the lattice\\
  girder &            girder\\
  dipole &            dipole\\
  quad   &             quadrupole\\
  sext   &              sextupole\\
  bpm    &              beam position monitor\\
  family name &    family name of the elements\\
\end{tabular}

\item[sys:]
denote that user are setting the systematic displacement error.

\item[dx:] 
defines the displacement in x direction with unit [m]. 

\item[dy:] 
defines the displacement in y direction with unit [m].

\item[dr:] 
defines the rotation angle with unit [rad]).
\end{description}

\end{flushleft}

\begin{itemize}
\item
The line start with ‘\#’ is comment line.
\item
The blank line in the misalignment error file is neglected by the code.
\end{itemize}


\begin{flushleft}
The following is an example file to define systematic multipole error on Soleil lattice: \\
\#  systematic  alignment error for SOLEIL \\
\end{flushleft}
\begin{tabular}{l l l l l}
\#  name&      keyword &  x(m)&          y(m)&      r (rad)   \\
girder& sys&   100.0e-6&        100.0e-6&           0.5e-03 \\
quad&   sys&    30.0e-6&         30.0e-6&       80.0e-06\\
sext&   sys&    30.0e-6&         30.0e-6&      100.0e-06\\
dipole& sys&   500.0e-6&        500.0e-6&           0.2e-03\\
\end{tabular}

\subsection{Random errors}
To define random misalignment errors on the lattice elements, user 
need to follow the same rule as the ones to define systematic 
misalignment error except replacing ``sys'' by ``rms''. That is:
input format of misalignment error:
\tracycommand{seed}{seed\_number}
\tracycommand{type/family}{  name  rms  dx  dy  dr}

The random misalignment error is multiplied by the random scale factor; 
the new value is added to the corresponding components of the misalignment 
components. The random scale factor is generated by a random function which 
follows the normal distribution (mean value is 0 and standard deviation is 1), 
the cut off value for the normal distribution function is 2 times of the 
RMS value.        

If user does not define seed for the random function before the setting of errors, 
then the code will stop and give an error message. 

\begin{flushleft}
Here is example file to define random misalignment error in the lattice: \\
\#  random  alignment error for SOLEIL \\
\begin{tabular}{l l l l l}
\#  name  & keyword &   x(m)&    y(m)&      r (rad)\\ 
girder& rms&   100.0e-6&        100.0e-6&           0.5e-03\\
quad&   rms&    30.0e-6&         30.0e-6&       80.0e-06\\
sext&   rms&    30.0e-6&         30.0e-6&      100.0e-06\\
dipole& rms&   500.0e-6&        500.0e-6&           0.2e-03\\
\end{tabular}
\end{flushleft}

\subsection{Vacuum chamber file}
User can define the script to set the vacuum chamber limitation 
around the ring. 
The format of the vacuum chamber definition is 
\tracycommand{MK1, MK2,}{ minimum x, maximum x, minimum y, maximum y}

\begin{itemize}  
\item
To set the vacuum chamber, it is needed to add two markers in the lattice, 
such as MK1 and MK2, MK1 is before the first element and MK2 is after 
the end element of the vacuum chamber region.
The numbers of MK1 and MK2 are the same in the lattice.
\item
The units are [meter] for minimum x, maximum x, minimum y, maximum y. 
\item 
The first line is to define the global vacuum chamber limit around the ring, 
and the key words should be "Start","All".
\item
Lines start with “\#” are comment.
\end{itemize}



The following is one example of the user vacuum chamber script:
\begin{flushleft}
         \#*********************************************\\
         \# Script to set the vacuum chamber \\
         \#\\
         \#**********************************************\\
\begin{tabular}{l l l l l l}
         \# MK1& MK2&  dxmin&  dxmax&  dymin&   dymax  \\
         Start&  All&    -35e-3&  35e-3&  -12.5e-3&   12.5e-3\\
        \#sdm1& esdm&  -21e-3&  21e-3&   -5e-3&     5e-3\\
          debut& ehu600&  -35e-3&  35e-3&  -7e-3&    7e-3\\
          ssep&  esep&   -20e-3&  35e-3&  -7e-3&    7e-3\\
          ssdm&  esdm&   -21e-3&  21e-3&  -5e-3&    5e-3\\
           ssdac& esdac & -35e-3&  25e-3&  -2.5e-3&   2.5e-3\\
\end{tabular}
\end{flushleft}
\end{document}