distribution.tex 46 KB
 snuverink_j committed Sep 06, 2017 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 %% NOT DOCUMENTED YET: %% MX, MY, MT, EX, EY, ET, E2, RESIDUUM, MAXSTEPSCO, MAXSTEPSSI, ORDERMAPS, %% MAGSYM, CORRT, R, FLIPX, FLIPY, ROTATE90, ROTATE180, ROTATE270, NPDARKCUR, %% INWARDMARGIN, EINITHR, FNA, FNB, FNY, FNVYZERO, FNYSECOND, FNPHIW, FNBETA, %% FNFIELDTHR, FNMAXEMI, SECONDARYFLAG, NEMISSIONMODE, VSEYZERO, VEZERO, %% VSEYMAX, VEMAX, VKENERGY, VKTHETA, VVTHERMAL, VW, SURFMATERIAL \input{header} \chapter{Distribution Command} \label{chp:distribution} \index{Distribution Command|(} \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 16  \caption{Possible distribution types. Note that the \texttt{SURFACEEMISSION} and \texttt{SURFACERANDCREATE}  snuverink_j committed Sep 06, 2017 17 18 19 20 21  distribution types will not be discussed in this chapter. Instead, refer to \chpref{femiss} on field emission for using these types.} \label{tab:disttypes} \begin{tabularx}{\textwidth-1cm}{|l|X|} \hline  snuverink_j committed Sep 11, 2017 22  \tabhead Distribution Type & Description \\  snuverink_j committed Sep 06, 2017 23  \hline  snuverink_j committed Sep 11, 2017 24 25  \texttt{FROMFILE} & Initial distribution read in from text file provided by user see~Section~\ref{fromfiledisttype}. \\  snuverink_j committed Sep 06, 2017 26  %\hline  snuverink_j committed Sep 11, 2017 27 28  \texttt{GAUSS} & Initial distribution generated using Gaussian distribution(s) see~Section~\ref{gaussdisttype}. \\  snuverink_j committed Sep 06, 2017 29  %\hline  snuverink_j committed Sep 11, 2017 30 31  \texttt{FLATTOP} & Initial distribution generated using flattop distribution(s) see~Section~\ref{flattopdisttype}. \\  snuverink_j committed Sep 06, 2017 32  %\hline  snuverink_j committed Sep 11, 2017 33 34  \texttt{BINOMIAL} & Initial distribution generated using binomial distribution(s) see~Section~\ref{binomialdisttype}. \\  snuverink_j committed Sep 06, 2017 35  %\hline  snuverink_j committed Sep 11, 2017 36  \texttt{SURFACEEMISSION} & For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead \chpref{femiss}. \\  snuverink_j committed Sep 06, 2017 37  %\hline  snuverink_j committed Sep 11, 2017 38  \texttt{SURFACERANDCREATE} & For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead \chpref{femiss}. \\  snuverink_j committed Sep 06, 2017 39  %\hline  snuverink_j committed Sep 11, 2017 40  \texttt{GUNGAUSSFLATTOPTH} & Legacy. Special case of \texttt{FLATTOP} distribution see~Section~\ref{gungaussflattopthdisttype}. \\  snuverink_j committed Sep 06, 2017 41  %\hline  snuverink_j committed Sep 11, 2017 42  \texttt{ASTRAFLATTOPTH} & Legacy. Special case of \texttt{FLATTOP} distribution see~Section~\ref{astraflattopthdisttype}. \\  snuverink_j committed Sep 06, 2017 43 44 45 46 47  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 07, 2017 48 The distribution command is used to introduce particles into an \textit{OPAL} simulation. Like other \textit{OPAL}  snuverink_j committed Sep 06, 2017 49 commands see~Chapter~\ref{format}, the distribution command is of the form:  snuverink_j committed Sep 06, 2017 50   snuverink_j committed Sep 06, 2017 51 \begin{verbatim}  snuverink_j committed Sep 06, 2017 52 53 54 55 56 57 58 Name:DISTRIBUTION, TYPE = DISTRIBUTION_TYPE, ATTRIBUTE #1 =, ATTRIBUTE #2 =, . . . ATTRIBUTE #N =;  snuverink_j committed Sep 06, 2017 59 \end{verbatim}  snuverink_j committed Sep 07, 2017 60 The distribution is given a name (which is used to reference the distribution in the \textit{OPAL} input  snuverink_j committed Sep 06, 2017 61 file), a distribution type, and a list of attributes. The types of distributions that are supported  snuverink_j committed Sep 06, 2017 62 are listed in Table~\ref{disttypes}. The attributes that follow the distribution type further  snuverink_j committed Sep 06, 2017 63 64 65 66 67 68 69 70 71 72 define the particle distribution. Some attributes are universal, while others are specific to the distribution type. In the following sections we will define the distribution attributes, starting with the general, or universal attributes. (Note that, in general, if a distribution type does not support a particular attribute, defining a value for it does no harm. That attribute just gets ignored.) \section{Units} \label{sec:unitsdistattributes} \index{Distribution!Units} \FloatBarrier  snuverink_j committed Sep 07, 2017 73 74 The internal units used by \textit{OPAL-t} and \textit{OPAL-cycl} are described in Section~\ref{variablesopalt,variablesopalcycl}. When defining a distribution, both \textit{OPAL-t} and \textit{OPAL-cycl} use meters for  snuverink_j committed Sep 06, 2017 75 length and seconds for time. However, there are different options for the units used to input the  snuverink_j committed Sep 06, 2017 76 momentum. This is controlled with the \texttt{INPUTMOUNITS} attribute, defined in  snuverink_j committed Sep 06, 2017 77 Table~\ref{distattrinputmounits}.  snuverink_j committed Sep 06, 2017 78 79 80  \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 81  \caption{Definition of \texttt{INPUTMOUNITS} attribute.}  snuverink_j committed Sep 06, 2017 82 83 84  \label{tab:distattrinputmounits} \begin{tabularx}{\textwidth-1cm}{|l|c|X|} \hline  snuverink_j committed Sep 11, 2017 85  \tabhead Attribute Name & Value & Description \\  snuverink_j committed Sep 06, 2017 86  \hline  snuverink_j committed Sep 11, 2017 87 88  \texttt{INPUTMOUNITS} & \texttt{NONE} (default for \textit{OPAL-t}) & Use no units for the input momentum (e.g. $p_{x}$, $p_{y}$, $p_{z}$). Momentum is given as $\beta_{x} \gamma$, $\beta_{y} \gamma$ and $\beta_{z} \gamma$, as in Section~\ref{variablesopalt}. \\ \texttt{INPUTMOUNITS} & \index{INPUTMOUNITS} \texttt{EV} (default for \textit{OPAL-cycl}) & Use the units {eV} for the input momentum (e.g. $p_{x}$, $p_{y}$, $p_{z}$). \\  snuverink_j committed Sep 06, 2017 89 90 91 92 93 94 95 96 97 98  \hline \end{tabularx} \end{center} \end{table} \section{General Distribution Attributes} \label{sec:gendistattributes} \index{Distribution!General Attributes} \FloatBarrier  snuverink_j committed Sep 06, 2017 99 100 Once the distribution type is chosen, the next attribute to specify is the \texttt{EMITTED} attribute, which is defined in Table~\ref{distattremitted}. The \texttt{EMITTED} attribute  snuverink_j committed Sep 06, 2017 101 102 103 controls whether a distribution is \emph{injected} or \emph{emitted}. An \emph{injected} distribution is placed in its entirety into the simulation space at the start of the simulation. An \emph{emitted} beam is emitted into the simulation over time as the simulation progresses (e.g.  snuverink_j committed Sep 07, 2017 104 from a cathode in a photoinjector simulation). Currently, only \textit{OPAL-t} supports \emph{emitted}  snuverink_j committed Sep 06, 2017 105 106 107 108 distributions. The default is an \emph{injected} distribution. \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 109  \caption{Definition of \texttt{EMITTED} attribute.}  snuverink_j committed Sep 06, 2017 110 111 112  \label{tab:distattremitted} \begin{tabularx}{\textwidth-1cm}{|l|c|X|} \hline  snuverink_j committed Sep 11, 2017 113  \tabhead Attribute Name & Value & Description \\  snuverink_j committed Sep 06, 2017 114  \hline  snuverink_j committed Sep 11, 2017 115  \texttt{EMITTED} & \index{EMITTED} \texttt{FALSE} (default) & The distribution is injected into the simulation in its entirety  snuverink_j committed Sep 06, 2017 116  at the start of the simulation. The particle coordinates for an injected distribution are defined as in  snuverink_j committed Sep 07, 2017 117  Section~\ref{variablesopalt,variablesopalcycl}. Note that in \textit{OPAL-t} the entire distribution will automatically  snuverink_j committed Sep 11, 2017 118  be shifted to ensure that the $z$ coordinate will be greater than zero for all particles. \\  snuverink_j committed Sep 06, 2017 119  %\hline  snuverink_j committed Sep 11, 2017 120  \texttt{EMITTED} & \texttt{TRUE} & The distribution is emitted into the simulation over time as the simulation  snuverink_j committed Sep 07, 2017 121  progresses. Currently only \textit{OPAL-t} supports this type of distribution. In this case, the longitudinal coordinate, as  snuverink_j committed Sep 11, 2017 122  defined by Section~\ref{variablesopalt}, is given in seconds instead of meters. Early times are emitted first. \\  snuverink_j committed Sep 06, 2017 123 124 125 126 127  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 128 Depending on the \texttt{EMITTED} attribute, we can specify several other attributes that do not depend on the  snuverink_j committed Sep 06, 2017 129 130 distribution type. These are defined in Section~\ref{universaldistattributes,injecteddistattributes,emitteddistattributes} in Table~\ref{distattruniversal,distattrinjected,distattrsemitted}.  snuverink_j committed Sep 06, 2017 131 132 133 134 135 136 137 138 139 140 141 \clearpage \subsection{Universal Attributes} \label{sec:universaldistattributes} \index{Distribution!Universal Attributes} \begin{table}[!htb] \begin{center}\footnotesize \caption{Definition of universal distribution attributes. Any distribution type can use these and they are the same whether the beam is \emph{injected} or \emph{emitted}.} \label{tab:distattruniversal} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 142  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 143  \hline  snuverink_j committed Sep 11, 2017 144  \texttt{WRITETOFILE} & \index{WRITETOFILE} \texttt{FALSE} & None & Echo initial distribution to text file \textit{data/\textless basename \textgreater\_ DIST.dat}. \\  snuverink_j committed Sep 06, 2017 145  %\hline  snuverink_j committed Sep 11, 2017 146  \texttt{SCALABLE} & \index{SCALABLE} \texttt{FALSE} & None & Makes the generation scalable with respect of number of particles. The result depends on the number of cores used. \\  snuverink_j committed Sep 06, 2017 147  %  snuverink_j committed Sep 11, 2017 148  \texttt{WEIGHT} & {1.0} & None & Weight of distribution when used in a distribution list see~Section~\ref{distlist}. \\  snuverink_j committed Sep 06, 2017 149  %\hline  snuverink_j committed Sep 11, 2017 150 151  \texttt{NBIN} & {0} & None & The distribution (beam) will be broken up into \texttt{NBIN} energy bins. This has consequences for the space charge solver see~Section~\ref{FSENBINS}. \\  snuverink_j committed Sep 06, 2017 152  %\hline  snuverink_j committed Sep 11, 2017 153 154  \texttt{XMULT} & \index{XMULT} {1.0} & None & Value used to scale the $x$ positions of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 155  %\hline  snuverink_j committed Sep 11, 2017 156 157  \texttt{YMULT} & \index{YMULT} {1.0} & None & Value used to scale the $y$ positions of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 158  %\hline  snuverink_j committed Sep 11, 2017 159 160  \texttt{PXMULT} & \index{PXMULT} {1.0} & None & Value used to scale the x momentum, $p_{x}$, of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 161  %\hline  snuverink_j committed Sep 11, 2017 162 163  \texttt{PYMULT} & \index{PYMULT} {1.0} & None & Value used to scale the y momentum, $p_{y}$, of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 164  %\hline  snuverink_j committed Sep 11, 2017 165 166  \texttt{PZMULT} & \index{PZMULT} {1.0} & None & Value use to scale the z momentum, $p_{z}$, of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 167  %\hline  snuverink_j committed Sep 11, 2017 168 169  \texttt{OFFSETX} & \index{OFFSETX} {0.0} & {m} & Distribution is shifted in $x$ by this amount after the distribution is generated (or read in). Same as the average $x$ position, $\bar{x}$. \\  snuverink_j committed Sep 06, 2017 170  %\hline  snuverink_j committed Sep 11, 2017 171 172  \texttt{OFFSETY} & \index{OFFSETY} {0.0} & {m} & Distribution is shifted in $y$ by this amount after the distribution is generated (or read in). Same as the average $y$ position, $\bar{y}$. \\  snuverink_j committed Sep 06, 2017 173  %\hline  snuverink_j committed Sep 11, 2017 174  \texttt{OFFSETPX} & \index{OFFSETPX} {0.0} & Section~\ref{unitsdistattributes} &  snuverink_j committed Sep 06, 2017 175  Distribution is shifted in $p_{x}$ by this amount after the distribution is generated (or read in). Same as the  snuverink_j committed Sep 11, 2017 176  average $p_{x}$ value, $\bar{p}_{x}$. \\  snuverink_j committed Sep 06, 2017 177  %\hline  snuverink_j committed Sep 11, 2017 178  \texttt{OFFSETPY} & \index{OFFSETPY} {0.0} & Section~\ref{unitsdistattributes} &  snuverink_j committed Sep 06, 2017 179  Distribution is shifted in $p_{y}$ by this amount after the distribution is generated (or read in). Same as the  snuverink_j committed Sep 11, 2017 180  average $p_{y}$ value, $\bar{p}_{y}$. \\  snuverink_j committed Sep 06, 2017 181  %\hline  snuverink_j committed Sep 11, 2017 182  \texttt{OFFSETPZ} & \index{OFFSETPZ} {0.0} & Section~\ref{unitsdistattributes} &  snuverink_j committed Sep 06, 2017 183  Distribution is shifted in $p_{z}$ by this amount after the distribution is generated (or read in). Same as the  snuverink_j committed Sep 11, 2017 184  average $p_{z}$ value, $\bar{p}_{z}$. \\  snuverink_j committed Sep 06, 2017 185  %\hline  snuverink_j committed Sep 11, 2017 186 187  \texttt{ID1} & \index{ID1} {0.0} & Section~\ref{unitsdistattributes} & Tracer particle which is written also into {\em data/track\_orbit.dat} \\  snuverink_j committed Sep 06, 2017 188  %\hline  snuverink_j committed Sep 11, 2017 189 190  \texttt{ID2} & \index{ID2} {0.0} & Section~\ref{unitsdistattributes} & Tracer particle which is written also into {\em data/track\_orbit.dat} \\  snuverink_j committed Sep 06, 2017 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205  \hline \end{tabularx} \end{center} \end{table} \subsection{Injected Distribution Attributes} \label{sec:injecteddistattributes} \index{Distribution!Injected Beam} \begin{table}[!htb] \begin{center}\footnotesize \caption{Definition of distribution attributes that only affect \emph{injected} beams.} \label{tab:distattrinjected} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 206  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 207  \hline  snuverink_j committed Sep 11, 2017 208 209  \texttt{ZMULT} & \index{ZMULT} {1.0} & None & Value used to scale the $z$ positions of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 210  %\hline  snuverink_j committed Sep 11, 2017 211  \texttt{OFFSETZ} & \index{OFFSETZ} {0.0} & {m} & Distribution is shifted in $z$ by this amount relative to the reference particle. Same as the average $z$ position, $\bar{z}$. \\  snuverink_j committed Sep 06, 2017 212 213 214 215 216 217 218 219 220 221 222 223 224 225  \hline \end{tabularx} \end{center} \end{table} \subsection{Emitted Distribution Attributes} \label{sec:emitteddistattributes} \index{Distribution!Emitted Beam} \begin{table}[!htb] \begin{center}\footnotesize \caption{Definition of distribution attributes that only affect \emph{emitted} beams.} \label{tab:distattrsemitted} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 226  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 227  \hline  snuverink_j committed Sep 11, 2017 228 229  \texttt{TMULT} & \index{TMULT} {1.0} & None & Value used to scale the $t$ values of the distribution particles. Applied after the distribution is generated (or read in). \\  snuverink_j committed Sep 06, 2017 230  %\hline  snuverink_j committed Sep 11, 2017 231  \texttt{OFFSETT} & \index{OFFSETT} {0.0} & {s} & Distribution is emitted later by this amount relative to the reference particle. \\  snuverink_j committed Sep 06, 2017 232  %\hline  snuverink_j committed Sep 11, 2017 233  \texttt{EMISSIONSTEPS} & \index{EMISSIONSTEPS} {1} & None & Number of time steps to take during emission. The simulation time step  snuverink_j committed Sep 06, 2017 234  will be adjusted during emission to ensure that this many time steps will be  snuverink_j committed Sep 11, 2017 235  required to emit the entire distribution. \\  snuverink_j committed Sep 06, 2017 236  %\hline  snuverink_j committed Sep 11, 2017 237 238  \texttt{EMISSIONMODEL} & \index{EMISSIONMODEL} None & None & Emission model to use when emitting particles from cathode see~Section~\ref{emissionmodel}. \\  snuverink_j committed Sep 06, 2017 239 240 241 242 243  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 08, 2017 244 \section{\texttt{FROMFILE} Distribution Type}  snuverink_j committed Sep 06, 2017 245 246 247 248 \label{sec:fromfiledisttype} \index{Distribution!FROMFILE} \FloatBarrier  snuverink_j committed Sep 07, 2017 249 250 The most versatile distribution type is to use a user generated text file as input to \textit{OPAL}. This allows the user to generate their own distribution, if the built in options in \textit{OPAL} are insufficient,  snuverink_j committed Sep 06, 2017 251 and have it either \emph{injected} or \emph{emitted} into the simulation. In Table~\ref{distattrfromfile}  snuverink_j committed Sep 06, 2017 252 253 254 255 we list the single attribute specific to this type of distribution type. \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 256  \caption{Definition of distribution attributes for a \texttt{FROMFILE} distribution type.}  snuverink_j committed Sep 06, 2017 257 258 259  \label{tab:distattrfromfile} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 260  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 261  \hline  snuverink_j committed Sep 11, 2017 262  \texttt{FNAME} & \index{FNAME} None & None & File name for text file containing distribution particle coordinates. \\  snuverink_j committed Sep 06, 2017 263 264 265 266 267  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 268 An example of an \emph{injected} \texttt{FROMFILE} distribution definition is:  snuverink_j committed Sep 06, 2017 269   snuverink_j committed Sep 06, 2017 270 \begin{verbatim}  snuverink_j committed Sep 06, 2017 271 Name:DISTRIBUTION, TYPE = FROMFILE,  snuverink_j committed Sep 12, 2017 272  FNAME = "text file name";  snuverink_j committed Sep 06, 2017 273 274 \end{verbatim} an example of an \emph{emitted} \texttt{FROMFILE} distribution definition is:  snuverink_j committed Sep 06, 2017 275   snuverink_j committed Sep 06, 2017 276 \begin{verbatim}  snuverink_j committed Sep 06, 2017 277 Name:DISTRIBUTION, TYPE = FROMFILE,  snuverink_j committed Sep 12, 2017 278  FNAME = "text file name",  snuverink_j committed Sep 06, 2017 279 280  EMITTED = TRUE, EMISSIONMODEL = None;  snuverink_j committed Sep 06, 2017 281 \end{verbatim}  snuverink_j committed Sep 06, 2017 282   snuverink_j committed Sep 06, 2017 283 The text input file for the \texttt{FROMFILE} distribution type has slightly a slightly different  snuverink_j committed Sep 06, 2017 284 format, depending on whether the distribution is to be \emph{injected} or \emph{emitted}. The  snuverink_j committed Sep 06, 2017 285 286 \emph{injected} file format is defined in Table~\ref{fromfileinjfileformat}. The \emph{emitted} file format is defined in Table~\ref{fromfileemitfileformat}.  snuverink_j committed Sep 06, 2017 287 288 289  \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 290  \caption{File format for \emph{injected} \texttt{FROMFILE} distribution type. N is the number  snuverink_j committed Sep 06, 2017 291  of particles in the file. The particle coordinates are defined in Section~\ref{variablesopalt,variablesopalcycl}.}  snuverink_j committed Sep 06, 2017 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307  \label{tab:fromfileinjfileformat} \begin{tabular}{llllll} \hline N & & & & & \\ $x_{1}$ & $p_{x1}$ & $y_{1}$ & $p_{y1}$ & $z_{1}$ & $p_{z1}$ \\ $x_{2}$ & $p_{x2}$ & $y_{2}$ & $p_{y2}$ & $z_{2}$ & $p_{z2}$ \\ . & & & & & \\ . & & & & & \\ $x_{N}$ & $p_{xN}$ & $y_{N}$ & $p_{yN}$ & $z_{N}$ & $p_{zN}$ \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 308  \caption{File format for \emph{emitted} \texttt{FROMFILE} distribution type. N is the number  snuverink_j committed Sep 06, 2017 309  of particles in the file. The particle coordinates are defined in Section~\ref{variablesopalt}  snuverink_j committed Sep 06, 2017 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324  except that $z$, in meters, is replaced by $t$ in seconds.} \label{tab:fromfileemitfileformat} \begin{tabular}{llllll} \hline N & & & & & \\ $x_{1}$ & $p_{x1}$ & $y_{1}$ & $p_{y1}$ & $t_{1}$ & $p_{z1}$ \\ $x_{2}$ & $p_{x2}$ & $y_{2}$ & $p_{y2}$ & $t_{2}$ & $p_{z2}$ \\ . & & & & & \\ . & & & & & \\ $x_{N}$ & $p_{xN}$ & $y_{N}$ & $p_{yN}$ & $t_{N}$ & $p_{zN}$ \\ \hline \end{tabular} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 325 Note that for an \emph{emitted} \texttt{FROMFILE} distribution, all of the particle's time, $t$, coordinates  snuverink_j committed Sep 06, 2017 326 327 328 will be shifted to negative time (if they are not there already). The simulation clock will then start at $t = 0$ and distribution particles will be emitted into the simulation as the simulation progresses. Also note that, as the particles are emitted, they will be modified according to the type of emission model used. This is defined  snuverink_j committed Sep 06, 2017 329 330 by the attribute \texttt{EMISSIONMODEL}, which is described in Section~\ref{emissionmodel}. A choice of \texttt{NONE} for the \texttt{EMISSIONMODEL} (which is the default) can be defined so as not to affect the  snuverink_j committed Sep 06, 2017 331 332 333 distribution coordinates at all.  snuverink_j committed Sep 06, 2017 334 To maintain consistency $N$ and \texttt{NPART} from the \texttt{BEAM} command in \chpref{beam} must be equal.  snuverink_j committed Sep 06, 2017 335   snuverink_j committed Sep 08, 2017 336 \section{\texttt{GAUSS} Distribution Type}  snuverink_j committed Sep 06, 2017 337 338 339 340 \label{sec:gaussdisttype} \index{Distribution!GAUSS|(} \FloatBarrier  snuverink_j committed Sep 06, 2017 341 As the name implies, the \texttt{GAUSS} distribution type can generate distributions with a general  snuverink_j committed Sep 06, 2017 342 343 344 Gaussian shape (here we show a one-dimensional example): \begin{equation*}  snuverink_j committed Sep 08, 2017 345  f(x) = \frac{1}{\sqrt{2 \pi}} e^{-\frac{(x - \bar{x})^{2}}{2 \sigma_{x}^{2}}}  snuverink_j committed Sep 06, 2017 346 \end{equation*}  snuverink_j committed Sep 06, 2017 347 348 where $\bar{x}$ is the average value of $x$. However, the \texttt{GAUSS} distribution can also be used to generate an emitted beam with a flat top time profile. We will go over the various options for the \texttt{GAUSS}  snuverink_j committed Sep 06, 2017 349 350 distribution type in this section.  snuverink_j committed Sep 08, 2017 351 \subsection{Simple \texttt{GAUSS} Distribution Type}  snuverink_j committed Sep 06, 2017 352 We will begin by describing how to create a simple \texttt{GAUSS} distribution type. That is, a simple  snuverink_j committed Sep 06, 2017 353 354 355 356 6-dimensional distribution with a Gaussian distribution in all dimensions. \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 357  \caption{Definition of the basic distribution attributes for a \texttt{GAUSS} distribution type.}  snuverink_j committed Sep 06, 2017 358 359 360  \label{tab:distattrgauss} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 361  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 362  \hline  snuverink_j committed Sep 11, 2017 363  \texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & RMS width, $\sigma_{x}$, in transverse $x$ direction. \\  snuverink_j committed Sep 06, 2017 364  %\hline  snuverink_j committed Sep 11, 2017 365  \texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & RMS width, $\sigma_{y}$, in transverse $y$ direction. \\  snuverink_j committed Sep 06, 2017 366  %\hline  snuverink_j committed Sep 11, 2017 367 368  \texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & RMS radius, $\sigma_{r}$, in radial direction. If nonzero \texttt{SIGMAR} overrides \texttt{SIGMAX} and \texttt{SIGMAY}. \\  snuverink_j committed Sep 06, 2017 369  %\hline  snuverink_j committed Sep 11, 2017 370 371  \texttt{SIGMAZ} & \index{SIGMAZ} {0.0} & {m} & RMS length, $\sigma_{z}$, in longitudinal (z) direction. \texttt{SIGMAZ} is used for an \emph{injected} distribution. \\  snuverink_j committed Sep 06, 2017 372  %\hline  snuverink_j committed Sep 11, 2017 373 374  \texttt{SIGMAT} & \index{SIGMAT} {0.0} & {s} & RMS width, $\sigma_{t}$, in time (t). \texttt{SIGMAT} is used for an \emph{emitted} distribution. \\  snuverink_j committed Sep 06, 2017 375  %\hline  snuverink_j committed Sep 11, 2017 376  \texttt{SIGMAPX} & \index{SIGMAPX} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{px}$ for defining distribution. \\  snuverink_j committed Sep 06, 2017 377  %\hline  snuverink_j committed Sep 11, 2017 378  \texttt{SIGMAPY} & \index{SIGMAPY} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{py}$ for defining distribution. \\  snuverink_j committed Sep 06, 2017 379  %\hline  snuverink_j committed Sep 11, 2017 380  \texttt{SIGMAPZ} & \index{SIGMAPZ} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{pz}$ for defining distribution. \\  snuverink_j committed Sep 06, 2017 381  %\hline  snuverink_j committed Sep 11, 2017 382 383  \texttt{CUTOFFX} & \index{CUTOFFX} {3.0} & None & Defines transverse distribution cutoff in the $x$ direction in units of $\sigma_{x}$. If \texttt{CUTOFFX} $= 0$ then actual cutoff in $x$ is set to infinity. \\  snuverink_j committed Sep 06, 2017 384  %\hline  snuverink_j committed Sep 11, 2017 385 386  \texttt{CUTOFFY} & \index{CUTOFFY} {3.0} & None & Defines transverse distribution cutoff in the $y$ direction in units of $\sigma_{y}$. If \texttt{CUTOFFY} $= 0$ then actual cutoff in $y$ is set to infinity. \\  snuverink_j committed Sep 06, 2017 387  %\hline  snuverink_j committed Sep 11, 2017 388  \texttt{CUTOFFR} & \index{CUTOFFR} {3.0} & None & Defines transverse distribution cutoff in the $r$ direction in units of  snuverink_j committed Sep 08, 2017 389  $\sigma_{r}$. If \texttt{CUTOFFR} $= 0$ then actual cutoff in $r$ is set to infinity. \texttt{CUTOFFR} is  snuverink_j committed Sep 11, 2017 390  only used if \texttt{SIGMAR} $>0$. \\  snuverink_j committed Sep 06, 2017 391  %\hline  snuverink_j committed Sep 11, 2017 392  \texttt{CUTOFFLONG} & \index{CUTOFFLONG} {3.0} & None & Defines longitudinal distribution cutoff in the $z$ or $t$ direction  snuverink_j committed Sep 08, 2017 393  (\emph{injected} or \emph{emitted}) in units of $\sigma_{z}$ or $\sigma_{t}$. \texttt{CUTOFFLONG} is  snuverink_j committed Sep 11, 2017 394  different from other dimensions in that a value of {0.0} does not imply a cutoff value of infinity. \\  snuverink_j committed Sep 06, 2017 395  %\hline  snuverink_j committed Sep 11, 2017 396 397  \texttt{CUTOFFPX} & \index{CUTOFFPX} {3.0} & None & Defines cutoff in $p_{x}$ dimension in units of $\sigma_{px}$. If \texttt{CUTOFFPX} $= 0$ then actual cutoff in $p_{x}$ is set to infinity. \\  snuverink_j committed Sep 06, 2017 398  %\hline  snuverink_j committed Sep 11, 2017 399 400  \texttt{CUTOFFPY} & \index{CUTOFFPY} {3.0} & None & Defines cutoff in $p_{y}$ dimension in units of $\sigma_{py}$. If \texttt{CUTOFFPY} $= 0$ then actual cutoff in $p_{y}$ is set to infinity. \\  snuverink_j committed Sep 06, 2017 401  %\hline  snuverink_j committed Sep 11, 2017 402 403  \texttt{CUTOFFPZ} & \index{CUTOFFPZ} {3.0} & None & Defines cutoff in $p_{z}$ dimension in units of $\sigma_{pz}$. If \texttt{CUTOFFPZ} $= 0$ then actual cutoff is $p_{z}$ is set to infinity. \\  snuverink_j committed Sep 06, 2017 404 405 406 407 408  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 409 410 In Table~\ref{distattrgauss} we list the basic attributes available for a \texttt{GAUSS} distribution. We can use these to create a very simple \texttt{GAUSS} distribution:  snuverink_j committed Sep 06, 2017 411   snuverink_j committed Sep 06, 2017 412 \begin{verbatim}  snuverink_j committed Sep 06, 2017 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 Name:DISTRIBUTION, TYPE = GAUSS, SIGMAX = 0.001, SIGMAY = 0.003, SIGMAZ = 0.002, SIGMAPX = 0.0, SIGMAPY = 0.0, SIGMAPZ = 0.0, CUTOFFX = 2.0, CUTOFFY = 2.0, CUTOFFLONG = 4.0, OFFSETX = 0.001, OFFSETY = -0.002, OFFSETZ = 0.01, OFFSETPZ = 1200.0 USEEV = TRUE;  snuverink_j committed Sep 06, 2017 428 \end{verbatim}  snuverink_j committed Sep 11, 2017 429 430 This creates a Gaussian shaped distribution with zero transverse emittance, zero energy spread, $\sigma_{x} = {1.0}{mm}$, $\sigma_{y} = {3.0}{mm}$, $\sigma_{z} = {2.0}{mm}$ and an average energy of:  snuverink_j committed Sep 06, 2017 431 432  \begin{equation*}  snuverink_j committed Sep 08, 2017 433 W = {1.2}{MeV}  snuverink_j committed Sep 06, 2017 434 \end{equation*}  snuverink_j committed Sep 11, 2017 435 436 437 In the $x$ direction, the Gaussian distribution is cutoff at $x = 2.0 \times \sigma_{x} = {2.0}{mm}$. In the $y$ direction it is cutoff at $y = 2.0 \times \sigma_{y} = {6.0}{mm}$. This distribution is \emph{injected} into the simulation at an average position of $(\bar{x},\bar{y},\bar{z})=({1.0}{mm}, {-2.0}{mm}, {10.0}{mm})$.  snuverink_j committed Sep 06, 2017 438 439 440   snuverink_j committed Sep 08, 2017 441 \subsection{\texttt{GAUSS} Distribution for Photoinjector}  snuverink_j committed Sep 06, 2017 442 443 444 445 \label{sec:gaussdisttypephotoinjector} \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 446  \caption{Definition of additional distribution attributes for an \emph{emitted} \texttt{GAUSS}  snuverink_j committed Sep 06, 2017 447  distribution type. These are used to generate a distribution with a time profile as illustrated  snuverink_j committed Sep 06, 2017 448  in Figure~\ref{flattop}.}  snuverink_j committed Sep 06, 2017 449 450 451  \label{tab:distattremittedgauss} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 452  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 453  \hline  snuverink_j committed Sep 11, 2017 454  \texttt{TPULSEFWHM} & \index{TPULSEFWHM} {0.0} & {s} & Flat top time see~Figure~\ref{flattop}. \\  snuverink_j committed Sep 06, 2017 455  %\hline  snuverink_j committed Sep 11, 2017 456 457  \texttt{TRISE} & \index{TRISE} {0.0} & {s} & Rise time see~Figure~\ref{flattop}. If defined will override \texttt{SIGMAT}. \\  snuverink_j committed Sep 06, 2017 458  %\hline  snuverink_j committed Sep 11, 2017 459 460  \texttt{TFALL} & \index{TFALL} {0.0} & {s} & Fall time see~Figure~\ref{flattop}. If defined will override \texttt{SIGMAT}. \\  snuverink_j committed Sep 06, 2017 461  %\hline  snuverink_j committed Sep 11, 2017 462 463  \texttt{FTOSCAMPLITUDE} & \index{FTOSCAMPLITUDE} {0} & None & Sinusoidal oscillations can imposed on the flat top in Figure~\ref{flattop}. This defines the amplitude of those oscillations in percent of the average flat top amplitude. \\  snuverink_j committed Sep 06, 2017 464  %\hline  snuverink_j committed Sep 11, 2017 465 466  \texttt{FTOSCPERIODS} & \index{FTOSCPERIODS} {0} & None & Defines the number of oscillation periods imposed on the flat top, $t_\mathrm{flattop}$, in Figure~\ref{flattop}. \\  snuverink_j committed Sep 06, 2017 467 468 469 470 471 472 473 474  \hline \end{tabularx} \end{center} \end{table} \begin{figure}[ht] \begin{center} \includegraphics[width=0.8\textwidth]{./figures/flattop.pdf}  snuverink_j committed Sep 07, 2017 475  \caption{\textit{OPAL} emitted \texttt{GAUSS} distribution with flat top.}  snuverink_j committed Sep 06, 2017 476 477 478 479  \label{fig:flattop} \end{center} \end{figure}  snuverink_j committed Sep 06, 2017 480 A useful feature of the \texttt{GAUSS} distribution type is the ability to mimic the initial distribution  snuverink_j committed Sep 06, 2017 481 from a photoinjector. For this purpose we have the distribution attributes listed in Table~\ref{distattremittedgauss}.  snuverink_j committed Sep 06, 2017 482 Using them, we can create a distribution with the time structure  snuverink_j committed Sep 06, 2017 483 shown in Figure~\ref{flattop}. This is a half Gaussian rise plus a uniform flat-top plus a half Gaussian  snuverink_j committed Sep 06, 2017 484 fall. To make it more convenient to mimic measured laser profiles, \texttt{TRISE} and \texttt{TFALL} from  snuverink_j committed Sep 06, 2017 485 Table~\ref{distattremittedgauss} do not define RMS quantities, but instead are given by (See also Figure~\ref{flattop}):  snuverink_j committed Sep 06, 2017 486 487  \begin{align*}  snuverink_j committed Sep 08, 2017 488 489 490 491  \texttt{TRISE} = t_{R} &= \left(\sqrt{2 \ln(10)} - \sqrt{2 \ln \left(\frac{10}{9} \right)} \right) \sigma_{R}\\ & = 1.6869 \sigma_{R} \\ \texttt{TFALL} = t_{F} &= \left(\sqrt{2 \ln(10)} - \sqrt{2 \ln \left(\frac{10}{9} \right)} \right) \sigma_{F}\\ & = 1.6869 \sigma_{F}  snuverink_j committed Sep 06, 2017 492 \end{align*}  snuverink_j committed Sep 08, 2017 493 where $\sigma_{R}$ and $\sigma_{F}$ are the Gaussian, RMS rise and fall times respectively. The flat-top portion  snuverink_j committed Sep 06, 2017 494 of the profile, \texttt{TPULSEFWHM}, is defined as (See also Figure~\ref{flattop}):  snuverink_j committed Sep 06, 2017 495 496  \begin{equation*}  snuverink_j committed Sep 08, 2017 497  \texttt{TPULSEFWHM} = \mathrm{FWHM}_{P} = t_\mathrm{flattop} + \sqrt{2 \ln 2} \left( \sigma_{R} + \sigma_{F} \right)  snuverink_j committed Sep 06, 2017 498 499 \end{equation*} Total emission time, $t_{E}$, of this distribution, is a function of the longitudinal cutoff,  snuverink_j committed Sep 06, 2017 500 \texttt{CUTOFFLONG} see~Table~\ref{distattrgauss}, and is given by:  snuverink_j committed Sep 06, 2017 501 502  \begin{align*}  snuverink_j committed Sep 06, 2017 503  t_{E}(\texttt{CUTOFFLONG}) &= \mathrm{FWHM}_{P} - \frac{1}{2} (\mathrm{FWHM}_{R} + \mathrm{FWHM}_{F})  snuverink_j committed Sep 08, 2017 504  + \texttt{CUTOFFLONG} (\sigma_{R} + \sigma_{F}) \\  snuverink_j committed Sep 06, 2017 505  &= \mathrm{FWHM}_{P} + \frac{\texttt{CUTOFFLONG} - \sqrt{2 \ln 2}}{1.6869} (\texttt{TRISE} + \texttt{TFALL})  snuverink_j committed Sep 06, 2017 506 507 \end{align*}  snuverink_j committed Sep 06, 2017 508 Finally, we can also impose oscillations over the flat-top portion of the laser pulse in Figure~\ref{flattop},  snuverink_j committed Sep 06, 2017 509 510 511 $t_\mathrm{flattop}$. This is defined by the attributes \texttt{FTOSCAMPLITUDE} and \texttt{FTOSCPERIODS} from Table~\ref{distattremittedgauss}. \texttt{FTOSCPERIODS} defines how many oscillation periods will be present during the $t_\mathrm{flattop}$ portion of the pulse. \texttt{FTOSCAMPLITUDE} defines the amplitude of those  snuverink_j committed Sep 06, 2017 512 513 514 515 oscillations in percentage of the average profile amplitude during $t_\mathrm{flattop}$. So, for example, if we set $\texttt{FTOSCAMPLITUDE} = 5$, and the amplitude of the profile is equal to $1.0$ during $t_\mathrm{flattop}$, the amplitude of the oscillation will be $0.05$.  snuverink_j committed Sep 08, 2017 516 \subsection{Correlations for \texttt{GAUSS} Distribution (Experimental)}  snuverink_j committed Sep 06, 2017 517 518 519  \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 520  \caption{Definition of additional distribution attributes for a \texttt{GAUSS}  snuverink_j committed Sep 06, 2017 521 522 523 524  distribution type for generating correlations in the beam.} \label{tab:distattrcorrgauss} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 525  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 526  \hline  snuverink_j committed Sep 11, 2017 527 528  \texttt{CORRX} & \index{CORRX} {0.0} & Section~\ref{unitsdistattributes} & $x$, $p_x$ correlation. ($R_{12}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 529  %\hline  snuverink_j committed Sep 11, 2017 530 531  \texttt{CORRY} & \index{CORRY} {0.0} & Section~\ref{unitsdistattributes} & $y$, $p_y$ correlation. ($R_{34}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 532  %\hline  snuverink_j committed Sep 11, 2017 533 534  \texttt{CORRZ} & \index{CORRZ} {0.0} & Section~\ref{unitsdistattributes} & $z$, $p_z$ correlation. ($R_{56}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 535  %\hline  snuverink_j committed Sep 11, 2017 536 537  \texttt{R51} & \index{R51} {0.0} & Section~\ref{unitsdistattributes} & $x$, $z$ correlation. ($R_{51}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 538  %\hline  snuverink_j committed Sep 11, 2017 539 540  \texttt{R52} & \index{R52} {0.0} & Section~\ref{unitsdistattributes} & $p_x$, $z$ correlation. ($R_{52}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 541  %\hline  snuverink_j committed Sep 11, 2017 542 543  \texttt{R61} & \index{R61} {0.0} & Section~\ref{unitsdistattributes} & $x$, $p_z$ correlation. ($R_{61}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 544  %\hline  snuverink_j committed Sep 11, 2017 545 546  \texttt{R62} & \index{R62} {0.0} & Section~\ref{unitsdistattributes} & $p_x$, $p_z$ correlation. ($R_{62}$ in transport notation.) \\  snuverink_j committed Sep 06, 2017 547 548 549 550 551 552 553  \hline \end{tabularx} \end{center} \end{table} To generate Gaussian initial distribution with dispersion, first we generate the uncorrelated Gaussian inputs matrix $R=(R1,...,R_n)$. The mean of $R_i$ is $0$ and the standard deviation squared is 1. Then we correlate $R$.  snuverink_j committed Sep 08, 2017 554 The correlation coefficient matrix $\sigma$ in $x$, $p_x$, $z$, $p_z$ phase space reads:  snuverink_j committed Sep 06, 2017 555 556  \begin{equation*}  snuverink_j committed Sep 08, 2017 557 \sigma= \left[  snuverink_j committed Sep 06, 2017 558 559 560 561 562 563 564 565 \begin{array}{cccc} 1 &c_x&r51 &r61\\ c_x&1 &r52 &r62\\ r51 &r52 &1 &c_t\\ r61 &r62 &c_t &1\\ \end{array} \right] \\ \end{equation*}  snuverink_j committed Sep 08, 2017 566 The Cholesky decomposition of the symmetric positive-definite matrix $\sigma$ is $\sigma=\transpose{C}C$, then the correlated  snuverink_j committed Sep 06, 2017 567 568 569 570 571 572 573 574 575 distribution is $\transpose{C}R$. \textbf{Note}: Correlations work for the moment only with the Gaussian distribution and are experimental, so there are no guarantees as to its efficacy or accuracy. Also, these correlations will work, in principle, for an \emph{emitted} beam. However, recall that in this case, $z$ in meters is replaced by $t$ in seconds, so take care. As an example of defining a correlated beam, let the initial correlation coefficient matrix be: \begin{equation*}  snuverink_j committed Sep 08, 2017 576 \sigma= \left[  snuverink_j committed Sep 06, 2017 577 578 579 580 581 582 583 584 585 586 \begin{array}{cccc} 1 &0.756 &0.023 &0.496\\ 0.756 &1 &0.385 &-0.042\\ 0.023 &0.385 &1 &-0.834\\ 0.496 &-0.042 &-0.834 &1\\ \end{array} \right] \end{equation*} then the corresponding distribution command will read:  snuverink_j committed Sep 06, 2017 587 \begin{verbatim}  snuverink_j committed Sep 06, 2017 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 Dist:DISTRIBUTION, TYPE = GAUSS, SIGMAX = 4.796e-03, SIGMAPX = 231.0585, CORRX = 0.756, SIGMAY = 23.821e-03, SIGMAPY = 1.6592e+03, CORRY = -0.999, SIGMAZ = 0.466e-02, SIGMAPZ = 74.7, CORRZ = -0.834, OFFSETZ = 0.466e-02, OFFSETPZ = 72e6, R61 = 0.496, R62 = -0.042, R51 = 0.023, R52 = 0.385;  snuverink_j committed Sep 06, 2017 604 \end{verbatim}  snuverink_j committed Sep 06, 2017 605 606 \index{Distribution!GAUSS|)}  snuverink_j committed Sep 08, 2017 607 \section{\texttt{FLATTOP} Distribution Type}  snuverink_j committed Sep 06, 2017 608 609 610 611 \label{sec:flattopdisttype} \index{Distribution!FLATTOP|(} \FloatBarrier  snuverink_j committed Sep 06, 2017 612 The \texttt{FLATTOP} distribution type is used to define hard edge beam distributions. Hard edge, in this case, means  snuverink_j committed Sep 06, 2017 613 a more or less uniformly filled cylinder of charge, although as we will see this is not always the case. The main purpose  snuverink_j committed Sep 06, 2017 614 of the \texttt{FLATTOP} is to mimic laser pulses in photoinjectors, and so we usually will make this an \emph{emitted}  snuverink_j committed Sep 06, 2017 615 616 distribution. However it can be \emph{injected} as well.  snuverink_j committed Sep 08, 2017 617 \subsection{Injected \texttt{FLATTOP}}  snuverink_j committed Sep 06, 2017 618 619 620 The attributes for an \emph{injected} \texttt{FLATTOP} distribution are defined in Table~\ref{distattrflattopinj,distattruniversal}. At the moment, we cannot define a spread in the beam momentum, so an \emph{injected} \texttt{FLATTOP} distribution will currently have zero emittance. An \emph{injected} \texttt{FLATTOP} will be a uniformly filled ellipse transversely  snuverink_j committed Sep 06, 2017 621 622 623 624 with a uniform distribution in $z$. (Basically a cylinder with an elliptical cross section.) \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 625  \caption{Definition of the basic distribution attributes for an \emph{injected} \texttt{FLATTOP} distribution type.}  snuverink_j committed Sep 06, 2017 626 627 628  \label{tab:distattrflattopinj} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 629  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 630  \hline  snuverink_j committed Sep 11, 2017 631  \texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & Hard edge width in $x$ direction. \\  snuverink_j committed Sep 06, 2017 632  %\hline  snuverink_j committed Sep 11, 2017 633  \texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & Hard edge width in $y$ direction. \\  snuverink_j committed Sep 06, 2017 634  %\hline  snuverink_j committed Sep 11, 2017 635  \texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & Hard edge radius. If nonzero \texttt{SIGMAR} overrides \texttt{SIGMAX} and \texttt{SIGMAY}. \\  snuverink_j committed Sep 06, 2017 636  %\hline  snuverink_j committed Sep 11, 2017 637  \texttt{SIGMAZ} & \index{SIGMAZ} {0.0} & {m} & Hard edge length in $z$ direction. \\  snuverink_j committed Sep 06, 2017 638 639 640 641 642 643  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 08, 2017 644 \subsection{Emitted \texttt{FLATTOP}}  snuverink_j committed Sep 06, 2017 645 646 647  \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 648  \caption{Definition of the basic distribution attributes for an \emph{emitted} \texttt{FLATTOP} distribution type.}  snuverink_j committed Sep 06, 2017 649 650 651  \label{tab:distattrflattopemit} \begin{tabularx}{\textwidth - 1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 652  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 653  \hline  snuverink_j committed Sep 11, 2017 654  \texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & Hard edge width in $x$ direction. \\  snuverink_j committed Sep 06, 2017 655  %\hline  snuverink_j committed Sep 11, 2017 656  \texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & Hard edge width in $y$ direction. \\  snuverink_j committed Sep 06, 2017 657  %\hline  snuverink_j committed Sep 11, 2017 658  \texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & Hard edge radius. If nonzero \texttt{SIGMAR} overrides \texttt{SIGMAX} and \texttt{SIGMAY}. \\  snuverink_j committed Sep 06, 2017 659  %\hline  snuverink_j committed Sep 11, 2017 660 661  \texttt{SIGMAT} & \index{SIGMAT} {0.0} & {s} & RMS rise and fall of half Gaussian in flat top defined in in Figure~\ref{flattop}. \\  snuverink_j committed Sep 06, 2017 662  %\hline  snuverink_j committed Sep 11, 2017 663  \texttt{TPULSEFWHM} & \index{TPULSEFWHM} {0.0} & {s} & Flat top time. See Figure~\ref{flattop}. \\  snuverink_j committed Sep 06, 2017 664  %\hline  snuverink_j committed Sep 11, 2017 665 666  \texttt{TRISE} & \index{TRISE} {0.0} & {s} & Rise time. See Figure~\ref{flattop}. If defined will override \texttt{SIGMAT}. \\  snuverink_j committed Sep 06, 2017 667  %\hline  snuverink_j committed Sep 11, 2017 668 669  \texttt{TFALL} & \index{TFALL} {0.0} & {s} & Fall time. See Figure~\ref{flattop}. If defined will override \texttt{SIGMAT}. \\  snuverink_j committed Sep 06, 2017 670  %\hline  snuverink_j committed Sep 11, 2017 671 672  \texttt{FTOSCAMPLITUDE} & \index{FTOSCAMPLITUDE} {0} & None & Sinusoidal oscillations can imposed on the flat top in Figure~\ref{flattop}. This defines the amplitude of those oscillations in percent of the average flat top amplitude. \\  snuverink_j committed Sep 06, 2017 673  %\hline  snuverink_j committed Sep 11, 2017 674 675  \texttt{FTOSCPERIODS} & \index{FTOSCPERIODS} {0} & None & Defines the number of oscillation periods imposed on the flat top, $t_\mathrm{flattop}$, in Figure~\ref{flattop}. \\  snuverink_j committed Sep 06, 2017 676  %\hline  snuverink_j committed Sep 11, 2017 677  \texttt{LASERPROFFN} & \index{LASERPROFFN} & None & File name containing measured laser image. \\  snuverink_j committed Sep 06, 2017 678  %\hline  snuverink_j committed Sep 11, 2017 679  \texttt{IMAGENAME} & \index{IMAGENAME} & None & Name of the file containing the laser image. \\  snuverink_j committed Sep 06, 2017 680  %\hline  snuverink_j committed Sep 11, 2017 681 682 683 684 685 686 687  \texttt{INTENSITYCUT} & \index{INTENSITYCUT} {0.0} & None & Parameter defining floor of the background to be subtracted from the laser image in percent of the maximum intensity. \\ \texttt{FLIPX} & \index{FLIPX} \texttt{FALSE} & & Flip the laser profile in horizontal direction. \\ \texttt{FLIPY} & \index{FLIPY} \texttt{FALSE} & & Flip the laser profile in vertical direction. \\ \texttt{ROTATE90} & \index{ROTATE90} \texttt{FALSE} & & Rotate the laser profile {90}{$^{\circ}$} in counterclockwise direction. \\ \texttt{ROTATE180} & \index{ROTATE180} \texttt{FALSE} & & Rotate the laser profile {180}{$^{\circ}$}. \\ \texttt{ROTATE270} & \index{ROTATE270} \texttt{FALSE} & & Rotate the laser profile {270}{$^{\circ}$} in counterclockwise direction. \\  snuverink_j committed Sep 06, 2017 688 689 690 691 692  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 693 694 695 The attributes of an \emph{emitted} \texttt{FLATTOP} distribution are defined in Table~\ref{distattrflattopemit,distattruniversal}. The \texttt{FLATTOP} distribution was really intended for this mode of operation in order to mimic common laser pulses in photoinjectors. The basic characteristic of a \texttt{FLATTOP} is a uniform, elliptical transverse distribution  snuverink_j committed Sep 06, 2017 696 and a longitudinal (time) distribution with a Gaussian rise and fall time as described in Section~\ref{gaussdisttypephotoinjector}.  snuverink_j committed Sep 11, 2017 697 Below we show an example of a \texttt{FLATTOP} distribution command with an elliptical cross section of {1}{mm} by {2}{mm} and a flat top,  snuverink_j committed Sep 08, 2017 698 in time, {10}{ps} long with a {0.5}{ps} rise and fall time as defined in Figure~\ref{flattop}.  snuverink_j committed Sep 06, 2017 699   snuverink_j committed Sep 06, 2017 700 \begin{verbatim}  snuverink_j committed Sep 06, 2017 701 702 703 704 705 706 707 708 709 710 711 712 Dist:DISTRIBUTION, TYPE = FLATTOP, SIGMAX = 0.001, SIGMAY = 0.002, TRISE = 0.5e-12, TFALL = 0.5e-12, TPULSEFWHM = 10.0e-12, CUTOFFLONG = 4.0, NBIN = 5, EMISSIONSTEPS = 100, EMISSIONMODEL = ASTRA, EKIN = 0.5, EMITTED = TRUE;  snuverink_j committed Sep 06, 2017 713 \end{verbatim}  snuverink_j committed Sep 06, 2017 714 715 716 717 \index{Distribution!FLATTOP|)} \subsection{Transverse Distribution from Laser Profile (Under Development)} \index{Distribution!Laser Profile}  snuverink_j committed Sep 06, 2017 718 An alternative to using a uniform, elliptical transverse profile is to define the \texttt{LASERPROFFN}, \texttt{IMAGENAME} and  snuverink_j committed Sep 07, 2017 719 \texttt{INTENSITYCUT} attributes from Table~\ref{distattrflattopemit}. Then, \textit{OPAL-t} will use the laser image as the basis  snuverink_j committed Sep 06, 2017 720 721 722 723 724 to sample the transverse distribution. \textbf{\emph{This distribution option is not yet available.}}  snuverink_j committed Sep 08, 2017 725 \subsection{\texttt{GUNGAUSSFLATTOPTH} Distribution Type}  snuverink_j committed Sep 06, 2017 726 727 \label{sec:gungaussflattopthdisttype} \index{Distribution!GUNGAUSSFLATTOPTH}  snuverink_j committed Sep 06, 2017 728 729 730 This is a legacy distribution type. A \texttt{GUNGAUSSFLATTOPTH} is the equivalent of a \texttt{FLATTOP} distribution, except that the \texttt{EMITTED} attribute will set to \texttt{TRUE} automatically and the \texttt{EMISSIONMODEL} will be automatically set to \texttt{ASTRA}.  snuverink_j committed Sep 06, 2017 731   snuverink_j committed Sep 08, 2017 732 \subsection{\texttt{ASTRAFLATTOPTH} Distribution Type}  snuverink_j committed Sep 06, 2017 733 734 \label{sec:astraflattopthdisttype} \index{Distribution!ASTRAFLATTOPTH}  snuverink_j committed Sep 06, 2017 735 736 737 This is a legacy distribution type. A \texttt{ASTRAFLATTOPTH} is the equivalent of a \texttt{FLATTOP} distribution, except that the \texttt{EMITTED} attribute will set to \texttt{TRUE} automatically and the \texttt{EMISSIONMODEL} will be automatically set to \texttt{ASTRA}. There are a few other differences with how the longitudinal time profile of the distribution is generated.  snuverink_j committed Sep 06, 2017 738   snuverink_j committed Sep 08, 2017 739 \section{\texttt{BINOMIAL} Distribution Type}  snuverink_j committed Sep 06, 2017 740 741 742 743 \label{sec:binomialdisttype} \index{Distribution!BINOMIAL} \FloatBarrier  snuverink_j committed Sep 08, 2017 744 The \texttt{BINOMIAL} type of distribution is based on \ref{JohoDist}. The shape of the binomial distribution is governed by  snuverink_j committed Sep 06, 2017 745 one parameter $m$. By varying this single parameter one obtains the most commonly used distributions for our type of simulations,  snuverink_j committed Sep 06, 2017 746 as listed in Table~\ref{binomdist}.  snuverink_j committed Sep 06, 2017 747 748 749 750 751 752 753  \begin{table}[!htb] \begin{center} \footnotesize \caption{Different distributions specified by a single parameter $m$} \label{tab:binomdist} \begin{tabularx}{\textwidth-1cm}{|l|l|l|X|} \hline  snuverink_j committed Sep 11, 2017 754  \tabhead $m$ & Distribution & Density & Profile \\  snuverink_j committed Sep 06, 2017 755  \hline  snuverink_j committed Sep 08, 2017 756  {0.0} & Hollow shell & $\frac{1}{\pi}\delta(1-r^2)$ &$\frac{1}{\pi}(1-r^2)^{-0.5}$\\  snuverink_j committed Sep 06, 2017 757  %\hline  snuverink_j committed Sep 08, 2017 758  {0.5} & Flat profile & $\frac{1}{2\pi}(1-r^2)^{-0.5}$ & $\frac{1}{2}$\\  snuverink_j committed Sep 06, 2017 759  %\hline  snuverink_j committed Sep 08, 2017 760  {1.0} & Uniform & $\frac{1}{\pi}$ & $\frac{2}{\pi}(1-x^2)^{0.5}$\\  snuverink_j committed Sep 06, 2017 761  %\hline  snuverink_j committed Sep 08, 2017 762  {1.5} & Elliptical & $\frac{3}{2\pi}(1-r^2)^{0.5}$ & $\frac{1}{4}(1-x^2)$ \\  snuverink_j committed Sep 06, 2017 763  %\hline  snuverink_j committed Sep 08, 2017 764  {2.0} & Parabolic & $\frac{2}{\pi}(1-r^2)$ & $\frac{3}{8\pi}(1-x^2)^{1.5}$ \\  snuverink_j committed Sep 06, 2017 765  %\hline  snuverink_j committed Sep 08, 2017 766 767  $\rightarrow \infty$ & Gaussian & $\frac{1}{2\pi\sigma_x\sigma_y}exp(-\frac{x^2}{2\sigma_x^2} -\frac{y^2}{2\sigma_y^2})$ & $\frac{1}{\sqrt{2\pi}*\sigma_x}exp(-\frac{x^2}{2\sigma_x^2})$ \\  snuverink_j committed Sep 06, 2017 768 769 770 771 772 773 774 775 776 777 778 779 780 781  \hline \end{tabularx} \end{center} \end{table} \section{Emission Models} \label{sec:emissionmodel} \index{Distribution!Emission} \index{Emission} \FloatBarrier When emitting a distribution from a cathode, there are several ways in which we can model the emission process in order to calculate the thermal emittance of the beam. In this section we discuss the various options available.  snuverink_j committed Sep 08, 2017 782 \subsection{Emission Model: \texttt{NONE} (default)}  snuverink_j committed Sep 06, 2017 783 \index{Emission Model!NONE}  snuverink_j committed Sep 07, 2017 784 The emission model \texttt{NONE} is the default emission model used in \textit{OPAL-t}. It has a single attribute, listed in  snuverink_j committed Sep 06, 2017 785 786 Table~\ref{distattremitmodelnoneastra}. The \texttt{NONE} emission model is very simplistic. It merely adds the amount of energy defined by the attribute \texttt{EKIN} to the longitudinal momentum, $p_{z}$, for each particle in the distribution  snuverink_j committed Sep 06, 2017 787 788 789 790 as it leaves the cathode. \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 791  \caption{Attributes for the \texttt{NONE} and \texttt{ASTRA} emission models.}  snuverink_j committed Sep 06, 2017 792 793 794  \label{tab:distattremitmodelnoneastra} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 795  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 796  \hline  snuverink_j committed Sep 11, 2017 797  \texttt{EKIN} & \index{EKIN} {1.0} &{eV} & Thermal energy added to beam during emission. \\  snuverink_j committed Sep 06, 2017 798 799 800 801 802  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 803 An example of using the \texttt{NONE} emission model is given below. This option allows us to emit transversely cold  snuverink_j committed Sep 06, 2017 804 (zero x and y emittance) beams into our simulation. We must add some z momentum to ensure that the particles drift into  snuverink_j committed Sep 06, 2017 805 the simulation space. If in this example one were to specify \texttt{EKIN = 0}, then you would likely get strange results  snuverink_j committed Sep 06, 2017 806 807 808 as the particles would not move off the cathode, causing all of the emitted charge to pile up at $z = 0$ in the first half time step before the beam space charge is calculated.  snuverink_j committed Sep 06, 2017 809 \begin{verbatim}  snuverink_j committed Sep 06, 2017 810 811 812 813 814 815 816 817 818 819 820 821 Dist:DISTRIBUTION, TYPE = FLATTOP, SIGMAX = 0.001, SIGMAY = 0.002, TRISE = 0.5e-12, TFALL = 0.5e-12, TPULSEFWHM = 10.0e-12, CUTOFFLONG = 4.0, NBIN = 5, EMISSIONSTEPS = 100, EMISSIONMODEL = NONE, EKIN = 0.5, EMITTED = TRUE;  snuverink_j committed Sep 06, 2017 822 \end{verbatim}  snuverink_j committed Sep 06, 2017 823   snuverink_j committed Sep 06, 2017 824 825 One thing to note, it may be that if you are emitting your own distribution using the \texttt{TYPE = FROMFILE} option, you may want to set \texttt{EKIN = 0} if you have already added some amount of momentum, $p_{z}$, to the  snuverink_j committed Sep 06, 2017 826 827 particles.  snuverink_j committed Sep 08, 2017 828 \subsection{Emission Model: \texttt{ASTRA}}  snuverink_j committed Sep 06, 2017 829 \index{Emission Model!ASTRA}  snuverink_j committed Sep 06, 2017 830 831 The \texttt{ASTRA} emittance model uses the same single parameter as the \texttt{NONE} option as listed in Table~\ref{distattremitmodelnoneastra}. However, in this case, the energy defined by the \texttt{EKIN} attribute is  snuverink_j committed Sep 06, 2017 832 833 834 835 added to each emitted particle's momentum in a random way: \begin{equation*} \begin{aligned}  snuverink_j committed Sep 06, 2017 836  p_{total} &= \sqrt{\left(\frac{\texttt{EKIN}}{mc^{2}} + 1\right)^{2} - 1} \\  snuverink_j committed Sep 11, 2017 837 838  p_{x} &= p_{total} \sin(\phi) \cos(\theta)) \\ p_{y} &= p_{total} \sin(\phi) \sin(\theta)) \\  snuverink_j committed Sep 06, 2017 839 840 841 842 843 844 845 846 847 848  p_{z} &= p_{total} |{\cos(\theta)}| \end{aligned} \end{equation*} where $\theta$ is a random angle between $0$ and $\pi$, and $\phi$ is given by \begin{equation*} \phi = 2.0 \arccos \left( \sqrt{x} \right) \end{equation*} with $x$ a random number between $0$ and $1$.  snuverink_j committed Sep 08, 2017 849 \subsection{Emission Model: \texttt{NONEQUIL}}  snuverink_j committed Sep 06, 2017 850 \index{Emission Model!NONEQUIL}  snuverink_j committed Sep 06, 2017 851 The \texttt{NONEQUIL} emission model is based on an actual physical model of particle emission as described in  snuverink_j committed Sep 08, 2017 852 \ref{flo:97, clen:2000, dowe:2009}. The attributes needed by this emission model are listed in  snuverink_j committed Sep 06, 2017 853 Table~\ref{distattremitmodelnonequil}.  snuverink_j committed Sep 06, 2017 854 855 856  \begin{table}[!htb] \begin{center}\footnotesize  snuverink_j committed Sep 06, 2017 857  \caption{Attributes for the \texttt{NONE} and \texttt{ASTRA} emission models.}  snuverink_j committed Sep 06, 2017 858 859 860  \label{tab:distattremitmodelnonequil} \begin{tabularx}{\textwidth-1cm}{|l|c|c|X|} \hline  snuverink_j committed Sep 11, 2017 861  \tabhead Attribute Name & Default Value & Units & Description \\  snuverink_j committed Sep 06, 2017 862  \hline  snuverink_j committed Sep 11, 2017 863  \texttt{ELASER} & \index{ELASER} {4.86} & {eV} & Photoinjector drive laser energy. (Default is {255}{nm} light.) \\  snuverink_j committed Sep 06, 2017 864  %\hline  snuverink_j committed Sep 11, 2017 865  \texttt{W} & \index{W} {4.31} & {eV} & Photocathode work function. (Default is atomically clean copper.) \\  snuverink_j committed Sep 06, 2017 866  %\hline  snuverink_j committed Sep 11, 2017 867  \texttt{FE} & \index{FE} {7.0} & {eV} & Fermi energy of photocathode. (Default is atomically clean copper.) \\  snuverink_j committed Sep 06, 2017 868  %\hline  snuverink_j committed Sep 11, 2017 869  \texttt{CATHTEMP} & \index{CATHTEMP} {300.0} & {\kelvin} & Operating temperature of photocathode. \\  snuverink_j committed Sep 06, 2017 870 871 872 873 874  \hline \end{tabularx} \end{center} \end{table}  snuverink_j committed Sep 06, 2017 875 An example of using the \texttt{NONEQUIL} emission model is given below. This model is relevant for metal  snuverink_j committed Sep 06, 2017 876 877 cathodes and cathodes such as $CsTe$.  snuverink_j committed Sep 06, 2017 878 \begin{verbatim}  snuverink_j committed Sep 06, 2017 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 Dist:DISTRIBUTION, TYPE = GAUSS, SIGMAX = 0.001, SIGMAY = 0.002, TRISE = 1.0e-12, TFALL = 1.0e-12, TPULSEFWHM = 15.0e-12, CUTOFFLONG = 3.0, NBIN = 10, EMISSIONSTEPS = 100, EMISSIONMODEL = NONEQUIL, ELASER = 6.48, W = 4.1, FE = 7.0, CATHTEMP = 325, EMITTED = TRUE;  snuverink_j committed Sep 06, 2017 894 \end{verbatim}  snuverink_j committed Sep 06, 2017 895 896 897 898 899 900 901 902 903  \section{Distribution List} \label{sec:distlist} \index{Distribution List} \FloatBarrier It is possible to use multiple distributions in the same simulation. We do this be using a distribution list  snuverink_j committed Sep 06, 2017 904 in the \texttt{RUN} command see~Chapter~\ref{track}. Assume we have defined several distributions: \texttt{DIST1},  snuverink_j committed Sep 06, 2017 905 906 \texttt{DIST2} and \texttt{DIST3}. If we want to use just one of these distributions in a simulation, we would use the following \texttt{RUN} command to start the simulation:  snuverink_j committed Sep 06, 2017 907   snuverink_j committed Sep 06, 2017 908 \begin{verbatim}  snuverink_j committed Sep 06, 2017 909 910 911 912 RUN, METHOD = "PARALLEL-T", BEAM = beam_name, FIELDSOLVER = field_solver_name, DISTRIBUTION = DIST1;  snuverink_j committed Sep 06, 2017 913 \end{verbatim}