thintrack.tex

%% TRACKING chapter
\chapter{Particle Tracking}
\label{chap:tracking}\label{chap:thintrack}

\section{Introduction to \madx Tracking Modules}
\label{sec:trackintro}

A number of particles with given initial conditions can be tracked
through a beam-line or a ring. The particles can be tracked either for a
single passage or for many turns.  


While \madx keeps most of the functionality of \madeight, the
trajectory tracking in \madx is considerably modified compared to
\madeight. 
The reason is that in \madeight the thick lens tracking is inherently not
symplectic, which implies that the phase space volume is not preserved
during the tracking, i.e. contrary to the real particle the tracked
particle amplitude is either growing or decreasing. 


The non-symplectic tracking as in \madeight has been completely excluded
from \madx by taking out the thick lens part from the tracking
modules. Instead two types of tracking modules (both symplectic) are
implemented into \madx. 


The first part of this design decision is the thin-lens tracking module
(\hyperref[sec:trackoverview]{\texttt{THINTRACK}})  which tracks
symplecticly through drifts and kicks and by replacing the end effects
by their symplectic part in the form of an additional kick on either end of
the element. This method requires a preliminary conversion of a sequence
with thick elements into one composed of thin elements (see the
\hyperref[chap:makethin]{\texttt{MAKETHIN}} command).


The second part of this design decision is to produce a thick lens
tracking module based on the \ptc code of E.~Forest that
allows a symplectic treatment of all accelerator elements giving the
user full control over the precision (number of steps and integration
type) and exactness (full or extended Hamiltonian) of the results. 


The first \ptc thick-lens tracking module is named
\hyperref[sec:ptc-track]{PTC\_TRACK}. 
It has the same features as the thin-lens tracking code
(\hyperref[sec:trackoverview]{thintrack}) except that it
treats thick-lenses in a symplectic manner. 


There is a second \ptc tracking module called the line tracking module
(\hyperref[sec:ptc-trackline]{\texttt{PTC\_TRACKLINE}}). It was developped
for tracking particles in
\href{http://clic-study.web.cern.ch/CLIC-Study/}{CLIC}, with the
specificities that it can deal with beam-lines containing traveling-wave
cavities and includes actual beam acceleration. 


%%\title{Thin-Lens Tracking Module (thintrack)}
%  Created by: Andre VERDIER, 21-Jun-2002 
%  Changed by: Andre Verdier, 26-Jun-2002 
%  Changed by: Alexander Koschik, 07-Mar-2006 
%  Changed by: Alexander Koschik, 29-Mar-2006 
%  Changed by: Alexander Koschik, 02-Feb-2007 

\section{Overview of Thin-Lens Tracking} % Module (thintrack)}
\label{sec:trackoverview}

The \textbf{thin-lens tracking module} of \madx performs element per
element tracking of one or several particle trajectories in the last
\hyperref[sec:use]{\texttt{USE}}d sequence.  
 
%  either for single passage (option <var class="option">onepass</var>)
%  or for many turns (default option).  

Only thin elements are allowed (apart from the element \texttt{DRIFT}),
which guarantees the symplecticity of the coordinate transformation. Any
lattice can be converted into a "thin element" lattice by invoking the
\hyperref[chap:makethin]{\texttt{MAKETHIN}} command. 

Several commands are actually required to complete a tracking run:

\madbox{
xxxxxxx\= \kill
TRACK, \>DELTAP=real, ONEPASS=logical, DAMP=logical; \\
      \>QUANTUM=logical, SEED=real, UPDATE=logical, \\
      \>ONETABLE=logical, RECLOSS=logical, FILE=filename, \\
      \>APERTURE=logical,ONLY\_AVERAGE=logical; \\
xxxx\=xxxxxxx\= \kill
  \>\ldots \\
  \>START, X=real, PX=real, Y=real, PY=real, T=real, PT=real;  \\
  \>START, FX=real, PHIX=real, FY=real, PHIY=real, \\
  \> \>FT=real, PHIT=real;\\  
  \>\ldots \\
  \>OBSERVE, PLACE=string; \\  
  \>\ldots \\
  \>RUN, TURNS=integer, MAXAPER=double\_array, FFILE=integer; \\
  \>\ldots\\
  \>DYNAP, \>TURNS=real, FASTUNE=logical, LYAPUNOV=real,\\
  \>       \>MAXAPER=real\_array, ORBIT=logical;\\
  \>\ldots \\
ENDTRACK;
}


