%% 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
\caption{Possible distribution types. Note that the \texttt{SURFACEEMISSION} and \texttt{SURFACERANDCREATE}
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
\tabhead Distribution Type & Description \\
\hline
\texttt{FROMFILE} & Initial distribution read in from text file provided by user
see~Section~\ref{fromfiledisttype}. \\
%\hline
\texttt{GAUSS} & Initial distribution generated using Gaussian distribution(s)
see~Section~\ref{gaussdisttype}. \\
%\hline
\texttt{FLATTOP} & Initial distribution generated using flattop distribution(s)
see~Section~\ref{flattopdisttype}. \\
%\hline
\texttt{BINOMIAL} & Initial distribution generated using binomial distribution(s)
see~Section~\ref{binomialdisttype}. \\
%\hline
\texttt{SURFACEEMISSION} & For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead \chpref{femiss}. \\
%\hline
\texttt{SURFACERANDCREATE} & For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead \chpref{femiss}. \\
%\hline
\texttt{GUNGAUSSFLATTOPTH} & Legacy. Special case of \texttt{FLATTOP} distribution see~Section~\ref{gungaussflattopthdisttype}. \\
%\hline
\texttt{ASTRAFLATTOPTH} & Legacy. Special case of \texttt{FLATTOP} distribution see~Section~\ref{astraflattopthdisttype}. \\
\hline
\end{tabularx}
\end{center}
\end{table}
The distribution command is used to introduce particles into an \textit{OPAL} simulation. Like other \textit{OPAL}
commands see~Chapter~\ref{format}, the distribution command is of the form:
\begin{verbatim}
Name:DISTRIBUTION, TYPE = DISTRIBUTION_TYPE,
ATTRIBUTE #1 =,
ATTRIBUTE #2 =,
.
.
.
ATTRIBUTE #N =;
\end{verbatim}
The distribution is given a name (which is used to reference the distribution in the \textit{OPAL} input
file), a distribution type, and a list of attributes. The types of distributions that are supported
are listed in Table~\ref{disttypes}. The attributes that follow the distribution type further
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
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
length and seconds for time. However, there are different options for the units used to input the
momentum. This is controlled with the \texttt{INPUTMOUNITS} attribute, defined in
Table~\ref{distattrinputmounits}.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of \texttt{INPUTMOUNITS} attribute.}
\label{tab:distattrinputmounits}
\begin{tabularx}{\textwidth-1cm}{|l|c|X|}
\hline
\tabhead Attribute Name & Value & Description \\
\hline
\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}$). \\
\hline
\end{tabularx}
\end{center}
\end{table}
\section{General Distribution Attributes}
\label{sec:gendistattributes}
\index{Distribution!General Attributes}
\FloatBarrier
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
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.
from a cathode in a photoinjector simulation). Currently, only \textit{OPAL-t} supports \emph{emitted}
distributions. The default is an \emph{injected} distribution.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of \texttt{EMITTED} attribute.}
\label{tab:distattremitted}
\begin{tabularx}{\textwidth-1cm}{|l|c|X|}
\hline
\tabhead Attribute Name & Value & Description \\
\hline
\texttt{EMITTED} & \index{EMITTED} \texttt{FALSE} (default) & The distribution is injected into the simulation in its entirety
at the start of the simulation. The particle coordinates for an injected distribution are defined as in
Section~\ref{variablesopalt,variablesopalcycl}. Note that in \textit{OPAL-t} the entire distribution will automatically
be shifted to ensure that the $z$ coordinate will be greater than zero for all particles. \\
%\hline
\texttt{EMITTED} & \texttt{TRUE} & The distribution is emitted into the simulation over time as the simulation
progresses. Currently only \textit{OPAL-t} supports this type of distribution. In this case, the longitudinal coordinate, as
defined by Section~\ref{variablesopalt}, is given in seconds instead of meters. Early times are emitted first. \\
\hline
\end{tabularx}
\end{center}
\end{table}
Depending on the \texttt{EMITTED} attribute, we can specify several other attributes that do not depend on the
distribution type. These are defined in Section~\ref{universaldistattributes,injecteddistattributes,emitteddistattributes} in
Table~\ref{distattruniversal,distattrinjected,distattrsemitted}.
\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
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{WRITETOFILE} & \index{WRITETOFILE} \texttt{FALSE} & None & Echo initial distribution to text file \textit{data/\textless basename \textgreater\_ DIST.dat}. \\
%\hline
\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. \\
%
\texttt{WEIGHT} & {1.0} & None & Weight of distribution when used in a distribution list see~Section~\ref{distlist}. \\
%\hline
\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}. \\
%\hline
\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). \\
%\hline
\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). \\
%\hline
\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). \\
%\hline
\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). \\
%\hline
\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). \\
%\hline
\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}$. \\
%\hline
\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}$. \\
%\hline
\texttt{OFFSETPX} & \index{OFFSETPX} {0.0} & Section~\ref{unitsdistattributes} &
Distribution is shifted in $p_{x}$ by this amount after the distribution is generated (or read in). Same as the
average $p_{x}$ value, $\bar{p}_{x}$. \\
%\hline
\texttt{OFFSETPY} & \index{OFFSETPY} {0.0} & Section~\ref{unitsdistattributes} &
Distribution is shifted in $p_{y}$ by this amount after the distribution is generated (or read in). Same as the
average $p_{y}$ value, $\bar{p}_{y}$. \\
%\hline
\texttt{OFFSETPZ} & \index{OFFSETPZ} {0.0} & Section~\ref{unitsdistattributes} &
Distribution is shifted in $p_{z}$ by this amount after the distribution is generated (or read in). Same as the
average $p_{z}$ value, $\bar{p}_{z}$. \\
%\hline
\texttt{ID1} & \index{ID1} {0.0} & Section~\ref{unitsdistattributes} &
Tracer particle which is written also into {\em data/track\_orbit.dat} \\
%\hline
\texttt{ID2} & \index{ID2} {0.0} & Section~\ref{unitsdistattributes} &
Tracer particle which is written also into {\em data/track\_orbit.dat} \\
\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
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\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). \\
%\hline
\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}$. \\
\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
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\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). \\
%\hline
\texttt{OFFSETT} & \index{OFFSETT} {0.0} & {s} & Distribution is emitted later by this amount relative to the reference particle. \\
%\hline
\texttt{EMISSIONSTEPS} & \index{EMISSIONSTEPS} {1} & None & Number of time steps to take during emission. The simulation time step
will be adjusted during emission to ensure that this many time steps will be
required to emit the entire distribution. \\
%\hline
\texttt{EMISSIONMODEL} & \index{EMISSIONMODEL} None & None & Emission model to use when emitting particles from cathode
see~Section~\ref{emissionmodel}. \\
\hline
\end{tabularx}
\end{center}
\end{table}
\section{\texttt{FROMFILE} Distribution Type}
\label{sec:fromfiledisttype}
\index{Distribution!FROMFILE}
\FloatBarrier
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,
and have it either \emph{injected} or \emph{emitted} into the simulation. In Table~\ref{distattrfromfile}
we list the single attribute specific to this type of distribution type.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of distribution attributes for a \texttt{FROMFILE} distribution type.}
\label{tab:distattrfromfile}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{FNAME} & \index{FNAME} None & None & File name for text file containing distribution particle coordinates. \\
\hline
\end{tabularx}
\end{center}
\end{table}
An example of an \emph{injected} \texttt{FROMFILE} distribution definition is:
\begin{verbatim}
Name:DISTRIBUTION, TYPE = FROMFILE,
FNAME = "text file name";
\end{verbatim}
an example of an \emph{emitted} \texttt{FROMFILE} distribution definition is:
\begin{verbatim}
Name:DISTRIBUTION, TYPE = FROMFILE,
FNAME = "text file name",
EMITTED = TRUE,
EMISSIONMODEL = None;
\end{verbatim}
The text input file for the \texttt{FROMFILE} distribution type has slightly a slightly different
format, depending on whether the distribution is to be \emph{injected} or \emph{emitted}. The
\emph{injected} file format is defined in Table~\ref{fromfileinjfileformat}. The \emph{emitted}
file format is defined in Table~\ref{fromfileemitfileformat}.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{File format for \emph{injected} \texttt{FROMFILE} distribution type. N is the number
of particles in the file. The particle coordinates are defined in Section~\ref{variablesopalt,variablesopalcycl}.}
\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
\caption{File format for \emph{emitted} \texttt{FROMFILE} distribution type. N is the number
of particles in the file. The particle coordinates are defined in Section~\ref{variablesopalt}
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}
Note that for an \emph{emitted} \texttt{FROMFILE} distribution, all of the particle's time, $t$, coordinates
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
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
distribution coordinates at all.
To maintain consistency $N$ and \texttt{NPART} from the \texttt{BEAM} command in \chpref{beam} must be equal.
\section{\texttt{GAUSS} Distribution Type}
\label{sec:gaussdisttype}
\index{Distribution!GAUSS|(}
\FloatBarrier
As the name implies, the \texttt{GAUSS} distribution type can generate distributions with a general
Gaussian shape (here we show a one-dimensional example):
\begin{equation*}
f(x) = \frac{1}{\sqrt{2 \pi}} e^{-\frac{(x - \bar{x})^{2}}{2 \sigma_{x}^{2}}}
\end{equation*}
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}
distribution type in this section.
\subsection{Simple \texttt{GAUSS} Distribution Type}
We will begin by describing how to create a simple \texttt{GAUSS} distribution type. That is, a simple
6-dimensional distribution with a Gaussian distribution in all dimensions.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of the basic distribution attributes for a \texttt{GAUSS} distribution type.}
\label{tab:distattrgauss}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & RMS width, $\sigma_{x}$, in transverse $x$ direction. \\
%\hline
\texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & RMS width, $\sigma_{y}$, in transverse $y$ direction. \\
%\hline
\texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & RMS radius, $\sigma_{r}$, in radial direction. If nonzero \texttt{SIGMAR} overrides
\texttt{SIGMAX} and \texttt{SIGMAY}. \\
%\hline
\texttt{SIGMAZ} & \index{SIGMAZ} {0.0} & {m} & RMS length, $\sigma_{z}$, in longitudinal (z) direction. \texttt{SIGMAZ} is used
for an \emph{injected} distribution. \\
%\hline
\texttt{SIGMAT} & \index{SIGMAT} {0.0} & {s} & RMS width, $\sigma_{t}$, in time (t). \texttt{SIGMAT} is used for an \emph{emitted}
distribution. \\
%\hline
\texttt{SIGMAPX} & \index{SIGMAPX} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{px}$ for defining distribution. \\
%\hline
\texttt{SIGMAPY} & \index{SIGMAPY} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{py}$ for defining distribution. \\
%\hline
\texttt{SIGMAPZ} & \index{SIGMAPZ} {0.0} & Section~\ref{unitsdistattributes}& Parameter $\sigma_{pz}$ for defining distribution. \\
%\hline
\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. \\
%\hline
\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. \\
%\hline
\texttt{CUTOFFR} & \index{CUTOFFR} {3.0} & None & Defines transverse distribution cutoff in the $r$ direction in units of
$\sigma_{r}$. If \texttt{CUTOFFR} $= 0$ then actual cutoff in $r$ is set to infinity. \texttt{CUTOFFR} is
only used if \texttt{SIGMAR} $>0$. \\
%\hline
\texttt{CUTOFFLONG} & \index{CUTOFFLONG} {3.0} & None & Defines longitudinal distribution cutoff in the $z$ or $t$ direction
(\emph{injected} or \emph{emitted}) in units of $\sigma_{z}$ or $\sigma_{t}$. \texttt{CUTOFFLONG} is
different from other dimensions in that a value of {0.0} does not imply a cutoff value of infinity. \\
%\hline
\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. \\
%\hline
\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. \\
%\hline
\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. \\
\hline
\end{tabularx}
\end{center}
\end{table}
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:
\begin{verbatim}
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;
\end{verbatim}
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:
\begin{equation*}
W = {1.2}{MeV}
\end{equation*}
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})$.
\subsection{\texttt{GAUSS} Distribution for Photoinjector}
\label{sec:gaussdisttypephotoinjector}
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of additional distribution attributes for an \emph{emitted} \texttt{GAUSS}
distribution type. These are used to generate a distribution with a time profile as illustrated
in Figure~\ref{flattop}.}
\label{tab:distattremittedgauss}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{TPULSEFWHM} & \index{TPULSEFWHM} {0.0} & {s} & Flat top time see~Figure~\ref{flattop}. \\
%\hline
\texttt{TRISE} & \index{TRISE} {0.0} & {s} & Rise time see~Figure~\ref{flattop}. If defined will override
\texttt{SIGMAT}. \\
%\hline
\texttt{TFALL} & \index{TFALL} {0.0} & {s} & Fall time see~Figure~\ref{flattop}. If defined will override
\texttt{SIGMAT}. \\
%\hline
\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. \\
%\hline
\texttt{FTOSCPERIODS} & \index{FTOSCPERIODS} {0} & None & Defines the number of oscillation periods imposed on the flat top,
$t_\mathrm{flattop}$, in Figure~\ref{flattop}. \\
\hline
\end{tabularx}
\end{center}
\end{table}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=0.8\textwidth]{./figures/flattop.pdf}
\caption{\textit{OPAL} emitted \texttt{GAUSS} distribution with flat top.}
\label{fig:flattop}
\end{center}
\end{figure}
A useful feature of the \texttt{GAUSS} distribution type is the ability to mimic the initial distribution
from a photoinjector. For this purpose we have the distribution attributes listed in Table~\ref{distattremittedgauss}.
Using them, we can create a distribution with the time structure
shown in Figure~\ref{flattop}. This is a half Gaussian rise plus a uniform flat-top plus a half Gaussian
fall. To make it more convenient to mimic measured laser profiles, \texttt{TRISE} and \texttt{TFALL} from
Table~\ref{distattremittedgauss} do not define RMS quantities, but instead are given by (See also Figure~\ref{flattop}):
\begin{align*}
\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}
\end{align*}
where $\sigma_{R}$ and $\sigma_{F}$ are the Gaussian, RMS rise and fall times respectively. The flat-top portion
of the profile, \texttt{TPULSEFWHM}, is defined as (See also Figure~\ref{flattop}):
\begin{equation*}
\texttt{TPULSEFWHM} = \mathrm{FWHM}_{P} = t_\mathrm{flattop} + \sqrt{2 \ln 2} \left( \sigma_{R} + \sigma_{F} \right)
\end{equation*}
Total emission time, $t_{E}$, of this distribution, is a function of the longitudinal cutoff,
\texttt{CUTOFFLONG} see~Table~\ref{distattrgauss}, and is given by:
\begin{align*}
t_{E}(\texttt{CUTOFFLONG}) &= \mathrm{FWHM}_{P} - \frac{1}{2} (\mathrm{FWHM}_{R} + \mathrm{FWHM}_{F})
+ \texttt{CUTOFFLONG} (\sigma_{R} + \sigma_{F}) \\
&= \mathrm{FWHM}_{P} + \frac{\texttt{CUTOFFLONG} - \sqrt{2 \ln 2}}{1.6869} (\texttt{TRISE} + \texttt{TFALL})
\end{align*}
Finally, we can also impose oscillations over the flat-top portion of the laser pulse in Figure~\ref{flattop},
$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
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$.
\subsection{Correlations for \texttt{GAUSS} Distribution (Experimental)}
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of additional distribution attributes for a \texttt{GAUSS}
distribution type for generating correlations in the beam.}
\label{tab:distattrcorrgauss}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{CORRX} & \index{CORRX} {0.0} & Section~\ref{unitsdistattributes} & $x$, $p_x$ correlation.
($R_{12}$ in transport notation.) \\
%\hline
\texttt{CORRY} & \index{CORRY} {0.0} & Section~\ref{unitsdistattributes} & $y$, $p_y$ correlation.
($R_{34}$ in transport notation.) \\
%\hline
\texttt{CORRZ} & \index{CORRZ} {0.0} & Section~\ref{unitsdistattributes} & $z$, $p_z$ correlation.
($R_{56}$ in transport notation.) \\
%\hline
\texttt{R51} & \index{R51} {0.0} & Section~\ref{unitsdistattributes} & $x$, $z$ correlation.
($R_{51}$ in transport notation.) \\
%\hline
\texttt{R52} & \index{R52} {0.0} & Section~\ref{unitsdistattributes} & $p_x$, $z$ correlation.
($R_{52}$ in transport notation.) \\
%\hline
\texttt{R61} & \index{R61} {0.0} & Section~\ref{unitsdistattributes} & $x$, $p_z$ correlation.
($R_{61}$ in transport notation.) \\
%\hline
\texttt{R62} & \index{R62} {0.0} & Section~\ref{unitsdistattributes} & $p_x$, $p_z$ correlation.
($R_{62}$ in transport notation.) \\
\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$.
The correlation coefficient matrix $\sigma$ in $x$, $p_x$, $z$, $p_z$ phase space reads:
\begin{equation*}
\sigma= \left[
\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*}
The Cholesky decomposition of the symmetric positive-definite matrix $\sigma$ is $\sigma=\transpose{C}C$, then the correlated
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*}
\sigma= \left[
\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:
\begin{verbatim}
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;
\end{verbatim}
\index{Distribution!GAUSS|)}
\section{\texttt{FLATTOP} Distribution Type}
\label{sec:flattopdisttype}
\index{Distribution!FLATTOP|(}
\FloatBarrier
The \texttt{FLATTOP} distribution type is used to define hard edge beam distributions. Hard edge, in this case, means
a more or less uniformly filled cylinder of charge, although as we will see this is not always the case. The main purpose
of the \texttt{FLATTOP} is to mimic laser pulses in photoinjectors, and so we usually will make this an \emph{emitted}
distribution. However it can be \emph{injected} as well.
\subsection{Injected \texttt{FLATTOP}}
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
with a uniform distribution in $z$. (Basically a cylinder with an elliptical cross section.)
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of the basic distribution attributes for an \emph{injected} \texttt{FLATTOP} distribution type.}
\label{tab:distattrflattopinj}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & Hard edge width in $x$ direction. \\
%\hline
\texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & Hard edge width in $y$ direction. \\
%\hline
\texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & Hard edge radius. If nonzero \texttt{SIGMAR} overrides \texttt{SIGMAX} and \texttt{SIGMAY}. \\
%\hline
\texttt{SIGMAZ} & \index{SIGMAZ} {0.0} & {m} & Hard edge length in $z$ direction. \\
\hline
\end{tabularx}
\end{center}
\end{table}
\subsection{Emitted \texttt{FLATTOP}}
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Definition of the basic distribution attributes for an \emph{emitted} \texttt{FLATTOP} distribution type.}
\label{tab:distattrflattopemit}
\begin{tabularx}{\textwidth - 1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{SIGMAX} & \index{SIGMAX} {0.0} & {m} & Hard edge width in $x$ direction. \\
%\hline
\texttt{SIGMAY} & \index{SIGMAY} {0.0} & {m} & Hard edge width in $y$ direction. \\
%\hline
\texttt{SIGMAR} & \index{SIGMAR} {0.0} & {m} & Hard edge radius. If nonzero \texttt{SIGMAR} overrides \texttt{SIGMAX} and \texttt{SIGMAY}. \\
%\hline
\texttt{SIGMAT} & \index{SIGMAT} {0.0} & {s} & RMS rise and fall of half Gaussian in flat top defined in
in Figure~\ref{flattop}. \\
%\hline
\texttt{TPULSEFWHM} & \index{TPULSEFWHM} {0.0} & {s} & Flat top time. See Figure~\ref{flattop}. \\
%\hline
\texttt{TRISE} & \index{TRISE} {0.0} & {s} & Rise time. See Figure~\ref{flattop}. If defined will override
\texttt{SIGMAT}. \\
%\hline
\texttt{TFALL} & \index{TFALL} {0.0} & {s} & Fall time. See Figure~\ref{flattop}. If defined will override
\texttt{SIGMAT}. \\
%\hline
\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. \\
%\hline
\texttt{FTOSCPERIODS} & \index{FTOSCPERIODS} {0} & None & Defines the number of oscillation periods imposed on the flat top,
$t_\mathrm{flattop}$, in Figure~\ref{flattop}. \\
%\hline
\texttt{LASERPROFFN} & \index{LASERPROFFN} & None & File name containing measured laser image. \\
%\hline
\texttt{IMAGENAME} & \index{IMAGENAME} & None & Name of the file containing the laser image. \\
%\hline
\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. \\
\hline
\end{tabularx}
\end{center}
\end{table}
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
and a longitudinal (time) distribution with a Gaussian rise and fall time as described in Section~\ref{gaussdisttypephotoinjector}.
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,
in time, {10}{ps} long with a {0.5}{ps} rise and fall time as defined in Figure~\ref{flattop}.
\begin{verbatim}
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;
\end{verbatim}
\index{Distribution!FLATTOP|)}
\subsection{Transverse Distribution from Laser Profile (Under Development)}
\index{Distribution!Laser Profile}
An alternative to using a uniform, elliptical transverse profile is to define the \texttt{LASERPROFFN}, \texttt{IMAGENAME} and
\texttt{INTENSITYCUT} attributes from Table~\ref{distattrflattopemit}. Then, \textit{OPAL-t} will use the laser image as the basis
to sample the transverse distribution.
\textbf{\emph{This distribution option is not yet available.}}
\subsection{\texttt{GUNGAUSSFLATTOPTH} Distribution Type}
\label{sec:gungaussflattopthdisttype}
\index{Distribution!GUNGAUSSFLATTOPTH}
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}.
\subsection{\texttt{ASTRAFLATTOPTH} Distribution Type}
\label{sec:astraflattopthdisttype}
\index{Distribution!ASTRAFLATTOPTH}
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.
\section{\texttt{BINOMIAL} Distribution Type}
\label{sec:binomialdisttype}
\index{Distribution!BINOMIAL}
\FloatBarrier
The \texttt{BINOMIAL} type of distribution is based on \ref{JohoDist}. The shape of the binomial distribution is governed by
one parameter $m$. By varying this single parameter one obtains the most commonly used distributions for our type of simulations,
as listed in Table~\ref{binomdist}.
\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
\tabhead $m$ & Distribution & Density & Profile \\
\hline
{0.0} & Hollow shell & $\frac{1}{\pi}\delta(1-r^2)$ &$\frac{1}{\pi}(1-r^2)^{-0.5}$\\
%\hline
{0.5} & Flat profile & $\frac{1}{2\pi}(1-r^2)^{-0.5}$ & $\frac{1}{2}$\\
%\hline
{1.0} & Uniform & $\frac{1}{\pi}$ & $\frac{2}{\pi}(1-x^2)^{0.5}$\\
%\hline
{1.5} & Elliptical & $\frac{3}{2\pi}(1-r^2)^{0.5}$ & $\frac{1}{4}(1-x^2)$ \\
%\hline
{2.0} & Parabolic & $\frac{2}{\pi}(1-r^2)$ & $\frac{3}{8\pi}(1-x^2)^{1.5}$ \\
%\hline
$\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}) $ \\
\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.
\subsection{Emission Model: \texttt{NONE} (default)}
\index{Emission Model!NONE}
The emission model \texttt{NONE} is the default emission model used in \textit{OPAL-t}. It has a single attribute, listed in
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
as it leaves the cathode.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Attributes for the \texttt{NONE} and \texttt{ASTRA} emission models.}
\label{tab:distattremitmodelnoneastra}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{EKIN} & \index{EKIN} {1.0} &{eV} & Thermal energy added to beam during emission. \\
\hline
\end{tabularx}
\end{center}
\end{table}
An example of using the \texttt{NONE} emission model is given below. This option allows us to emit transversely cold
(zero x and y emittance) beams into our simulation. We must add some z momentum to ensure that the particles drift into
the simulation space. If in this example one were to specify \texttt{EKIN = 0}, then you would likely get strange results
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.
\begin{verbatim}
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;
\end{verbatim}
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
particles.
\subsection{Emission Model: \texttt{ASTRA}}
\index{Emission Model!ASTRA}
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
added to each emitted particle's momentum in a random way:
\begin{equation*}
\begin{aligned}
p_{total} &= \sqrt{\left(\frac{\texttt{EKIN}}{mc^{2}} + 1\right)^{2} - 1} \\
p_{x} &= p_{total} \sin(\phi) \cos(\theta)) \\
p_{y} &= p_{total} \sin(\phi) \sin(\theta)) \\
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$.
\subsection{Emission Model: \texttt{NONEQUIL}}
\index{Emission Model!NONEQUIL}
The \texttt{NONEQUIL} emission model is based on an actual physical model of particle emission as described in
\ref{flo:97, clen:2000, dowe:2009}. The attributes needed by this emission model are listed in
Table~\ref{distattremitmodelnonequil}.
\begin{table}[!htb]
\begin{center}\footnotesize
\caption{Attributes for the \texttt{NONE} and \texttt{ASTRA} emission models.}
\label{tab:distattremitmodelnonequil}
\begin{tabularx}{\textwidth-1cm}{|l|c|c|X|}
\hline
\tabhead Attribute Name & Default Value & Units & Description \\
\hline
\texttt{ELASER} & \index{ELASER} {4.86} & {eV} & Photoinjector drive laser energy. (Default is {255}{nm} light.) \\
%\hline
\texttt{W} & \index{W} {4.31} & {eV} & Photocathode work function. (Default is atomically clean copper.) \\
%\hline
\texttt{FE} & \index{FE} {7.0} & {eV} & Fermi energy of photocathode. (Default is atomically clean copper.) \\
%\hline
\texttt{CATHTEMP} & \index{CATHTEMP} {300.0} & {\kelvin} & Operating temperature of photocathode. \\
\hline
\end{tabularx}
\end{center}
\end{table}
An example of using the \texttt{NONEQUIL} emission model is given below. This model is relevant for metal
cathodes and cathodes such as $CsTe$.
\begin{verbatim}
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;
\end{verbatim}
\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
in the \texttt{RUN} command see~Chapter~\ref{track}. Assume we have defined several distributions: \texttt{DIST1},
\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:
\begin{verbatim}
RUN, METHOD = "PARALLEL-T",
BEAM = beam_name,
FIELDSOLVER = field_solver_name,
DISTRIBUTION = DIST1;
\end{verbatim}
If we want to use all the distributions at the same time, then the command would instead be:
\begin{verbatim}
RUN, METHOD = "PARALLEL-T",
BEAM = beam_name,
FIELDSOLVER = field_solver_name,
DISTRIBUTION = {DIST1, DIST2, DIST3};
\end{verbatim}
In this second case, the first distribution (\texttt{DIST1}) is the master distribution. The main consequence of this is that
all distributions in the list will be forced to the same \texttt{EMITTED} condition as \texttt{DIST1}. So, if \texttt{DIST1}
is to be \emph{emitted}, then all other distributions in the list will be forced to this same condition. If \texttt{DIST1} is
to be \emph{injected}, then all other distribution is the list will also be \emph{injected}.
The number of particles in the simulation is defined in the \texttt{BEAM} command see~Chapter~\ref{beam}. The number
of particles in each distribution in a distribution list is determined by this number and the \texttt{WEIGHT} attribute
of each distribution (Table~\ref{distattruniversal}). If all distributions have the same \texttt{WEIGHT} value, then
the number of particles will be divided up evenly among them. If, however we have a distribution list consisting of
two distributions, and one has twice the \texttt{WEIGHT} of the other, then it will have twice the particles as its partner.
The exception here is any \texttt{FROMFILE} distribution type. In this case, the \texttt{WEIGHT} attribute and the number of
particles in the \texttt{BEAM} command are ignored. The number of particles in any \texttt{FROMFILE} distribution type is
defined by the text file containing the distribution particle coordinates. (Section~\ref{fromfiledisttype}).
\index{Distribution Command|)}
\input{footer}