\chapter{About the component library}
\label{c:components}
This \MCX\ Component Manual consists of the following major parts:
\begin{itemize}
\item An introduction to the use of Monte Carlo methods in \MCX .
\item A thorough description of system components,
with one chapter per major category: Sources, optics,
monochromators, samples, monitors, and other components.
\item The \MCX\ library functions and definitions
  that aid in the writing of simulations and components in
  Appendix~\ref{c:kernelcalls}.
%\item A detailed explanation of the use of random numbers
%   in Appendix~\ref{s:random}.
\item An explanation of the \MCX\ terminology in Appendix~\ref{s:terminology}.
\end{itemize}
Additionally, you may refer to the list of example instruments
from the library in the \MCX\ User Manual.

\section{Authorship}
The component library is
maintained by the \MCX\ system group. A number of basic components
``belongs'' the \MCX\ system, and are supported and tested by the \MCX\
team.

Other components are contributed
by specific authors, who are listed in the code for each component
they contribute as well as in this manual.
\MCX\ users are encouraged to send their
contributions to us for inclusion in future releases.

%Some contributed components have later been taken over
%for further development by the \MCX\ system
%group, with permission from the original authors.
%The original authors will still appear both in the component code and in the
%\MCX\ manual.

\section{Symbols for x-ray scattering and simulation}
In the description of the theory behind the component functionality
we will use the usual symbols {\bfseries r} for the position
$(x,y,z)$ of the particle (unit m), and {\bfseries k} for
the particle wave vector $(k_x, k_y, k_z)$ (unit \si{\per\angstrom}).
The wavelength is the reciprocal wave vector,
$\lambda=2 \pi / k$. By convention energy is usually given i \si{keV} and may be calculated from the wavelength by:
$\lambda=\frac{12.398}{E}$

In general, vectors are denoted by boldface symbols.

Subscripts "i" and "f" denotes ``initial'' and ``final'', respectively,
and are used in connection with the photon state before and after
an interaction with the component in question.
%This is of particular importance in sample components, where the
%wave vector change is denoted the {\em scattering vector}
%\begin{equation}\label{eq:q-transfert}
%\mathbf{ q} \equiv \mathbf{ k}_\mathrm{i} - \mathbf{ k}_\mathrm{f} .
%\end{equation}
%In analogy, the {\em energy transfer} is given by
%\begin{equation}\label{eq:w-transfert}
%\hbar \omega \equiv E_\mathrm{i}-E_\mathrm{f} =
%\frac{\hbar^2}{2 m_\mathrm{n}} \left( k_\mathrm{i}^2 - k_\mathrm{f}^2 \right).
%\end{equation}


\section{Component coordinate system}
All mentioning of component geometry refer to
the local coordinate system of the individual component.
The axis convention is so that the $z$ axis is along
the photon propagation axis, the $y$ axis is vertical up,
and the $x$ axis points left when looking along the $z$-axis,
completing a right-handed coordinate system.
Most components 'position' (as specified in the instrument description
with the \verb+AT+ keyword) corresponds to their volume centre. The mirrors
are an important counterexmaple. In this case the 'position' is the
centre of the mirror surface

Components are not necessarily designed to overlap.
This may lead to loss of rays.
Warnings will be issued during simulation if sections of the instrument
are not reached by any xrays, or if a significant number of xrays are removed.
This is usually the sign of either overlapping components
or low intensity.\index{Removed xray events}

\section{About data files}\index{Data files}\index{Library!read\_table-lib (Read\_Table)}
Some components require external data files,
e.g. lattice crystallographic definitions for Laue and powder pattern diffraction,
absorption and reflectivity files, etc.

Such files distributed with \MCX\ are located in the
\verb+data+ sub-directory of the \verb+MCXTRACE+ library.
Components that make use of the \MCX\ file system,
including the \verb+read-table+ library (see section \ref{s:read-table})
may access all \MCX\ data files without making local copies.
Of course, you are welcome to define your own data files,
and eventually contribute to \MCX\ if you find them useful.

