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

\chapter{Introduction to \MCS}

Efficient design and optimization of neutron spectrometers are
formidable challenges, which are efficiently treated by Monte Carlo
simulation techniques.
When \MCS version 1.0 was released in October
1998, except for the NISP/MCLib program~\cite{nisp_webpage}, no existing package offered a general framework for the neutron
scattering community to tackle the problems currently faced at reactor and
spallation sources. The \MCS project was designed to provide such a framework.

\MCS %({\em Monte Carlo Simulations of Triple Axis Spectrometers\/})
is a fast and versatile software tool for neutron ray-tracing simulations.
It is based on a meta-language specially designed for neutron
simulation. Specifications are written in this language by users and
automatically translated into efficient simulation codes in ISO-C.
The present version supports both continuous and pulsed source instruments, and includes a library of standard
components with in total around 130 components. These enable to simulate all kinds of neutron scattering instruments (diffractometers, spectrometers, reflectometers, small-angle, back-scattering,...) for both continuous and pulsed sources.

The core \MCS package is written in ISO-C, with various tools based
on Perl and Python and is freely available for download
from the \MCS website~\cite{mcstas_webpage}. The package is actively
being developed and supported by DTU Physics,
Institut Laue Langevin (ILL), Paul Scherrer Institute and the Niels
Bohr Institute (NBI).
The system is well tested and
is supplied with several examples and with an extensive documentation.
Besides this manual, a separate component manual exists.

The release at hand \MCS \version is a major upgrade from the last
release, mainly because of our switch to the use of a Python user
interface layer. (The perl-based layer is still available, but we
recommend and encourage use of the new Python layer, since this is
where our efforts will go from this point.)

Porting your existing personal instrument files and
components should be trivial, but if you experience problems feel free
to contact  \verb+mcstas-users@mcstas.org+ or the authors.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Development of Monte Carlo neutron simulation}
The very early implementations of the method for neutron instruments used \emph{home-made} computer programs  (see e.g. papers by J.R.D. Copley, D.F.R. Mildner, J.M. Carpenter, J. Cook), more general packages have been designed, providing models for most parts of the simulations.
These present existing packages are: NISP \cite{NISP}, ResTrax
\cite{Restrax}, \MCS\cite{mcs_ppf,nn_10_20,mcstas_pb,mcs_ppf,mcstas_webpage},
Vitess \cite{Vitess,vitess_webpage}, IDEAS \cite{IDEAS} and IB (Instrument
Builder) \cite{IB_webpage}. Supplementing the Monte Carlo based
methods, various analytic phase-space simulation methods exist,
including Neutron Acceptance Diagram Shading (NADS) \cite{NADS_webpage}.
Their usage usually covers all types of neutron spectrometers, most of the time through a user-friendly graphical interface, without requiring programming skills.

The neutron ray-tracing Monte-Carlo method has been used widely for
{\em e.g.}\ guide studies \cite{Copley93,Farhi02,Schanzer04},
instrument optimization and design \cite{Zsigmond04,Lieutenant05}.
Most of the time, the conclusions and general behavior of such studies
may be obtained using the classical analytic approaches,
but accurate estimates for the flux, the resolutions,
and generally the optimum parameter set, benefit advantageously from MC methods.

Recently, the concept of virtual experiments, {\em i.e.}\ full simulations
of a complete neutron experiment, has been suggested as a major asset for neutron ray-tracing simulations. The goal is that
simulations should be of benefit to not only instrument builders, but also
to users for training, experiment planning, diagnostics, and data
analysis.

In the late 90'ies at Ris\o\ National Laboratory,
simulation tools were urgently needed,
not only to better utilize existing instruments
({\em e.g.} RITA-1 and RITA-2~\cite{cjp_73_697,pb_241_50,pb_283_343}),
but also to plan completely new instruments for new sources
({\em e.g.} the Spallation Neutron Source, SNS~\cite{sns_webpage}
and the planned European Spallation Source, ESS~\cite{ess_webpage}).
Writing programs in C or FORTRAN for
each of the different cases involves a huge effort, with debugging presenting
particularly difficult problems. A higher level tool specially designed
for simulating neutron instruments was needed. As there was
no existing simulation software that would fulfill our needs, the \MCS
project was initiated.
In addition, the ILL required an efficient and general simulation
package in order to achieve renewal of its instruments and guides.
A significant contribution to both the component library and the \MCS
kernel itself was early performed at the ILL and included in the package.
ILL later became a part of the core \MCS team.
Similarly, the PSI has applied \MCS extensively for instrument design
and upgrades, provided important component additions and contributed
several systematic comparative studies of the European instrument
Monte Carlo codes. Hence, PSI has also become a part of the core \MCS
team. 
Since year 2001 Ris\o\ was no longer a neutron source, and the authors
from that site have moved on to positions at University of Copenhagen
(NBI) and Technical University of Denmark (DTU Physics), hence these
two partners have joined the core \MCS team.
Finally, trough general emphasis on use of \MCS as a tool for
simulating the ESS instruments and virtual data, plus the partial
secondment of one DTU-based \MCS author, the ESS Data Management and
Software Centre (ESS DMSC) is now contributing to the projecte.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Scientific background}
What makes scientists happy? Probably collect good quality data, pushing the instruments to their limits, and fit that data to physical models.
Among available measurement techniques, neutron scattering provides a
large variety of spectrometers to probe structure and dynamics of all
kinds of materials.

