track.tex 13.7 KB
Newer Older
snuverink_j's avatar
snuverink_j committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
\input{header}

\chapter{Tracking}
\label{chp:track}
\index{Tracking|(}

\begin{table}[ht] \footnotesize
  \begin{center}
    \caption{Commands accepted in Tracking Mode}
    \label{tab:trackcmd}
    \begin{tabular}{|p{0.3\textwidth}|p{0.6\textwidth}|}
      \hline
      \tabhead{Command & Purpose}
      \hline
snuverink_j's avatar
snuverink_j committed
15 16 17 18 19 20 21 22 23
      \tabline{TRACK}{Enter tracking mode}
      \tabline{LINE}{Label of \texttt{LINE} or \texttt{SEQUENCE}}
      \tabline{BEAM}{Label of \texttt{BEAM}}
      \tabline{T0}{Initial time}
      \tabline{DT}{Array of time step sizes for tracking}
      \tabline{MAXSTEPS}{Array of maximal number of time steps}
      \tabline{ZSTART}{z-location [m], from where to run simulation}
      \tabline{ZSTOP}{Array of z-location [m], after which the simulation switches to the next set of \texttt{DT}, \texttt{MAXSTEPS} and \texttt{ZSTOP}}
      \tabline{STEPSPERTURN}{Number of time steps per revolution period}
24
      \tabline{TIMEINTEGRATOR}{Defines the time integrator used in \textit{OPAL-cycl}}
snuverink_j's avatar
snuverink_j committed
25 26 27 28 29 30
      \tabline{name=expression}{Parameter relation}
%      \tabline{NOISE}{& Define power supply ripple}
      \ifthenelse{\boolean{ShowMap}}{\tabline{START}{Define initial conditions}
      \tabline{TSAVE}{Save end conditions}}{}
      \tabline{RUN}{Run particles for specified number of turns or steps}
      \tabline{ENDTRACK}{Leave tracking mode}
snuverink_j's avatar
snuverink_j committed
31 32 33 34 35 36 37 38 39 40
      \hline
    \end{tabular}
  \end{center}
\end{table}

\section{Track Mode}
\label{sec:trackmode}
\index{TRACK}
\index{ENDTRACK}

snuverink_j's avatar
snuverink_j committed
41 42
Before starting to track, a beam line see~Section~\ref{line} \ifthenelse{\boolean{ShowMap}}{or
sequence see~Section~\ref{sequence}}{} and a beam see~Chapter~\ref{beam} must be selected.
43
The time step (\texttt{DT}) and the maximal steps to track (\texttt{MAXSTEPS}) or \texttt{ZSTOP} should be set. This command causes \textit{OPAL} to enter ``tracking mode'',
snuverink_j's avatar
snuverink_j committed
44
in which it accepts only the track commands see~Table~\ref{trackcmd}. In order to preform several tracks, specify arrays of parameter
snuverink_j's avatar
snuverink_j committed
45
in \texttt{DT}, \texttt{MAXSTEPS} and \texttt{ZSTOP}. This can be used to change the time step manually.
snuverink_j's avatar
snuverink_j committed
46 47 48 49 50


The attributes of the command are:
\begin{kdescription}
\item[LINE]
snuverink_j's avatar
snuverink_j committed
51 52
  The label of a preceding \texttt{LINE} see~Section~\ref{line}
  \ifthenelse{\boolean{ShowMap}}{ or \texttt{SEQUENCE} see~Section~\ref{sequence}}{} (no default).
snuverink_j's avatar
snuverink_j committed
53
\item[BEAM]
snuverink_j's avatar
snuverink_j committed
54 55
  \sloppy The named \texttt{BEAM} command defines the particle mass, charge
  and reference momentum (default: \texttt{UNNAMED\_BEAM}).
snuverink_j's avatar
snuverink_j committed
56 57
  \index{UNNAMED\_BEAM}
\item[T0]
snuverink_j's avatar
snuverink_j committed
58
 The initial time [{s}] of the simulation, its default value is 0.
snuverink_j's avatar
snuverink_j committed
59
\item[DT]
snuverink_j's avatar
snuverink_j committed
60
  Array of  time step sizes for tracking, default length of the array is 1 and its only value is {1}{ps}.
snuverink_j's avatar
snuverink_j committed
61 62 63
\item[MAXSTEPS]
  Array of maximal number of time steps, default length of the array is 1 and its only value is 10.
\item[ZSTART]
snuverink_j's avatar
snuverink_j committed
64
  Initial position of the reference particle along the reference trajectory, default position is {0.0}{m}.
snuverink_j's avatar
snuverink_j committed
65
\item[ZSTOP]
snuverink_j's avatar
snuverink_j committed
66
  Array of z-locations [m], default length of the array is 1 and its only value is $1E6$ [m]. The simulation switches to the next set, $i+1$, of \texttt{DT}, \texttt{MAXSTEPS} and \texttt{ZSTOP} if either it has been tracking with the current set for more than $\text{\texttt{MAXSTEPS}}_i$ steps or the mean position has reached a z-position larger than $\text{\texttt{ZSTOP}}_i$. If set $i$ is the last set of the array then the simulation stops.
snuverink_j's avatar
snuverink_j committed
67 68

 \item[TIMEINTEGRATOR]
69
  Define the time integrator. Currently only available in \textit{OPAL-cycl}.
snuverink_j's avatar
snuverink_j committed
70
  The valid options are \texttt{RK-4}, \texttt{LF-2} and \texttt{MTS}:
snuverink_j's avatar
snuverink_j committed
71
  \begin{kdescription}
72
    \item[RK-4] the fourth-order Runge-Kutta integrator. This is the default integrator for \textit{OPAL-cycl}.
snuverink_j's avatar
snuverink_j committed
73
    \item[LF-2] the second-order Boris-Buneman (leapfrog-like) integrator.
snuverink_j's avatar
snuverink_j committed
74 75
      Currently, \texttt{LF-2} is only available for multi-particles with/without space charge.
      For single particle tracking and tune calculations, use the \texttt{RK-4} for the time being.
snuverink_j's avatar
snuverink_j committed
76 77 78
    \item[MTS] the multiple-time-stepping integrator.
    Considering that the space charge fields change much slower than the external fields in cyclotrons,
    the space charge can be calculated less  frequently than the external field interpolation, so as to reduce time to solution.
snuverink_j's avatar
snuverink_j committed
79
    The outer step (determined by \texttt{STEPSPERTURN}) is used to integrate  space charge effects.
snuverink_j's avatar
snuverink_j committed
80
    A constant number of sub-steps per outer step is used to query external fields and to move the particles.
snuverink_j's avatar
snuverink_j committed
81
    The number of sub-steps can be set with the option \texttt{MTSSUBSTEPS} and its default value is 1.
snuverink_j's avatar
snuverink_j committed
82 83
    When using this integrator, the input file has to be rewritten in the units of the outer step.
   For example, extracts of the input file suited for
snuverink_j's avatar
snuverink_j committed
84 85
    \texttt{LF-2} or \texttt{RK-4} read
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
86 87 88 89 90 91 92 93 94 95
Option, PSDUMPFREQ=100;
Option, REPARTFREQ=20;
Option, SPTDUMPFREQ=50;
Option, VERSION=10600;
REAL turns=5;
REAL nstep=3000;
TRACK, LINE=l1, BEAM=beam1, MAXSTEPS=nstep*turns, STEPSPERTURN=nstep,
TIMEINTEGRATOR="LF-2";
    RUN, METHOD = "CYCLOTRON-T", BEAM=beam1, FIELDSOLVER=Fs1, DISTRIBUTION=Dist1;
ENDTRACK;
snuverink_j's avatar
snuverink_j committed
96
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
97
and should be transformed to
snuverink_j's avatar
snuverink_j committed
98
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
99 100 101 102 103 104 105 106 107 108 109
Option, MTSSUBSTEPS=10;
Option, PSDUMPFREQ=10;
Option, REPARTFREQ=2;
Option, SPTDUMPFREQ=5;
Option, VERSION=10600;
REAL turns=5;
REAL nstep=300;
TRACK, LINE=l1, BEAM=beam1, MAXSTEPS=nstep*turns, STEPSPERTURN=nstep,
TIMEINTEGRATOR="MTS";
    RUN, METHOD = "CYCLOTRON-T", BEAM=beam1, FIELDSOLVER=Fs1, DISTRIBUTION=Dist1;
ENDTRACK;
snuverink_j's avatar
snuverink_j committed
110
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
111 112 113 114
In general all step quantities should be divided by MTSSUBSTEPS.

In our first experiments on PSI injector II cyclotron, simulations with reduced
space charge solving frequency by a factor of 10 lie still very close to the original solution.
snuverink_j's avatar
snuverink_j committed
115
How large \texttt{MTSSUBSTEPS} can be chosen of course depends on the importance of space charge effects.
snuverink_j's avatar
snuverink_j committed
116 117 118
  \end{kdescription}

\item[STEPSPERTURN]
119
  Number of time steps per revolution period. Only available for \textit{OPAL-cycl}, default value is 720.
snuverink_j's avatar
snuverink_j committed
120 121 122 123

\end{kdescription}

\ifthenelse{\boolean{ShowMap}}{
124
In \textit{OPAL-t} and \textit{OPAL-map}, the command format is:
snuverink_j's avatar
snuverink_j committed
125
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
126
TRACK, LINE=name, BEAM=name, MAXSTEPS=value, DT=value;
snuverink_j's avatar
snuverink_j committed
127
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
128 129
}{}

130
In \textit{OPAL-cycl}, instead of setting time step, the time steps per-turn should be set.
snuverink_j's avatar
snuverink_j committed
131
The command format is:
snuverink_j's avatar
snuverink_j committed
132
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
133
TRACK, LINE=name, BEAM=name, MAXSTEPS=value,  STEPSPERTURN=value;
snuverink_j's avatar
snuverink_j committed
134
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
135 136 137 138

Particles are tracked in parallel i.e. the coordinates of all particles
are transformed at each beam element as it is reached.

139
\textit{OPAL} leaves \textbf{track mode} when it sees the command
snuverink_j's avatar
snuverink_j committed
140
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
141
  ENDTRACK;
snuverink_j's avatar
snuverink_j committed
142
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
143 144 145 146 147 148 149 150




\subsection{Track a Random Machine} \label{sec:randmach}
This example shows how to track a {\em random} machine i.e. some
parameters are random variables. At the moment (Version 1.1.4) there seams to be a problem when
having random variables in the Distribution command.
snuverink_j's avatar
snuverink_j committed
151
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
Option, SCAN=TRUE;
......

REAL I=0;
WHILE (I < 3) {

   REAL rv1:= (RANF()*4.7);
   REAL rv2:=0.0;
   REAL rv3:=0.0;
   REAL rv4:=0.0;
   REAL rv5:=0.0;

   Ppo: PepperPot, L=200.0E-6, ELEMEDGE=6.0E-3,
        R=1.0E-4, PITCH=0.5E-4, NHOLX=20, NHOLY=20,
        XSIZE=5.0E-3, YSIZE=5.0E-3, OUTFN="ppo.h5";

   Col: ECollimator, L=3.0E-3, ELEMEDGE=7.0E-3,
        XSIZE=7.5E-4, YSIZE=7.5E-4, OUTFN="Coll.h5";
   SP1: Solenoid, L=1.20, ELEMEDGE=-0.5315,
        FMAPFN="1T2.T7", KS=8.246e-05 + rv2;
   SP2: Solenoid, L=1.20, ELEMEDGE=-0.397,
        FMAPFN="1T3.T7", KS=1.615e-05 + rv3;
   SP3: Solenoid, L=1.20, ELEMEDGE=-0.267,
        FMAPFN="1T3.T7", KS=1.016e-05 + rv4;
   SP4: Solenoid, L=1.20, ELEMEDGE=-0.157,
        FMAPFN="1T3.T7", KS=4.750e-05 + rv5;
   SP5: Solenoid, L=1.20, ELEMEDGE=-0.047,
        FMAPFN="1T3.T7", KS=0.0;

   gun: RFCavity, L=0.013, VOLT=(-47.51437343 + rv1),
        FMAPFN="1T1.T7", ELEMEDGE=0.00,
        TYPE="STANDING", FREQ=1.0e-6;

   value,{I, rv1, rv2, rv3, rv4, rv5};

   l1: Line=(gun, Ppo, sp1, sp2, sp3, sp4, sp5);

   SELECT, Line=l1;
   TRACK, line=l1, beam=beam1, MAXSTEPS=500, DT=2.0e-13;
    RUN, method="PARALLEL-T", beam=beam1,
    fieldsolver=Fs1, distribution:=Dist1;
   ENDTRACK;

   SYSTEM,"mkdir -p scan0-" & STRING(I);
   SYSTEM,"mv scan-0.h5 scan-0.stat scan-0.lbal scan0-"
          & STRING(I);
   I=EVAL(I+1.0);
}
snuverink_j's avatar
snuverink_j committed
200
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
201 202 203 204 205 206 207


\section{Track Particles}
\label{sec:trackrun}
\index{RUN}

This command starts or continues the actual tracking:
snuverink_j's avatar
snuverink_j committed
208
\begin{verbatim}
snuverink_j's avatar
snuverink_j committed
209 210 211
RUN, METHOD=string, FIELDSOLVER=label, DISTRIBUTION=label-vector, BEAM=label,
FILE=string, TURNS=integer, MBMODE=string, PARAMB=float,
BOUNDARYGEOMETRY=string, MULTIPACTING=logical, OBJECTIVES=string-vector;
snuverink_j's avatar
snuverink_j committed
212
\end{verbatim}
snuverink_j's avatar
snuverink_j committed
213 214 215 216 217 218 219
The \texttt{RUN} command initialises tracking and uses the most recent
particle bunch for initial conditions.
The particle positions may be the result of previous tracking.

Its attributes are:
\begin{kdescription}
\item[METHOD]
snuverink_j's avatar
snuverink_j committed
220
  The name (a string, see Section~\ref{astring}) of the tracking method to be used.
snuverink_j's avatar
snuverink_j committed
221 222 223 224 225 226 227 228
  For the time being the following methods are known:
  \begin{kdescription}
    \ifthenelse{\boolean{ShowMap}}{
    \item[THIN]
    All elements are treated a s thin lenses.
    This is the fastest of the known method which do not lump elements.
    }{}
    \item[PARALLEL-T]
229
    This method puts \textit{OPAL} in \textit{OPAL-t} mode see~Chapter~\ref{opalt}.
snuverink_j's avatar
snuverink_j committed
230
    \item[CYCLOTRON-T]
231
    This method puts \textit{OPAL} in \textit{OPAL-cycl} mode see~Chapter~\ref{opalcycl}.
snuverink_j's avatar
snuverink_j committed
232
    \item[STATISTICAL-ERRORS]
233
    This is a method to let \textit{OPAL} run multiple times in parallel while adding imperfections to alignment and other physical quantities.
snuverink_j's avatar
snuverink_j committed
234 235
  \end{kdescription}
  \item[FIELDSOLVER]
snuverink_j's avatar
snuverink_j committed
236
  The field solver to be used see~Chapter~\ref{fieldsolver}.
snuverink_j's avatar
snuverink_j committed
237 238

  \item[DISTRIBUTION]
snuverink_j's avatar
snuverink_j committed
239
  The particle distribution to be used see~Chapter~\ref{distribution}.
snuverink_j's avatar
snuverink_j committed
240 241

  \item[BEAM]
snuverink_j's avatar
snuverink_j committed
242
  The particle beam see~Chapter~\ref{beam} to be used is specified.
snuverink_j's avatar
snuverink_j committed
243 244 245 246 247 248

  \item[FILE]
  The name of the file to be written (default="\texttt{track}").
  \item[TURNS]
  The number of turns (integer) to be tracked (default: 1, namely single bunch).

249
  In \textit{OPAL-cycl}, this parameter represents the number of bunches those will be injected into the cyclotron. In restart mode, the code
snuverink_j's avatar
snuverink_j committed
250 251 252 253 254
  firstly read an attribute $NumBunch$ from $.h5$ file which records how many bunches have already been injected. If $NumBunch$
  $<$ $TURNS$, the last $TURNS$$ -$ $NumBunch$ bunches will be injected in sequence by reading the initial distribution from $.h5$ file.

  \item[MBMODE]
  This defines which mode of multi-bunch runs. There are two options for it, namely, \texttt{AUTO} and \texttt{FORCE}.
snuverink_j's avatar
snuverink_j committed
255
  See Section~\ref{opalcycl:MultiBunch} for their explanations in detail.
snuverink_j's avatar
snuverink_j committed
256 257 258 259

  For restarting run with \texttt{TURNS} larger than one, if the existing bunches of the read-in step is large than one,
  the mode is forcedly set to \texttt{FORCE}. Otherwise, it is forcedly set to \texttt{AUTO}.

260
  This argument is available for \textit{OPAL-cycl}.
snuverink_j's avatar
snuverink_j committed
261 262 263 264

  \item[PARAMB]
   This is a control parameter to define when to start to transfer from single bunch to multi-bunches for \texttt{AUTO} mode (default: 5.0).

265
   This argument is only available for \texttt{AUTO} mode multi-bunch run in \textit{OPAL-cycl}.
snuverink_j's avatar
snuverink_j committed
266

snuverink_j's avatar
snuverink_j committed
267
   \item[MULTIPACTING] see~Chapter~\ref{multpact}\TODO{Describe attribute}
snuverink_j's avatar
snuverink_j committed
268
   \item[OBJECTIVES] An array of column names from the \filename{.stat} file used in \texttt{STATISTICAL-ERRORS} to compute mean value and standard deviation across all runs.
snuverink_j's avatar
snuverink_j committed
269 270 271 272 273 274 275 276 277 278
\end{kdescription}
Example:
\begin{verbatim}
run, file="table", turns=5, mbmode="AUTO", paramb=10.0,
     method="CYCLOTRON-T", beam=beam1, fieldsolver=Fs1,
     distribution=Dist1;
\end{verbatim}

This command tracks 5 bunches in cyclotron and writes the results on file \texttt{table}.

snuverink_j's avatar
snuverink_j committed
279
\subsection{\texttt{STATISTICAL-ERRORS}}
snuverink_j's avatar
snuverink_j committed
280 281
\label{ssec:statistical-errors}
\index{STATISTICAL-ERRORS}
snuverink_j's avatar
snuverink_j committed
282
This method can be used to quantify the effects of imperfections to alignment or other physical quantities such as e.g. the phase or the amplitude. It doesn't propagate the particles directly. Instead it scans through the input file and replaces all occurrences of \texttt[tab:realfun]{GAUSS} and \texttt[tab:realfun]{TGAUSS} with randomly generated values of appropriate distribution. Then one of the other methods, e.g. \texttt{PARALLEL-T} is called. These two steps are then repeated many times.
snuverink_j's avatar
snuverink_j committed
283

snuverink_j's avatar
snuverink_j committed
284
To use this method one has to specify the \texttt{METHOD} using the following form:
snuverink_j's avatar
snuverink_j committed
285 286 287 288 289
\begin{center}
\texttt{STATISTICAL-ERRORS(<track{\textunderscore}method>, <ncores>, <nruns>)},
\end{center}
\noindent where \texttt{<track{\textunderscore}method>} is the method that should track the particles, \texttt{<ncores>} is the number of cores used for a run and \texttt{<nruns>} is the number of individual runs that should be performed. \textbf{It should be noted that the total number of cores available has to be greater or equal to \texttt{ncores} + 1.} One core is needed to manage the distribution of tasks and to collect the results. The other cores are used to perform the simulations. If in total $N \times \texttt{ncores} + 1$ cores are available then $N$ individual runs are processed in parallel each using \texttt{ncores}.

snuverink_j's avatar
snuverink_j committed
290
\sloppy For each run of the method \texttt{STATISTICAL-ERRORS} a unique base name is generated of the form \filename{foo}. Each individual run is then performed in a directory \filename{foo{\textunderscore}run{\textunderscore}ddddd}. The files that are produced by the \texttt{<track{\textunderscore}method>} are kept. \textbf{This can lead to a large amount of data especially when snapshots of the phase space are stored frequently. The user should make sure that the file system can handle the amount of data or set the option \texttt{PSDUMPFREQ} to a big number.}
snuverink_j's avatar
snuverink_j committed
291

snuverink_j's avatar
snuverink_j committed
292
In the end the method \texttt{STATISTICAL-ERRORS} computes the mean and the standard deviation for each variable in the array \texttt{OBJECTIVES} along the machine and stores this information in to the \filename{.stat} file.
snuverink_j's avatar
snuverink_j committed
293
\input{footer}