File extensions are not interpreted by \MCX but help in identifying relevant files per
application. \Cref{t:comp-data} lists the current default file extensions.
\begin{table}
  \begin{center}
    {\let\my=\\
    \begin{tabular}{|p{0.28\textwidth}|p{0.64\textwidth}|}
      \hline
       \textbf{MCXTRACE/data} & Description \\
       \hline
 *.lau & Laue pattern file, as issued from Crystallographica.
       For use with Single\_crystal and PowderN.
       Data: [ h   k   l Mult. d-space 2Theta   F-squared ] \\
 *.laz & Powder pattern file, as obtained from Lazy/ICSD.
       For use with PowderN.\\
 *.txt & General text file, containing ascii data. Currently used for elemental data extracted from NIST\cite{NIST-ffast}.\\
% *.trm & transmission file, typically for monochromator crystals and filters.
%       Data: [ k (Angs-1) , Transmission (0-1) ] \\
% *.rfl & reflectivity file, typically for mirrors and monochromator crystals.
%       Data: [ k (Angs-1) , Reflectivity (0-1) ] \\
% *.sqw & $S(q,\omega)$ files for Isotropic\_Sqw component.
%       Data: [q] [$\omega$] [$S(q,\omega)$]\\
      \hline
    \end{tabular}
    \caption{Data files of the \MCX\ library.}
    \label{t:comp-data}
    \index{Library!Components!data}
    }
  \end{center}
\end{table}