Inside the block \texttt{TRACK}-\texttt{ENDTRACK} a series 
of initial trajectory coordinates can be specified by the \texttt{START} 
command (as many commands as trajectories). This will be usually done in a 
\texttt{WHILE}-loop. \textbf{Note} that the coordinates are either 
\textbf{canonical} coordinates or \textbf{action-angle} variables!

For usual tracking (single/multi-turn), all coordinates are specified
with respect to the actual closed orbit (possibly off-momentum, with
magnet errors) and \textbf{NOT} with respect to the reference orbit. 

If the option \texttt{ONEPASS} is used, the coordinates are specified
with respect to the reference orbit. The name \texttt{ONEPASS} might be
misleading: Still tracking can be single- or multi-turn!   

The tracking is actually started with the \texttt{RUN} command, where
the option \texttt{TURNS} defines for how many turns the particles will
be tracked in the given sequence. 

If the option \texttt{DUMP} is used, the particle coordinates are
written to files at each turn. The output files are named
automatically. The name given by the user is followed by
\texttt{.obsnnnn} (observation point), followed by
\texttt{.pnnnn} (particle number).\\
Hence filenames look like \texttt{track.obs0001.p0001}.  

Tracking creates a number of internal tables and can create files on disk: 
\texttt{TRACKSUMM, TRACKLOSS}, and \texttt{TRACKONE} or
\texttt{TRACK.OBS\$\$\$\$.P\$\$\$\$} (depending on the attribute
\texttt{ONETABLE} of the \texttt{RUN} command)
\texttt{ONLY\_AVERAGE} when used with ONETABLE it will only output
the average of all the particles. 

These internal tables can be accessed via the
\hyperref[chap:tables]{\texttt{TABLE}}-access functions.

Plotting of particle coordinates or other data in these tables is
possible in \madx. Plotting can also be done with external programs by
using the files created by \texttt{TRACK}.  

\madx also has the capability to treat space-charge during tracking
runs. There is no space-charge command per se but space charge is
controlled through several options of \madx (see
\hyperref[sec:option]{\texttt{OPTION}}) and specific attributes of the
\hyperref[sec:run]{\texttt{RUN}} command in this \texttt{TRACK} environment. A
section specific to space charge options and particularities appears
below.

\section{TRACK}
\label{sec:track}

The \texttt{TRACK} command initiates trajectory tracking by entering the 
thin-lens tracking module. 

\madbox{
xxxxxxx\= \kill
TRACK, \>DELTAP=real, ONEPASS=logical, DAMP=logical; \\
       \>QUANTUM=logical, SEED=real, UPDATE=logical, \\
       \>ONETABLE=logical, RECLOSS=logical, FILE=filename, \\
       \>APERTURE=logical;
}

The attributes of the TRACK command are:

\begin{madlist}
  \ttitem{DELTAP} relative momentum offset for reference closed orbit (switched
  off for \texttt{ONEPASS}) \\  
  Defining a non-zero \texttt{DELTAP} results in a change of the beam
  momentum/energy without changing the magnetic properties in the
  sequence, which leads to an off-momentum closed orbit different from
  the on-momentum reference orbit. Particle coordinates are then given
  with respect to this new closed orbit, unless the option
  \texttt{ONEPASS=true} is used! \\  
  (Default:~0.0)

  \ttitem{ONEPASS} flag to ensure that no closed orbit search is done,
  which also means that no stability test is done. This is always the
  case for transfer lines, but this option can also be enabled for
  multi-turn tracking of a circular machine. \texttt{ONEPASS=true} does
  \textbf{NOT} restrict tracking to a single turn. \\
  With \texttt{ONEPASS=true}, the particle coordinates are specified with
  respect to the reference orbit. \\  
  With \texttt{ONEPASS=false}, the closed orbit is calculated and the particle
  coordinates are given with respect to the closed orbit coordinates.\\
  This flag affects the behavior of the \hyperref[sec:option]{\texttt{BBORBIT}} flag. \\
  The name of this attribute is misleading but was kept for backwards
  compatibility.  \\ 
  (Default:~false)

  \ttitem{DAMP} flag to introduce synchrotron damping (needs RF cavity
  and flag \texttt{RADIATE} in the \texttt{BEAM} command). \\ (Default:~false)

  \ttitem{QUANTUM} flag to introduce quantum excitation via random
  number generator and tables look-up (\texttt{SYNRAD} $=1$, see ref. \cite{roy1990}) or polynomial
  interpolation (\texttt{SYNRAD} $=2$, see ref. \cite{hbu2007}) for photon emission.
  The choice of the generator can be selected via the command
  \hyperref[sec:option]{\texttt{OPTION}} attribute \texttt{SYNRAD}. \\ (Default:~2)

  \ttitem{SEED} If \texttt{QUANTUM} is true, it selects a particular sequence of random values. 
A \texttt{SEED} value is an integer in the range [0...999999999] (default:
123456789). Note that the seed set with this command is shared with the \hyperref[sec:coption]{\texttt{COPTION}} and \hyperref[sec:coption]{\texttt{EOPTION}} commands. See also: \hyperref[subsubsec:random]{Random Values}.

  \ttitem{DUMP} flag to write the particle coordinates in files, whose
  names are generated automatically. \\ (Default:~false)

  \ttitem{APERTURE} a logical flag to trigger aperture check at the entrance 
  of each element (except \texttt{DRIFT}s). A particle is lost from the table of 
  tracked particles if its position lies outside the aperture of the current 
  element at the entrance of this element. \\ 
  (Default:~false) \\
  
  The \hyperref[chap:aperture]{\texttt{APERTYPE}} and 
  \hyperref[chap:aperture]{\texttt{APERTURE}} information of each element 
  in the sequence is used to assess the particle loss. 
  However \texttt{TRACK} only takes into account the predefined aperture 
  types listed in table \ref{table:apertype}
  \\
  
  Note that if no aperture information was specified for an element, 
  the following procedure still takes place:
  \\
  $\rightarrow$ No aperture definition for element $\rightarrow$ 
  Default apertype/aperture assigned (currently this is   
  \texttt{APERTYPE=circle, APERTURE=\{0\}}) 
  \\ $\rightarrow$  
  If tracking with \texttt{APERTURE} is used and an
  element with \texttt{APERTYPE=circle} AND \texttt{APERTURE=\{0\}}  
  is encountered, then the first value of the \texttt{MAXAPER} vector
  is assigned as the circle's radius (no permanent assignment!). 
  See option \hyperref[sec:run]{\texttt{MAXAPER}} for the default values. 
  \\ $\Rightarrow$
  Hence even if no aperture information is specified by the user for
  certain elements, default values will be used! 


  \ttitem{ONETABLE} flag to write all particle coordinates in a single
  file instead of one file per particle. \\ (Default:~false)

  \ttitem{RECLOSS} flag to create in memory a table named "trackloss"
  containing the coordinates of lost particles.\\
  (Default:~false) \\
  Traditionally, when a particle is lost on the aperture, this information
  is written to stdout. To allow more flexible tracking studies, the
  coordinates of lost particles and additional information can also be
  saved in a table in memory. Usually one would save this table to a
  file using the \texttt{WRITE} command after the tracking run has
  finished. The following information is available in the TFS table
  "trackloss":          
  \begin{itemize}
  \item Particle ID (number)
  \item Turn number
  \item Particle coordinates (x,px,y,py,t,pt)
  \item Longitudinal position in the machine (s)
  \item Beam energy
  \item Element name, where the particle is lost
  \end{itemize}

  \ttitem{FILE} name for the track table. The default name is different
  depending on the value of the \texttt{ONETABLE} attribute. \\ 
  (Default: "track" if \texttt{ONETABLE=true}, "trackone" if \texttt{ONETABLE=false})

  \ttitem{UPDATE} flag to trigger parameter update per turn. \\  
  (Default:~false) \\
  Specifying \texttt{UPDATE=true} gives access to the following additions:   
  \begin{madlist}
    \ttitem{tr\$turni} this special variable contains the turn number;
    it can be used in expressions like \texttt{KICK := SIN(tr\$turni)} and is
    updated at each turn during tracking.     
    \ttitem{tr\$macro}  this special macro can be
    user-defined and is executed/updated at each turn, during tracking.
    A macro structure is necessary to provide for table access.
    \textsl{e.g.} \\ 
    \texttt{
      tr\$macro(turn): macro=\{ \\
      commands that can depend on the turnnumber;\\
      \};
    } 
  \end{madlist}

