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

\chapter{Introduction to \MCX}

Efficient design and optimization of x-ray beamlines are
formidable challenges. In many cases Monte Carlo techniques are well matched to meet
these challenges. 
\MCX is an effort to port the framework provided to the neutron scattering
community by the \MCS package, to x-ray scattering. \MCS has, since its
inception in October '98, been used successfully at all major neutron
scattering facilities in the world. A particular power of \MCS is its geometry
engine, which has been adopted by \MCX, with little modification. The device
library of \MCX is not yet as complete as its sibling \MCS but is growing
rapidly.
At the time of writing it is complete enough to be able to perform simulations
approximating any standard beamline.

\MCX is a fast and versatile software tool.
It is based on a meta-language specially designed for x-ray (and neutron)
simulation. Specifications are written in this language by users and
automatically translated into efficient simulation codes in ANSI-C.
The present version supports both continuous and pulsed source beamlines, and includes a library of standard
components with total around 100 components.

The \MCX\ package is written in ANSI-C and is freely available for download
from the \MCX\ website~\cite{mcxtrace_webpage}. The package is actively
developed and supported by \DTUPHYSlong, \NBIlong, \ESRFlong and SAXSLAB Aps.
The system is tested and is supplied with examples and documentation.
Besides this manual, a separate component manual exists which details each individual component separately.

\section{Development of Monte Carlo x-ray simulation}
Monte Carlo simulation of x-ray instrumentation has been used for many years --- in particular the SHADOW package 
\cite{welnak1994shadow,sanchez2011shadow3}
has found widespread use, and is still actively developed, yet has some
limitations. \emph{Ray}\cite{schaefers2008bessy} and \emph{Xtrace}\cite{bauer2007simulation} are other packages using the same
basic techniques. 

What sets \MCX\ apart is, among other things, its open source
development strategy and its inherent modularity. 
This combination lets independent scientists work indepently on separate
modules that they have use for, and contribute to the whole with only a small
effort.

\section{Scientific background}
What makes scientists happy? Probably to collect good quality data, pushing beamlines to their limits, and fit that data to physical models.
Among available measurement techniques, x-ray scattering provides a
large variety of beamlines to probe structure and dynamics of all
kinds of samples.

Achieving a satisfactory experiment on the best beamline is not all. Once collected, the data analysis process
raises some questions concerning the signal: what is the background
signal? What proportion of coherent and incoherent scattering has
been measured? What are the contributions from the sample geometry, the
container, the sample environment, and generally the beamline
itself? And last but not least, how does multiple scattering affect the
signal? Most of the time, the physicist will elude these questions
using rough approximations, or applying analytical corrections
\cite{Copley86}. Monte-Carlo techniques provide a mean to evaluate
some of these quantities. The technicalities of Monte-Carlo simulation
techniques are explained in detail in \cref{c:MCtechniques}.


\subsection{The goals of \MCX}
\label{s:goals}

Initially, the \MCS project and hence also the present subject the \MCX project had four main objectives
that determined its design.

\paragraph{Correctness.}
It is essential to minimize the potential for bugs in computer
simulations.  If a word processing program contains bugs, it will
produce bad-looking output or may even crash. This is a nuisance, but at
least you know that something is wrong. However, if a simulation
contains bugs it produces wrong results, and unless the results are far
off, you may not know about it! Complex simulations involve hundreds or
even thousands of lines of formulae, making debugging a major issue. Thus the
system should be designed from the start to help minimize the potential
for bugs to be introduced in the first place, and provide good tools for
testing to maximize the chances of finding existing bugs.
%
\paragraph{Flexibility.}
When you commit yourself to using a tool for an important project, you
need to know if the tool will satisfy not only your present, but also
your future requirements. The tool must not have fundamental limitations that
restrict its potential usage. Thus the \MCX systems needs to be
flexible enough to simulate different kinds of instruments
as well as many different kind of
optical components, and it must also be extensible so that future, as
yet unforeseen, needs can be satisfied.
%
\paragraph{Power.}
``\textit{Simple things should be simple; complex things should be possible}''.
New ideas should be easy to try out, and the time from thought to action
should be as short as possible. If you are faced with the prospect of programming for
two weeks before getting any results on a new idea, you will most likely drop
it. Ideally, if you have a good idea at lunch time, the simulation
should be running in the afternoon.
%
\paragraph{Efficiency.}
Monte Carlo simulations are computationally intensive, hardware capacities
are finite (albeit impressive), and humans are impatient. Thus the
system must assist in producing simulations that run as fast as
possible, without placing unreasonable burdens on the user in order to
achieve this.


\section{The design of \MCX}
\label{s:design}

In order to meet these ambitious goals, it was decided that \MCX should
be based on its own meta-language, specially designed for
simulating scattering beamlines. Simulations are written in
this meta-language by the user, and the \MCX compiler automatically
translates them into efficient simulation programs written in ANSI-C.