Neutron scattering instruments are built as a series of neutron optics elements. Each of these elements modifies the beam characteristics (e.g. divergence, wavelength spread, spatial and time distributions) in a way which, for simple neutron beam configurations, may be modeled with analytic methods. This is valid for individual elements such as guides \cite{Leibnitz63,Mildner90}, choppers \cite{Lowde60,Copley03}, Fermi choppers \cite{Fermi47,Peters05}, velocity selectors \cite{Clark66}, monochromators \cite{Freund83,Sears97,Shirane02,Alianelli04}, and detectors \cite{Radeka74,Charpak89,Manzin04}. In the case of a limited number of optical elements, the so-called acceptance diagram theory \cite{Mildner90,Copley93,Cussen03} may be used, within which the neutron beam distributions are considered to be homogeneous, triangular or Gaussian.
However, real neutron instruments are constituted of a large number of optical elements, and this brings additional complexity by introducing strong correlations between neutron beam parameters like divergence and position - which is the basis of the acceptance diagram method - but also wavelength and time. The usual analytic methods, such as phase-space theory, then reach their limit of validity in the description of the resulting effects.

In order to cope with this difficulty, Monte Carlo (MC) methods (for a general review, see Ref.~\cite{James80}) may be applied to the simulation of neutron instruments.
The use of probability is common place in the description of microscopic physical processes. Integrating these events (absorption, scattering, reflection, ...) over the neutron trajectories
results in an estimation of measurable quantities characterizing the neutron instrument. Moreover, using variance reduction (importance sampling)
where possible, reduces the computation time and gives better accuracy.

Early implementations of the MC method for neutron instruments used \emph{home-made} computer programs  (see \cite{Copley86,Mildner77}) but, more recently, general packages have been designed, providing models for most optical components of neutron spectrometers.
The most widely-used packages are NISP \cite{NISP}, ResTrax \cite{Restrax}, \MCS \cite{mcs_ppf,nn_10_20,mcstas_webpage}, Vitess \cite{Vitess}, and IDEAS \cite{IDEAS}, which allow a wide range of neutron scattering instruments to be simulated.

The neutron ray-tracing Monte Carlo method has been used widely for
guide studies \cite{Copley93,Farhi02,Schanzer04}, instrument
optimization and design \cite{Zsigmond04,Lieutenant05}. Most of the
time, the conclusions and general behavior of such studies may be
obtained using the classical analytic approaches, but accurate
estimates for the flux, resolution and generally the optimum parameter
set, benefit considerably from MC methods, see Chapter~\ref{s:MCtechniques}.

Neutron instrument resolution (in $q$ and $E$) and flux are often limitations in the
experiments. This then motivates instrument responsibles to improve
the resolution, flux and overall efficiency at the spectrometer positions, and
even to design new machines. Using both analytic and numerical
methods, optimal configurations may be found.

But achieving a satisfactory experiment on the best neutron
spectrometer 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? Is possible to identify clearly the purely elastic
(structure) contribution from the quasi-elastic and inelastic one
(dynamics)? What are the contributions from the sample geometry, the
container, the sample environment, and generally the instrument
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 analytic corrections
\cite{Copley86}. Monte-Carlo techniques also provide means to evaluate
some of these quantities.

Technicalities of Monte-Carlo simulation
techniques are explained in detail in Chapter~\ref{s:MCtechniques}.

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

Initially, the \MCS project had four main objectives
that determined its design.

\paragraph{Correctness.}
\index{Bugs!hard to detect}
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 \MCS 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 \MCS}
\label{s:design}
\index{McStas!design}
\index{Meta-language}

In order to meet these ambitious goals, it was decided that \MCS should
be based on its own \emph{meta-language} (also known as \emph{domain-specific language}), specially designed for
simulating neutron scattering instruments. Simulations are written in
this language by the user, and the \MCS compiler automatically
translates them into efficient simulation programs written in ISO-C.

In realizing the design of \MCS, the task was
separated into four conceptual layers, listed below and also detailed
in Figure \ref{fig:structure}
\begin{enumerate}
\item Graphical user interface and scripting layer, presentation of
  the calculations, graphical or otherwise. (aka. the tool layer).
\item Modeling of the overall instrument geometry, mainly consisting
  of the type and position of the individual components.
\item Modeling the physical processes of neutron scattering, \textit{i.e}.\
  the calculation of the fate of a neutron that passes through the
  individual components of the instrument (absorption, scattering at a
  particular angle, etc.)
\item Accurate calculation, using Monte Carlo techniques, of
  instrument properties such as resolution function from the result of
  ray-tracing of a large number of neutrons. This includes estimating
  the accuracy of the calculation.
\end{enumerate}

If you don't want to read this manual in full, go directly to the brief introduction in chapter \ref{s:brief}.

