\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&\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}