track.tex 13.7 KB
 snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 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}  snuverink_j committed Sep 07, 2017 24  \tabline{TIMEINTEGRATOR}{Defines the time integrator used in \textit{OPAL-cycl}}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 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 committed Sep 06, 2017 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.  snuverink_j committed Sep 07, 2017 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 committed Sep 06, 2017 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 committed Sep 06, 2017 45 in \texttt{DT}, \texttt{MAXSTEPS} and \texttt{ZSTOP}. This can be used to change the time step manually.  snuverink_j committed Sep 06, 2017 46 47 48 49 50  The attributes of the command are: \begin{kdescription} \item[LINE]  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 53 \item[BEAM]  snuverink_j committed Sep 06, 2017 54 55  \sloppy The named \texttt{BEAM} command defines the particle mass, charge and reference momentum (default: \texttt{UNNAMED\_BEAM}).  snuverink_j committed Sep 06, 2017 56 57  \index{UNNAMED\_BEAM} \item[T0]  snuverink_j committed Sep 08, 2017 58  The initial time [{s}] of the simulation, its default value is 0.  snuverink_j committed Sep 06, 2017 59 \item[DT]  snuverink_j committed Sep 08, 2017 60  Array of time step sizes for tracking, default length of the array is 1 and its only value is {1}{ps}.  snuverink_j committed Sep 06, 2017 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 committed Sep 08, 2017 64  Initial position of the reference particle along the reference trajectory, default position is {0.0}{m}.  snuverink_j committed Sep 06, 2017 65 \item[ZSTOP]  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 67 68  \item[TIMEINTEGRATOR]  snuverink_j committed Sep 07, 2017 69  Define the time integrator. Currently only available in \textit{OPAL-cycl}.  snuverink_j committed Sep 06, 2017 70  The valid options are \texttt{RK-4}, \texttt{LF-2} and \texttt{MTS}:  snuverink_j committed Sep 06, 2017 71  \begin{kdescription}  snuverink_j committed Sep 07, 2017 72  \item[RK-4] the fourth-order Runge-Kutta integrator. This is the default integrator for \textit{OPAL-cycl}.  snuverink_j committed Sep 06, 2017 73  \item[LF-2] the second-order Boris-Buneman (leapfrog-like) integrator.  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 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 committed Sep 06, 2017 79  The outer step (determined by \texttt{STEPSPERTURN}) is used to integrate space charge effects.  snuverink_j committed Sep 06, 2017 80  A constant number of sub-steps per outer step is used to query external fields and to move the particles.  snuverink_j committed Sep 06, 2017 81  The number of sub-steps can be set with the option \texttt{MTSSUBSTEPS} and its default value is 1.  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 84 85  \texttt{LF-2} or \texttt{RK-4} read \begin{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 96 \end{verbatim}  snuverink_j committed Sep 06, 2017 97 and should be transformed to  snuverink_j committed Sep 06, 2017 98 \begin{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 110 \end{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 115 How large \texttt{MTSSUBSTEPS} can be chosen of course depends on the importance of space charge effects.  snuverink_j committed Sep 06, 2017 116 117 118  \end{kdescription} \item[STEPSPERTURN]  snuverink_j committed Sep 07, 2017 119  Number of time steps per revolution period. Only available for \textit{OPAL-cycl}, default value is 720.  snuverink_j committed Sep 06, 2017 120 121 122 123  \end{kdescription} \ifthenelse{\boolean{ShowMap}}{  snuverink_j committed Sep 07, 2017 124 In \textit{OPAL-t} and \textit{OPAL-map}, the command format is:  snuverink_j committed Sep 06, 2017 125 \begin{verbatim}  snuverink_j committed Sep 06, 2017 126 TRACK, LINE=name, BEAM=name, MAXSTEPS=value, DT=value;  snuverink_j committed Sep 06, 2017 127 \end{verbatim}  snuverink_j committed Sep 06, 2017 128 129 }{}  snuverink_j committed Sep 07, 2017 130 In \textit{OPAL-cycl}, instead of setting time step, the time steps per-turn should be set.  snuverink_j committed Sep 06, 2017 131 The command format is:  snuverink_j committed Sep 06, 2017 132 \begin{verbatim}  snuverink_j committed Sep 06, 2017 133 TRACK, LINE=name, BEAM=name, MAXSTEPS=value, STEPSPERTURN=value;  snuverink_j committed Sep 06, 2017 134 \end{verbatim}  snuverink_j committed Sep 06, 2017 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.  snuverink_j committed Sep 07, 2017 139 \textit{OPAL} leaves \textbf{track mode} when it sees the command  snuverink_j committed Sep 06, 2017 140 \begin{verbatim}  snuverink_j committed Sep 06, 2017 141  ENDTRACK;  snuverink_j committed Sep 06, 2017 142 \end{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 151 \begin{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 200 \end{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 208 \begin{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 212 \end{verbatim}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 220  The name (a string, see Section~\ref{astring}) of the tracking method to be used.  snuverink_j committed Sep 06, 2017 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]  snuverink_j committed Sep 07, 2017 229  This method puts \textit{OPAL} in \textit{OPAL-t} mode see~Chapter~\ref{opalt}.  snuverink_j committed Sep 06, 2017 230  \item[CYCLOTRON-T]  snuverink_j committed Sep 07, 2017 231  This method puts \textit{OPAL} in \textit{OPAL-cycl} mode see~Chapter~\ref{opalcycl}.  snuverink_j committed Sep 06, 2017 232  \item[STATISTICAL-ERRORS]  snuverink_j committed Sep 07, 2017 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 committed Sep 06, 2017 234 235  \end{kdescription} \item[FIELDSOLVER]  snuverink_j committed Sep 06, 2017 236  The field solver to be used see~Chapter~\ref{fieldsolver}.  snuverink_j committed Sep 06, 2017 237 238  \item[DISTRIBUTION]  snuverink_j committed Sep 06, 2017 239  The particle distribution to be used see~Chapter~\ref{distribution}.  snuverink_j committed Sep 06, 2017 240 241  \item[BEAM]  snuverink_j committed Sep 06, 2017 242  The particle beam see~Chapter~\ref{beam} to be used is specified.  snuverink_j committed Sep 06, 2017 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).  snuverink_j committed Sep 07, 2017 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 committed Sep 06, 2017 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 committed Sep 06, 2017 255  See Section~\ref{opalcycl:MultiBunch} for their explanations in detail.  snuverink_j committed Sep 06, 2017 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}.  snuverink_j committed Sep 07, 2017 260  This argument is available for \textit{OPAL-cycl}.  snuverink_j committed Sep 06, 2017 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).  snuverink_j committed Sep 07, 2017 265  This argument is only available for \texttt{AUTO} mode multi-bunch run in \textit{OPAL-cycl}.  snuverink_j committed Sep 06, 2017 266   snuverink_j committed Sep 06, 2017 267  \item[MULTIPACTING] see~Chapter~\ref{multpact}\TODO{Describe attribute}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 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 committed Sep 08, 2017 279 \subsection{\texttt{STATISTICAL-ERRORS}}  snuverink_j committed Sep 06, 2017 280 281 \label{ssec:statistical-errors} \index{STATISTICAL-ERRORS}  snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 283   snuverink_j committed Sep 06, 2017 284 To use this method one has to specify the \texttt{METHOD} using the following form:  snuverink_j committed Sep 06, 2017 285 286 287 288 289 \begin{center} \texttt{STATISTICAL-ERRORS(, , )}, \end{center} \noindent where \texttt{} is the method that should track the particles, \texttt{} is the number of cores used for a run and \texttt{} 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 committed Sep 06, 2017 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{} 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 committed Sep 06, 2017 291   snuverink_j committed Sep 06, 2017 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 committed Sep 06, 2017 293 \input{footer}