\end{madlist}

\textbf{Remarks}\\
\emph{IMPORTANT:} If an RF cavity has a non-zero voltage, synchrotron
oscillations are automatically included. If tracking with constant
momentum is desired, then the voltage of the RF cavities has to be set
to zero. If an RF cavity has a no zero voltage and \texttt{DELTAP} is non zero, 
tracking is done with synchrotron oscillations around an off-momentum
closed orbit.


%% \begin{tabular}{c p{5cm} p{3cm} c}
%%   \hline 
%%   \textbf{Option} & \textbf{Meaning} & \textbf{Default Value} &
%%   \textbf{Value Type} \\  
%%   \hline
%%   DELTAP & relative momentum offset for reference closed orbit (switched
%%   off for onepass) &  0.0 & double \\  
%%   \hline
%%   ONEPASS & the sequence is treated as transfer line (no stability test,
%%   ie. no closed-orbit search) & .FALSE.= closed-orbit search & logical
%%   \\  
%%   \hline
%%   DAMP & introduce synchrotron damping (needs RF cavity, RADIATE in
%%   BEAM)  & .FALSE.= no damping & logical \\  
%%   \hline
%%   QUANTUM & introduce quantum excitation via random number generator and
%%   tables for photon emission & .FALSE.= no excitation & logical \\  
%%   \hline
%%   DUMP & write the particle coordinates in files (names generated
%%   automatically)  & .FALSE.= no file generated & logical \\  
%%   \hline
%%   APERTURE & particle is lost if its trajectory is outside the aperture
%%   of the current
%%   element. \hyperlink{track:remarks:aperture:notes}{Notes}. & .FALSE.=
%%   no aperture check & logical \\  
%%   \hline
%%   ONETABLE & write all particle coordinates in a single file & .FALSE.=
%%   one file per particle & logical \\  
%%   \hline
%%   RECLOSS & create a table named "trackloss" in memory with lost
%%   particles' coordinates & .FALSE.= no table & logical \\  
%%   \hline
%%   FILE & name for the track table   & "track", "trackone" & string \\ 
%%   \hline
%%   UPDATE & parameter update per turn   & .FALSE.= no update & string \\  
%%   \hline
%% \end{tabular}



\section{START}
\label{sec:start}

After the \texttt{TRACK} command, initial trajectory coordinates must be
provided for each trajectory or particle to be tracked, with one
\texttt{START} command per trajectory or particle.

The coordinates can be expressed as either
\hyperref[subsec:tables-canon]{\textbf{canonical}}
or \textbf{action-angle} coordinates.

\madbox{
START, \=X=real, PX=real, Y=real, PY=real, T=real, PT=real;  \\
START, \>FX=real, PHIX=real, FY=real, PHIY=real, \\
       \>FT=real, PHIT=real;
}

For the case of action-angle coordinates, the normalised amplitudes are
expressed in number of r.m.s. beam size $F_X$, $F_Y$, $F_T$ (the actions
being computed with the emittances given in the \texttt{BEAM} command)
\textbf{in each mode plane}. 
The phases are $\Phi_X$, $\Phi_Y$ and $\Phi_T$ expressed in
radian. In the uncoupled case, we have in the plane mode labelled z, and
with $E_z$ being the r.m.s. emittance in that plane:\\
\begin{equation}
Z = F_z \sqrt E_z \cos\Phi_z , \qquad P_z= F_z \sqrt E_z \sin\Phi_z
\end{equation}

