% Emacs settings: -*-mode: latex; TeX-master: "manual.tex"; -*-
 
\chapter{Introduction to \MCS}

Efficient design and optimization of neutron spectrometers are
formidable challenges. Monte Carlo techniques are well matched to meet
these challenges. 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 instru-
ments, and includes a library of standard
components with in total around 90 components. These enable to simulate all kinds of neutron scattering instruments (diffractometers, triple-axis, reflectometers, small-angle, back-scattering,...) for both continuous and pulsed sources.

The \MCS package is written in ISO-C and is freely available for down-load
from the \MCS web-page~\cite{mcstas_webpage}. The package is actively
being developed and supported by Ris\o\ National Laboratory 
and the Institut Laue Langevin (ILL). 
The system is well tested and
is supplied with several examples and with an extensive documentation.
Besides this component manual, a system manual exists.


\section{Background}

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 the needs of simulating neutron instruments is 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.

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

Initially, the \MCS 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 \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 meta-language, specially designed for
simulating neutron scattering instruments. Simulations are written in
this meta-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:
\begin{enumerate}
\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 Modeling of the overall instrument geometry, mainly consisting
  of the type and position of the individual components.
\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.
\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 \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
detectors 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}

This \MCS Component Manual consists of the following major parts:
\begin{itemize}
\item A thorough description of system components 
from chapter~\ref{c:components}, sorted by categories. 
\item A list of example instruments from the library in chapter~\ref{c:instr_examples}. 
\item The \MCS library functions and definitions
  that aid in the writing of simulations and components in
  Appendix~\ref{c:kernelcalls}.    
\end{itemize}
An explanation of \MCS terminology can be
found in appendix~\ref{s:terminology}.

Additionally, you may refer to the list of example instruments from the library in the \MCS User Manual.

Plans for future component development are presented 
on the \MCS web-page~\cite{mcstas_webpage}.


%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}.