% Emacs settings: -*-mode: latex; TeX-master: "manual.tex"; -*-

\chapter{Source components}
\label{c:sources}
\index{Sources|textbf}
\index{Library!Components!sources}

\MCX\ contains a number of different source components,
and any simulation will usually contain exactly one of these sources.
The main function of a source is to determine a set of initial
parameters $(\mathbf{r}, \mathbf{k}, t)$
for each photon ray. This is done by Monte Carlo choices from
suitable distributions. For example, in most present sources
the initial position is
found from a uniform distribution over the source surface.
The initial photon wavenumber
is selected within an interval of either the corresponding energy or the corresponding wavelength.

For pulsed sources, the choice of the emission time, $t$,
is being made on basis of detailed analytical expressions.
For other sources, $t$ is set to zero.
In the case one would like to use a steady state source
with time-of-flight settings,
the emission time of each photon ray should be determined using
a Monte Carlo choice. This may be achieved by
the \verb+EXTEND+ keyword in the instrument description source
as in the example below:\index{Keyword!EXTEND}

\begin{verbatim}
  TRACE

  COMPONENT MySource=Source_pt(...) AT (...)
  EXTEND
  %{
    t = 1e-3*randpm1(); /* set time to +/- 1 ms */
  %}
\end{verbatim}
Also take a look at the \textbf{Chopper\_simple} component.

\subsection{Photon flux and Brilliance}
\label{s:xray-flux}
The flux of the sources deserves special attention. The total
intensity is defined as the sum of weights of all emitted x-rays
during one simulation
(the unit of total photon weight is thus photons per second).
The flux, $\psi$, at an instrument is defined as intensity per area perpendicular
to the beam direction.

The source Brilliance, $\Phi$, is defined in different units (See e.g. \cite{als2011elements}):
the number of photon rays emitted per second from a
\SI{1}{\square mm} area on the source surface,
with direction within a 1~\si{\square m \radian} angle window,
and with wavelength within a 1\% interval.
The total intensity of real photons emitted towards a given diaphragm
(units: ph./s) is therefore (for constant $\Phi$):
\begin{equation}
I_\mathrm{total} = \Phi A \Delta\Omega \Delta\lambda ,
\end{equation}
where $A$ is the source area, $\Delta\Omega$ is the solid angle of the
diaphragm as seen from the source surface, and $\Delta\lambda$ is the
width of the wavelength interval in which photons are emitted (assuming
a uniform wavelength spectrum).

The simulations are performed so that detector intensities
are independent of the number of photon histories simulated
(although more photon histories will give better statistics).
If $N_\mathrm{sim}$ denotes the number of
x-ray histories to simulate, the initial photon weight $p_0$ must be set to
\begin{equation}
\label{proprule}
p_0 = \frac{N_\mathrm{total}}{N_\mathrm{sim}} =
    \frac{\Phi(\lambda)}{N_\mathrm{sim}} A \Omega \Delta\lambda ,
\end{equation}
where the source brilliance is now given a $\lambda$-dependence.

As a start, we recommend new \MCX\ users to use the
\textbf{Source\_flat} component.
For a slightly more realistic sources are supply \textbf{Source\_flat} with a spectrum file (for instance
generated by SPECTRA~\cite{spectra}) or \textbf{Source\_gaussian}.

Optimizers can dramatically improve the statistics, but may occasionally
give wrong results, due to misleaded optimization.
You should always check such simulations with (shorter) non-optimized ones.

Other ways to speed-up simulations are to read events from a file.
See section \ref{s:sources-seealso} for details.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.75\textwidth]{figures/sources.eps}
  \end{center}
\caption{A circular source component (at z=0) emitting photon rays randomly, either from a model, or from a data file.}
\label{f:source}
\end{figure}

\newpage
\input{sources/Source_pt}

\input{sources/Source_flat}

\input{sources/Source_div}

\input{sources/Source_gaussian}

\input{sources/Source_lab}

\newpage

%\input{moderator}
%\input{ISISdoc.tex}
%\newpage

%\input{Source_adapt}

%\input{Adapt_check}

%\newpage
%\input{Source_Optimizer}

%\input{Monitor_Optimizer}

%\newpage
%\section{Other sources components: contributed pulsed sources, virtual sources (event files)}
%\label{sources-seealso}
\section{Other sources components: virtual sources (event files)}
\label{s:sources-seealso}

%There are many other source definitions in \MCX .

%Detailed pulsed source components are available for new facilities
%in a number of contributed components:
%\begin{itemize}
%\item SNS (\textbf{contrib/SNS\_source}),
%\item ISIS (\textbf{contrib/ISIS\_moderator}) see section \ref{isis-moderator},
%\item ESS-project (\textbf{ESS\_moderator\_long} and \textbf{ ESS\_moderator\_short}).
%\end{itemize}

%When no analytical model (e.g. a Maxwellian distribution) exits,
%one may have access to measurements, estimated flux distributions,
%event files, and - better - to MCNP/Triploli4 neutron event records.
%The following components are then useful:

%\begin{itemize}
%\item{\textbf{misc/Virtual\_input} can read a \MCX\ event file
%(in text or binary format), often bringing an order-of-magnitude speed-up.
%See section \ref{virtual_input}.}
%\item{\textbf{contrib/Virtual\_tripoli4\_input} does the same, but from event files (text format) obtained from the \emph{Tripoli4} \cite{tripoli_webpage} reactor simulation program. Such files are usually huge.\index{Tripoli}}
%\item{\textbf{contrib/Virtual\_mcnp\_input} can read MCNP "PTRAC" event files (text format) obtained from the \emph{MCNP} \cite{mcnp_webpage} reactor simulation program. Such files are usually huge.\index{MCNP}}
%\item{\textbf{misc/Vitess\_input} can read \emph{Vitess} \cite{vitess_webpage} neutron event binary files.\index{Vitess}}
%\item{\textbf{optics/Filter\_gen} reads a 1D distribution from a file, and may either modify or set the flux according to it. See section \ref{filter-gen}.}
%\end{itemize}

%\begin{itemize}
%\item{\textbf{misc/Virtual\_input} can read a \MCX\ event file
%(in text or binary format), often bringing an order-of-magnitude speed-up.
%See section \ref{virtual_input}.}