In realizing the design of \MCX, the task was
separated into four conceptual layers:
\begin{enumerate}
\item Modeling the physical processes of scattering, \textit{i.e}.\
  the calculation of the fate of a photon that passes through the
  individual components of the beamline (absorption, scattering at a
  particular angle, etc.)
\item Modeling of the overall beamline geometry, mainly consisting
  of the type and position of the individual components.
\item Accurate calculation, using Monte Carlo techniques, of
  beamline properties such as resolution function from the result of
  ray-tracing of a large number of photons. This includes estimating
  the accuracy of the calculation.
\item Presentation of the calculations, graphical or otherwise.
\end{enumerate}

Though obviously interrelated, these four layers can be
treated independently, and this is reflected in the overall system
architecture of \MCX. The user will in many situations be
interested in knowing the details only in some of the layers. For
example, one user may merely look at some results prepared by others,
without worrying about the details of the calculation. Another user
may simulate a new instrument without having to reinvent the
code for simulating the individual components in the instrument. A third
user may write an intricate simulation of a complex component,
e.g. a detailed description of a high resolution fast chopper,
and expect other users to easily
benefit from his/her work, and so on. \MCX attempts to make it
possible to work at any combination of layers in isolation by separating
the layers as much as possible in the design of the system and in
the meta-language in which simulations are written.

The usage of a special meta-language and an automatic compiler has
several advantages over writing a big monolithic program or a set of
library functions in C, Fortran, or another general-purpose programming
language.  The meta-language is more \textit{powerful}; specifications
are much simpler to write and easier to read when the syntax of the
specification language reflects the problem domain. For example, the
geometry of beamlines would be much more complex if it were specified
in C code with static arrays and pointers. The compiler can also take
care of the low-level details of interfacing the various parts of the
specification with the underlying C implementation language and each
other. This way, users do not need to know about \MCX\ internals to
write new component or beamline definitions, and even if those
internals change in later versions of \MCX, existing definitions can be
used without modification.

The \MCX system also utilizes the meta-language to let the \MCX
compiler generate as much code as possible automatically, letting the
compiler handle some of the things that would otherwise be the task of
the user/programmer. \textit{Correctness} is improved by having a well-tested
compiler generate code that would otherwise need to be specially written
and debugged by the user for every beamline or component. \textit{Efficiency}
is also improved by letting the compiler optimize the generated code in
ways that would be time-consuming or difficult for humans to do. Furthermore, the
compiler can generate several different simulations from the same
specification, for example to optimize the simulations in different
ways, to generate a simulation that graphically displays x-ray
trajectories, and possibly other things in the future that were not even
considered when the original instrument specification was written.

The design of \MCX makes it well suited for doing ``what if\ldots''
types of simulations. Once an instrument has been defined, questions
such as ``what if a slit was inserted'', ``what if a focusing
monochromator was used instead of a flat one'', ``what if the sample was
offset 0.2\ mm from the center of the axis'' and so on are easy to answer. Within
minutes the beamline definition can be modified and a
new simulation program generated. It also makes it simple to debug new
components. A test beamline definition may be written
containing a source, the component to be tested, and whatever
monitors are useful, and the component can be thoroughly tested before
being used in a complex simulation with many different components.

The \MCX system is based on ANSI-C, making it both efficient and
portable. The meta-language allows the user to embed arbitrary C code in
the specifications. \textit{Flexibility} is thus ensured since the full
power of the C language is available if needed.


\section{Overview}

The \MCX system documentation consists of the following major
parts:
\begin{itemize}
\item A short list of new features introduced in this \MCX release
  appears in chapter~\ref{c:changes}
\item Chapter~\ref{c:install} explains how to obtain, compile
  and install the \MCX compiler, associated files and supportive software
\item Chapter~\ref{c:MCtechniques} concerns Monte Carlo techniques
  and simulation strategies in general
\item Chapter~\ref{c:running} includes a brief introduction to the
  \MCX system (\cref{s:running}) on running the compiler to produce
  simulations. \cref{s:run-sim} explains how to run the generated
  simulations. Running \MCX on parallel computers requires special
  attention and is discussed in section~\ref{s:run-mpi}. A number of front-end programs are used to run the
  simulations and to aid in the data collection and analysis of the
  results. These user interfaces are described in section~\ref{s:frontends}.
\item The \MCX meta-language is described in chapter~\ref{s:kernel}. This
  chapter also describes a set of library functions and definitions
  that aid in the writing of simulations. See
  appendix~\ref{c:kernelcalls} for more details.
\item The \MCX component library contains a collection of
  well-tested, as well as user contributed, beam components that can be used in simulations.
  The \MCX component library is documented in a separate manual
  and on the \MCX web-page~\cite{mcxtrace_webpage}, but a short overview of these
  components is given in chapter~\ref{s:components} of the Manual.
\end{itemize}

A list of library calls that may be used in component definitions
appears in appendix~\ref{c:kernelcalls}, and
an explanation of the \MCX terminology can be
found in appendix~\ref{s:terminology} of the Manual.
Plans for future extensions are as a rule presented on the \MCX web-page~\cite{mcxtrace_webpage}.