The attributes of the START command are:
\begin{madlist}
  \ttitem{X, PX, Y, PY, T, PT} canonical coordinates. 
  \ttitem{FX, PHIX, FY, PHIY, FT, PHIT} action-angle coordinates.
\end{madlist}

\textbf{Remarks} \\
For usual tracking (single/multi-turn), all coordinates are specified
with respect to the actual closed orbit (possibly off-momentum, with
magnet errors) and \textbf{NOT} with respect to the reference orbit.

If the option \texttt{onepass} of the \texttt{TRACK} is used, the
coordinates are specified with respect to the reference orbit.

\section{OBSERVE}
\label{sec:observe}

During the tracking process, particle coordinates at specific named
locations along the machine can be printed to file(s). The declaration of
an observation point is with the OBSERVE command: 

\madbox{
OBSERVE, PLACE=string;  
}

The single attribute of \texttt{OBSERVE} is:
\begin{madlist}
  \ttitem{PLACE} the name of the observation point. 
\end{madlist}
  
Several \texttt{OBSERVE} commands can be given for the same tracking
job, one per observation point. 

If no \texttt{OBSERVE} command is given in a tracking job, but the
\texttt{DUMP} option in the \texttt{TRACK} command is used, the
trajectory coordinates are still recorded and one observation point is
provided at the starting point of the sequence. 
     
The output files are named automatically. The name given by
the user (attribute \texttt{FILE} of the \texttt{TRACK} command) is
followed by ".obsnnnn", where nnnn is the observation point number, and followed by 
".pnnnn"  wherer nnnn is now the particle number. Hence the default
filename for the first obseration point and first particle looks like
\texttt{track.obs0001.p0001}.


\section{RUN}
\label{sec:run}

The actual tracking is triggered by the \texttt{RUN} command.

\madbox{
RUN, TURNS=integer, MAXAPER=real\_array, FFILE=integer, KEEPTRACK=logical;
}

The \texttt{RUN} command has three attributes:

\begin{madlist}
  \ttitem{TURNS} number of turns to be tracked.

  \ttitem{MAXAPER} defines the maximum aperture (by
  aperture type) beyond which the particle is considered
  to be lost upper and, in addition, limits for the six coordinates.\\
  (Default: \{0.1, 0.01, 0.1, 0.01, 1.0, 0.1\} \\
  The limits defined by the \texttt{MAXAPER} option are only being taken
  into account if the \texttt{APERTURE} option of the \texttt{TRACK}
  command is used. 

  \ttitem{FFILE} defines the turn periodicity for printing coordinates at
   observation points. (Default:~1)\\

   \texttt{FFILE=n} will print coordinates every n-th turn only. 

   \ttitem{KEEPTRACK} a logical flag to keep data from previous tracking and append new results to tables. (Default:~false)

   \ttitem{TRACK\_HARMON} is used to calculate the maximum time difference before a particle is considered lost ($t_{max}$). 
    $t_{max} =\frac{C}{h_{track}*\beta}$ where $h_{track}$=TRACK\_HARMON and $C$ is the total length of the machine.  (Default: 1)
\end{madlist}


%%\title{DYNAP}
%  Changed by: Hans Grote, 17-Jun-2002 
%  Changed by: Frank Zimmermann, 18-Jun-2002 
%  Inserted in THINTRACK by ghislain, 2014-Aug-07  14:43:45  

\section{DYNAP}

The \texttt{DYNAP} command calculates tunes, tune footprints, smear and
Lyapunov exponent from tracking data. \texttt{DYNAP} can be called
instead of \texttt{RUN} inside a \texttt{TRACK} command environment.

\madbox{
DYNAP, \=TURNS=integer, FASTUNE=logical, LYAPUNOV=real,\\
       \>MAXAPER=real\_array, ORBIT=logical;
}
 
For each previously entered start command, \texttt{DYNAP} tracks two
close-by particles over a selected number of turns (minimum 64 and 
maximum 1024), from which it obtains the betatron tunes with error, 
the action smear, and an estimate of the lyapunov exponent. 
Many such companion particle-pairs can be tracked at the same time,
which speeds up the calculation.

The \textit{smear} is defined as  
$2 \times (\ wxy_{max} - wxy_{min}\ ) / (\ wxy_{max} + wxy_{min}\ )$,
where the $wxy_{min,max}$ refer to the  minimum and
maximum values of the sum of the transverse betatron invariants
$wx+wy$ during the tracking. 

The tunes are computed by using an FFT and formula (18) in reference 
\cite{bartolini1995} if the number of turns is 64 or less, or formula (25) in 
the same reference if the number of turns is strictly larger than 64.
 
\texttt{DYNAP} has the following attributes: 
\begin{madlist}
   \ttitem{TURNS} the number of turns to be tracked (Default:~64,
   minimum:~64 and maximum:~1024). 
     
   \ttitem{FASTUNE} a logical flag to compute the tunes. (Default:~false)
 
   \ttitem{MAXAPER} a vector of 6 real numbers defining the maximum
   aperture beyond which the particle is considered to be lost.\\
   (Default: \{0.1, 0.01, 0.1, 0.01, 1.0, 0.1\}
     
   \ttitem{LYAPUNOV} the initial distance which is added to the
   \textit{x} coordinate of the companion particle of every particle
   declared with \texttt{START} commands. (Default:~1.e-7~m)
   
   \ttitem{ORBIT} A logical flag. If set, the flag \textit{orbit} 
   is true during the tracking and its initialization
   (default: true).
   \textbf{This flag should be set to be true, if 
     normalized coordinates are to be entered.}
\end{madlist}

%% Example:
%% \begin{verbatim}
%% BEAM,PARTICLE=ELECTRON,ENERGY=50,EX=1.E-6,EY=1.E-8,ET=0.002,SIGT=1.E-2;
%% ...
%% USE,PERIOD=FODO;
%% ...
%% TRACK;
%% START,X=0.0010,Y=0.0017,PT=0.0003;
%% DYNAP,FASTUNE,TURNS=1024,LYAPUNOV=1.e-7;
%% ENDTRACK;
%% ...
%% \end{verbatim}

The first command defines the beam parameters. It is  essential that the
longitudinal emittance \texttt{ET} is set. The command \texttt{USE}
selects the beam line or sequence. The \texttt{TRACK} command activates the
tracking module, \texttt{START} enters the starting coordinates (more
than one particle can be defined),  \texttt{DYNAP} finally tracks two
nearby particles  with an initial distance equal to the value of the \texttt{
LYAPUNOV} attribute  for each
\texttt{START} definition over \texttt{TURNS} revolutions, and
\texttt{ENDTRACK} terminates the execution of the tracking module. 

The results are stored in the \texttt{DYNAP} and \texttt{DYNAPTUNE}
tables, and can be obtained by the two commands  
 
\madxmp{
VALUE, \=TABLE(dynap,smear); \\
VALUE, \>TABLE(dynaptune,tunx), \\
       \>TABLE(dynaptune,tuny), \\
       \>TABLE(dynaptune,dtune);
}

More generally, all results can be printed to a file, using the commands 
\madxmp{
WRITE, TABLE=dynap, FILE; \\
WRITE, TABLE=dynaptune, FILE;
}
The output file \texttt{lyapunov.data} lists the turn number and phase
distance between the two Lyapunov partners, respectively, allowing for
visual inspection of chaoticity.
 
\section{ENDTRACK}
\label{sec:endtrack}

Tracking is terminated by the command \texttt{ENDTRACK} with no
attributes. 

\madbox{ENDTRACK;}

\section{Space Charge}

\madx can perform tracking using a frozen space charge model.
This process is rather involved and requires careful setting of several options 
and switches as well as the insertion of space-charge kicks inserted within 
regular elements. The Space-Charge specifics of \madx are documented in 
\cite{kapin2013}.


%% EOF