Though obviously interrelated, these four layers can be
treated independently, and this is reflected in the overall system
architecture of \MCS. 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 rotating velocity selector,
and expect other users to easily
benefit from his/her work, and so on. \MCS 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 instruments 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 \MCS internals to
write new component or instrument definitions, and even if those
internals change in later versions of \MCS, existing definitions can be
used without modification.

The \MCS system also utilizes the meta-language to let the \MCS
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 instrument 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 neutron
trajectories, and possibly other things in the future that were not even
considered when the original instrument specification was written.

The design of \MCS 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 2~mm from the center of the axis'' and so on are easy to answer. Within
minutes the instrument definition can be modified and a
new simulation program generated. It also makes it simple to debug new
components. A test instrument definition may be written
containing a neutron 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 \MCS system is based on ISO-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 \MCS system documentation consists of the following major
parts:
\begin{itemize}
\item The complete listing of changes related to the version \MCS \version
is available in CHANGES document of the relevant download folder at
\url{http://download.mcstas.org/}. Bugs are reported and traced using
the \MCS GitHub issue system\cite{github_issue_webpage}. We will not
present here an extensive list of corrections, and we let the reader
refer to this bug reporting service for details. Only important
changes are indicated in the CHANGES document.
\item Chapter~\ref{s:MCtechniques} concerns Monte Carlo techniques
  and simulation strategies in general
\item Chapter~\ref{c:running} includes a brief introduction to the
  \MCS system
  (section~\ref{s:brief}) as well a section (\ref{s:running}) on running the compiler to produce
  simulations. Section~\ref{s:run-sim} explains how to run the generated
  simulations. Running \MCS on parallel computers require 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 \MCS meta-language is described in chapter~\ref{c: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 \MCS component library contains a collection of
  well-tested, as well as user contributed, beam components that can be used in simulations.
  The \MCS component library is documented in a separate manual
  and on the \MCS web-page~\cite{mcstas_webpage}, but a short overview of these
  components is given in chapter~\ref{c:components} of the Manual.
  %This
  %library is documented in detail in chapter~\ref{s:components}. Code
  %for the components can be found in appendix~\ref{compcode}.
% FIXME \item A collection of example instrument definitions is described in
% FIXME  chapter~\ref{c:instrument} of the Manual.%, with source code given in appendix~\ref{instcode}.

\end{itemize}

%In addition, some results from
%simulations with \MCS are described in
%appendix~\ref{testresults}.
As of this release of \MCS support for simulating neutron
polarization is strongly improved, e.g. by allowing nested magnetic
fields, tabulated magnetic fields in numerical input files and by close
to ``full'' support of polarization in all components. As this is the
first stable release with these new features, functionality is likely to change. To reflect this, the
documentation is still only available in the appendix of the Component manual. %~\ref{c:polarization}.
A list of library calls that may be used in component definitions
appears in appendix~\ref{c:kernelcalls}, and
an explanation of the \MCS terminology can be
found in appendix~\ref{s:terminology} of the Manual..
%Plans for future extensions are presented on the \MCS web-page~\cite{mcstas_webpage} as well as in section~\ref{s:future}.


%The \MCS package consists of four levels:
%\paragraph{The kernel.} Here are located some geometrical tools
%({\em e.g.} intersection between a line and various surfaces)
%and other elemental tools ({\em e.g.} creation and annihilation
%of a neutron). The kernel is maintained by the Ris\o\ group.

%\paragraph{The components.} Here resides the code for simulation
% of the individual spectrometer components
% (sources, detectors, samples, and optical elements).
% Components may have input parameters, like the angle of divergence of a
% collimator or the mosaicity of a monochromator crystal.
% Interested users are encouraged to modify existing components and to
% design new ones.
% A library of general and well documented components
% is being maintained by the Ris\o\ group.

%\paragraph{The instruments.} An instrument definition is written
% in the \MCS meta-language, which is a means of positioning
% components within an experimental geometry.
% Instruments may have inout parameters, like {\em e.g.}\ the three
% $(\omega,2\theta)$ pairs of a standard triple-axis spectrometer.
% For each specific instrument, a new instrument definition
% should be written. This will usually be done by the users,
% possibly in collaboration with the Ris\o\ group.

%\paragraph{The instrument control interface.}
% Here, the setting parameters of the
% instrument may be controlled in order to perform a simulation series.

% In the present version 1.0, the control interface
% consists of a very preliminary MATLAB program,
% but we expect soon to implement a simulation version of the
% Ris\o\ spectrometer control software TASCOM.
% By using the preprogrammed scans or the TASCOM programming features,
% the user will then be able easily to perform the desired simulations.
% Later, interfaces to other control software may be implemented.

%\paragraph{Data analysis and visualization}
% The output data is in the present version written as
% plain ASCII format, but will later be written in the TASCOM format,
% from where it may easily be converted into the general
% NeXus format\cite{NeXus}.
% This enables the user to choose between various analysis packages
% for the output side.
% Both ASCII and TASCOM files may be analysed and plotted through
% the Ris\o\ MATLAB package MVIEW/MFIT \cite{mview}.