%We list powder and liquid data files from the \MCX library in
%Tables \ref{t:powders-data} and \ref{t:liquids-data}. 
%These files contain an
%extensive header describing physical properties with references, and are
%specially suited for the PowderN (see \ref{powder}) and Isotropic\_Sqw
%components (see \ref{s:isotropic-sqw}).
%
%\begin{table}
%  \begin{center}
%    {\let\my=\\
%    \begin{tabular}{|p{0.24\textwidth}|p{0.7\textwidth}|}
%      \hline
%       \textbf{MCSTAS/data} & Description \\
%       \hline
% *.lau & Laue pattern file, as issued from Crystallographica.
%       For use with Single\_crystal, PowderN, and Isotropic\_Sqw.
%       Data: [ h   k   l Mult. d-space 2Theta   F-squared ] \\
% *.laz & Powder pattern file, as obtained from Lazy/ICSD.
%       For use with PowderN, Isotropic\_Sqw and possibly Single\_crystal.\\
% *.trm & transmission file, typically for monochromator crystals and filters.
%       Data: [ k (Angs-1) , Transmission (0-1) ] \\
% *.rfl & reflectivity file, typically for mirrors and monochromator crystals.
%       Data: [ k (Angs-1) , Reflectivity (0-1) ] \\
% *.sqw & $S(q,\omega)$ files for Isotropic\_Sqw component.
%       Data: [q] [$\omega$] [$S(q,\omega)$]\\
%      \hline
%    \end{tabular}
%    \caption{Data files of the \MCX\ library.}
%    \label{t:comp-data}
%    \index{Library!Components!data}
%    }
%  \end{center}
%\end{table}
%
%\begin{table}
%  \begin{center}
%    {\let\my=\\
%    \begin{small}
%    \begin{tabular}{|l|rrr|rr|p{0.2\textwidth}|}
%
%      \hline
%      \textbf{ MCSTAS/data} & $\sigma_{coh}$&$\sigma_{inc}$&$\sigma_{abs}$&$T_m$       & $c$    & Note \\
%          File name     & [barns]     & [barns]    & [barns]    & [K]        & [m/s] & \\
%      \hline
%Ag.laz             & 4.407     & 0.58     &{\bfseries 63.3}      &1234.9    &2600&\\
%Al2O3\_sapphire.laz & 15.683    & 0.0188   &0.4625    &2273      &   &\\
%Al.laz             & 1.495     & 0.0082   &0.231     &933.5     &5100& .lau\\
%Au.laz             & 7.32      & 0.43     &{\bfseries 98.65}     &1337.4    &{\bfseries 1740}&\\
%B4C.laz            & 19.71     & 6.801    &{\bfseries 3068}      &2718      &     &\\
%Ba.laz             & 3.23      & 0.15     &29.0      &1000      &{\bfseries 1620}&\\
%Be.laz             & 7.63      & 0.0018   &0.0076    &1560      &13000&\\
%BeO.laz            & 11.85     & 0.003    &0.008     &2650      &   & .lau\\
%Bi.laz             & 9.148     & 0.0084   &0.0338    &544.5     &{\bfseries 1790}&\\
%C60.lau            & 5.551     & 0.001    &0.0035    &          &   &\\
%C\_diamond.laz      & 5.551     & 0.001    &0.0035    &4400      &18350 & .lau\\
%C\_graphite.laz     & 5.551     & 0.001    &0.0035    &3800      &18350 & .lau\\
%Cd.laz             & 3.04      & 3.46     &{\bfseries 2520}      &594.2     &2310&\\
%Cr.laz             & 1.660     & 1.83     &3.05      &2180      &5940&\\
%Cs.laz             & 3.69      & 0.21     &29.0      &301.6     &{\bfseries 1090}  & $c$ in liquid\\
%Cu.laz             & 7.485     & 0.55     &3.78      &1357.8    &3570&\\
%Fe.laz             & 11.22     & 0.4      &2.56      &1811      &4910&\\
%Ga.laz             & 6.675     & 0.16     &2.75      &302.91    &2740&\\
%Gd.laz             & 29.3      & 151      &{\bfseries 49700}     &1585      &2680&\\
%Ge.laz             & 8.42      & 0.18     &2.2       &1211.4    &5400  & \\
%H2O\_ice\_1h.laz     & 7.75      & 160.52   &0.6652    &273       &     &\\
%Hg.laz             & 20.24     & 6.6      &{\bfseries 372.3}     &234.32    &{\bfseries 1407}&\\
%I2.laz             & 7.0       & 0.62     &12.3      &386.85    &   &\\
%In.laz             & 2.08      & 0.54     &{\bfseries 193.8}     &429.75    &{\bfseries 1215}&\\
%K.laz              & .69       & 0.27     &2.1       &336.53    &{\bfseries 2000}&\\
%LiF.laz            & 4.46      & 0.921    &{\bfseries 70.51}     &1140      &   &\\
%Li.laz             & 0.454     & 0.92     &{\bfseries 70.5}      &453.69    &6000&\\
%Nb.laz             & 8.57      & 0.0024   &1.15      &2750      &3480&\\
%Ni.laz             & 13.3      & 5.2      &4.49      &1728      &4970&\\
%Pb.laz             & 11.115    & 0.003    &0.171     &600.61    &{\bfseries 1260}&\\
%Pd.laz             & 4.39      & 0.093    &6.9       &1828.05   &3070&\\
%Pt.laz             & 11.58     & 0.13     &10.3      &2041.4    &2680&\\
%Rb.laz             & 6.32      & 0.5      &0.38      &312.46    &{\bfseries 1300}  & \\
%Se\_alpha.laz       & 7.98      & 0.32     &11.7      &494       &3350&\\
%Se\_beta.laz        & 7.98      & 0.32     &11.7      &494       &3350&\\
%Si.laz             & 2.163     & 0.004    &0.171     &1687      &2200&\\
%SiO2\_quartza.laz   & 10.625    & 0.0056   &0.1714    &846       &      & .lau\\
%SiO2\_quartzb.laz   & 10.625    & 0.0056   &0.1714    &1140      &      & .lau\\
%Sn\_alpha.laz       & 4.871     & 0.022    &0.626     &505.08    &     &\\
%Sn\_beta.laz        & 4.871     & 0.022    &0.626     &505.08    &2500&\\
%Ti.laz             & 1.485     & 2.87     &6.09      &1941      &4140&\\
%Tl.laz             & 9.678     & 0.21     &3.43      &577       &{\bfseries 818}&\\
%V.laz              & .0184     & 4.935    &5.08      &2183      &4560&\\
%Zn.laz             & 4.054     & 0.077    &1.11      &692.68    &3700&\\
%Zr.laz             & 6.44      & 0.02     &0.185     &2128      &3800&\\
%      \hline
%    \end{tabular}\end{small}
%    \caption{Powders of the \MCX\ library \cite{icsd_ill,ILLblue}. Low $c$ and high $\sigma_{abs}$ materials are highlighted. Files are given in LAZY format, but may exist as well in Crystallographica \textit{.lau} format as well.}
%    \label{t:powders-data}
%    \index{Library!Components!data}
%    }
%  \end{center}
%\end{table}
%
%\begin{table}
%  \begin{center}
%    {\let\my=\\
%    \begin{small}
%    \begin{tabular}{|l|rrr|rr|p{0.2\textwidth}|}
%
%      \hline
%      {\bfseries MCSTAS/data} & $\sigma_{coh}$&$\sigma_{inc}$&$\sigma_{abs}$&$T_m$       & $c$    & Note \\
%          File name     & [barns]     & [barns]    & [barns]    & [K]        & [m/s] & \\
%      \hline
%Cs\_liq\_tot.sqw                      & 3.69      & 0.21     &29.0      &301.6     &{\bfseries 1090}  & Measured \\
%Ge\_liq\_coh.sqw and Ge\_liq\_inc.sqw & 8.42      & 0.18     &2.2       &1211.4    &5400  & Ab-initio MD \\
%He4\_liq\_coh.sqw                     & 1.34      & 0        &0.00747   &0         &{\bfseries 240}   & Measured\\
%Ne\_liq\_tot.sqw                      & 2.62      & 0.008    &0.039     &24.56     &{\bfseries 591}   & Measured\\
%Rb\_liq\_coh.sqw and Rb\_liq\_inc.sqw & 6.32      & 0.5      &0.38      &312.46    &{\bfseries 1300}  & Classical MD \\
%Rb\_liq\_tot.sqw                      & 6.32      & 0.5      &0.38      &312.46    &{\bfseries 1300}  & Measured \\
%      \hline
%    \end{tabular}\end{small}
%    \caption{Liquids of the \MCX\ library \cite{icsd_ill,ILLblue}. Low $c$ and high $\sigma_{abs}$ materials are highlighted.}
%    \label{t:liquids-data}
%    \index{Library!Components!data}
%    }
%  \end{center}
%\end{table}

\MCX\ itself generates both simulation and monitor data files, the structure of which is explained in the User Manual (see end of chapter 'Running \MCX').

\section{Component source code}
Source code for all components may be found in the \verb+MCXTRACE+ library
subdirectory of the McXtrace installation;
the default is \verb+/usr/local/lib/mcxtrace/+
on Unix-like systems and \verb+C:\mcxtrace\lib+ on Windows systems, but it may be
changed using the \verb+MCXTRACE+ environment variable.
\index{Environment variable!MCXTRACE}

In case users only require to add new features, preserving the existing features of a component, 
using the \verb+EXTEND+ keyword\index{Keyword!EXTEND} in the instrument description file is recommended. For larger modification of a component, it is advised to make a copy
of the component file into the working directory.
A component file in the local directory will in \MCX takes precedence over
a library component of the same name.

\section{Documentation}
As a complement to this Component Manual, we encourage users to use
the \verb+mxdoc+ front-end which enables to display both the
catalog of the \MCX\ library, e.g using: \index{Tools!mcdoc}
\begin{quote}
  \verb|mxdoc|
\end{quote}
as well as the documentation of specific components, e.g with:
\begin{quote}
  \verb|mxdoc --text| \textit{name} \\
  \verb|mxdoc| \textit{file.comp}
\end{quote}
The first line will search for all components matching the \textit{name},
and display their help section as text. For instance, \verb+mxdoc .laz+ will list all available Lazy data files, whereas \verb+mxdoc --text Monitor+ will list most Monitors.
The second example will display the help corresponding to
the \textit{file.comp} component, using your
BROWSER\index{Environment variable!BROWSER} setting, or as text if unset.
The \verb+--help+ option will display the command help, as usual.

An overview of the component library is also given at the \MCX home page \cite{mcxtrace_webpage} and in the User Manual \cite{mcxtracemanual}.

\section{Disclaimer, bugs}\index{Bugs}

We would like to emphasize that the usage of both the \MCX software, as well as
its components are the responsability of the users. Indeed, obtaining accurate
and reliable results requires a substantial work when writing instrument
descriptions. This also means that users should read carefully both the
documentation from the manuals \cite{mcxtracemanual} and from the component
itself (using \verb+mcdoc+ \textit{comp}) before reporting errors. Most
anomalous results often originate from a wrong usage of some part of the
package.

Anyway, if you find that either the documentation is not clear, or the behavior
of the simulation is undoubtedly anomalous, you should report this to us at
\hbox{\texttt{mcxtrace-users@mcxtrace.org}} and/or refer to our special bug/request reporting service
\cite{mczilla_webpage}.
