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

\chapter{Libraries and conversion constants}
\label{c:kernelcalls}
\index{Library|textbf}
\index{Library!Shared|see{Library/Components/share}}
\index{Library!mcxtrace-r|see{Library/Run-time}}

The \MCX\ Library contains a number of built-in functions
and conversion constants which are useful when constructing
components. These are stored in the \verb+share+ directory of
the \verb+MCXTRACE+ library. \index{Library!Components!share}
\index{Environment variable!MCXTRACE}

Within these functions, the 'Run-time' part is available for all
component/instrument descriptions. The other parts
% (see table~\ref{t:comp-share})
are dynamic, that is they are not
pre-loaded, but only imported once when a component requests it
using the \verb+%include+ \MCX keyword. For instance, within a
component C code block, (usually SHARE or DECLARE):
\index{Keyword!\%include}
\begin{lstlisting}
    %include "read_table-lib"
\end{lstlisting}
will include the 'read\_table-lib.h' file, and the 'read\_table-lib.c'
(unless the \verb+--no-runtime+ option is used with \verb+mcxtrace+).
Similarly,
\begin{lstlisting}
    %include "read_table-lib.h"
\end{lstlisting}
will \emph{only} include the 'read\_table-lib.h'.
The library embedding is done only once for all components (like the
 SHARE section). \index{Keyword!SHARE} For an example
of implementation, see {\bfseries Res\_monitor}.

In this Appendix, we present a short list of both each of the library contents
and the run-time features.

\section{Run-time calls and functions (\texttt{mcxtrace-r})}
\label{s:calls:run-time}
\index{Library!Run-time|textbf}
\index{Library!mcxtrace-r|see{Library/Run-time}}
Here we list a number of preprogrammed macros and functions
which may ease the task of writing component and instrument definitions.
By convention macros are in upper case whereas functions are in lower case.

\subsection{Photon propagation}
\index{Library!Run-time!SCATTER}
\index{Library!Run-time!ABSORB}
\index{Library!Run-time!PROP\_Z0}
\index{Library!run-time!PROP\_X0}
\index{Library!run-time!PROP\_Y0}
\index{Library!Run-time!PROP\_DL}
\index{Library!Run-time!ALLOW\_BACKPROP}
Propagation routines perform all necessary operations to transport x-rays
from one point to an other. Except when using the special
\verb+ALLOW_BACKPROP;+ call prior to executing any \verb+PROP_*+ propagation,
the x-rays which have negative propagation lengths are removed automatically.
\begin{itemize}
\item {\bfseries ABSORB}. This macro issues an order to the overall
  \MCX\ simulator to interrupt the simulation of the current x-ray
  history and to start a new one.
\item {\bfseries PROP\_Z0}. Propagates the x-ray to the $z=0$ plane,
  by adjusting $(x,y,z)$, $\phi$, and $t$ accordingly from knowledge of the
  x-ray wavevector $(kx,ky,kz)$.
  If the propagation length is negative, the x-ray is absorbed, except if a \verb+ALLOW_BACKPROP;+ preceeds it.

  For components that are centered along the $z$-axis,
  use the \verb+_intersect+ functions to determine intersection time(s),
  and then a \verb+PROP_DL+ call.
\item {\bfseries PROP\_X0, PROP\_Y0}. These macros are analogous to \verb+PROP_Z0+ except they propagate to the $x=0$ and $y=0$ planes respectively.

\item {\bfseries PROP\_DL}$(dl)$. Propagates the x-ray by the length $dl$, adjusting $(x,y,z)$, $\phi$, $t$ accordingly,
  from knowledge of the x-ray wavevector.
\item {\bfseries ALLOW\_BACKPROP}. Indicates that the \emph{next} propagation routine
  will not remove the x-ray, even if negative propagation lengths
  are found. Subsequent propagations are not affected.\index{Removed x-ray events}
\item {\bfseries SCATTER}. This macro is used to denote a scattering event
  inside a component.
%, see section~\ref{s:comp-trace}.
  It should be used
  to indicate that a component has interacted with the x-ray
  (e.g. scattered or detected).
  This does not affect the x-ray state (see, however, {\bfseries Beamstop}),
  and it is mainly used by the \verb+MCDISPLAY+ section and the \verb+GROUP+ modifier.
%(see~\ref{s:trace} and \ref{s:comp-mcdisplay}).
  See also the SCATTERED variable (below).
  \index{Keyword!GROUP} \index{Keyword!MCDISPLAY} \index{Keyword!EXTEND}
\end{itemize}

\subsection{Coordinate and component variable retrieval}
\index{Library!Run-time!MC\_GETPAR}
\index{Library!Run-time!NAME\_CURRENT\_COMP}
\index{Library!Run-time!POS\_A\_CURRENT\_COMP}
\index{Library!Run-time!ROT\_A\_CURRENT\_COMP}
\index{Library!Run-time!POS\_A\_COMP}
\index{Library!Run-time!ROT\_A\_COMP}
\index{Library!Run-time!STORE\_XRAY}
\index{Library!Run-time!RESTORE\_XRAY}
\index{Library!Run-time!SCATTERED}
\begin{itemize}
\item {\bfseries MC\_GETPAR}$(comp, outpar)$. This may be used in e.g. the FINALLY section of an
  instrument definition to reference the parameters of a
  component.
% See page~\pageref{mcgetpar} for details.
\item {\bfseries NAME\_CURRENT\_COMP} gives the name of the current component as a string.
\item {\bfseries POS\_A\_CURRENT\_COMP} gives the absolute position of the
  current component. A component of the vector is referred to as
  POS\_A\_CURRENT\_COMP.$i$ where $i$ is $x$, $y$ or $z$.
\item {\bfseries ROT\_A\_CURRENT\_COMP} and
  {\bfseries ROT\_R\_CURRENT\_COMP} give the orientation
  of the current component as rotation matrices
  (absolute orientation and the orientation relative to
  the previous component, respectively). A
  component of a rotation matrix is referred to as
  ROT\_A\_CURRENT\_COMP$[m][n]$, where $m$ and
  $n$ are 0, 1, or 2 standing for $x,y$ and $z$ coordinates respectively.
\item {\bfseries POS\_A\_COMP}$(comp)$ gives the absolute position
  of the component with the name {\em comp}. Note that
  {\em comp} is not given as a string. A component of the
  vector is referred to as POS\_A\_COMP$(comp).i$
  where $i$ is $x$, $y$ or $z$.
\item {\bfseries ROT\_A\_COMP}$(comp)$ and
  {\bfseries ROT\_R\_COMP}$(comp)$ give the orientation of the
  component {\em comp} as rotation matrices (absolute
  orientation and the orientation relative to its
  previous component, respectively). Note that {\em comp}
  is not given as a string. A component of  a rotation
  matrice is referred to as
  ROT\_A\_COMP$(comp)[m][n]$, where $m$ and $n$ are
  0, 1, or 2.
\item {\bfseries INDEX\_CURRENT\_COMP} is the number (index) of the
       current component  (starting from 1).
\item {\bfseries POS\_A\_COMP\_INDEX}$(index)$ is the absolute position of
  component $index$. \\
  POS\_A\_COMP\_INDEX (INDEX\_CURRENT\_COMP) is the same as \\
  POS\_A\_CURRENT\_COMP. You may use \\
  POS\_A\_COMP\_INDEX  (INDEX\_CURRENT\_COMP+1) \\
  to make, for instance, your
  component access the position of the next component (this is usefull for
  automatic targeting).  A component of the vector is referred to as
  POS\_A\_COMP\_INDEX$(index).i$ where $i$ is $x$, $y$ or $z$.
\item {\bfseries POS\_R\_COMP\_INDEX} works the same as above,
  but with relative coordinates.
\item {\bfseries STORE\_XRAY}$(index, x, y, z, kx, ky, kz, phi,t, Ex, Ey,
Ez, p)$ stores the current x-ray state in the trace-history table,
in local coordinate system. $index$ is usually INDEX\_CURRENT\_COMP.
This is automatically done when entering each component of an
instrument.
\item {\bfseries RESTORE\_XRAY}$(index, x, y, z, kx, ky, kz, phi,t, Ex, Ey,
Ez, p)$ restores the x-ray state to the one at the input of the
component $index$. To ignore a component effect, use
RESTORE\_XRAY (INDEX\_CURRENT\_COMP, \\
$x, y, z, kx, ky, kz, phi,
Ex, Ey, Ez, p$) at the end of its TRACE section, or in its EXTEND
section. These x-ray states are in the local component coordinate
systems.
\item {\bfseries SCATTERED} is a variable set to 0 when entering
  a component, which is incremented each time a SCATTER event occurs.
  This may be used in the \verb+EXTEND+ sections to determine whether
  the component interacted with the current x-ray.
\item {\bfseries extend\_list}($n$, \&\textit{arr}, \&\textit{len},
  \textit{elemsize}). Given an array \textit{arr} with \textit{len}
  elements each of size \textit{elemsize}, make sure that the array is
  big enough to hold at least $n$ elements, by extending \textit{arr}
  and \textit{len} if necessary. Typically used when reading a list of
  numbers from a data file when the length of the file is not known in advance.
\item {\bfseries mcset\_ncount}$(n)$. Sets the number of x-ray histories to simulate to $n$.
\item {\bfseries mcget\_ncount}(). Returns the number of x-ray histories to simulate (usually set by option \verb+-n+).
\item {\bfseries mcget\_run\_num}(). Returns the number of x-ray histories that have been simulated until now.
\end{itemize}

\subsection{Coordinate transformations}
\begin{itemize}
\item {\bfseries coords\_set}$(x,y,z)$ returns a Coord structure (like POS\_A\_CURRENT\_COMP) with $x$, $y$ and $z$ members.
\item {\bfseries  coords\_get}$(P,$ \&$x$, \&$y$, \&$z)$ copies the $x$, $y$ and
$z$ members of the Coord structure $P$ into $x,y,z$ variables.
\item {\bfseries coords\_add}$(a,b)$, {\bfseries coords\_sub}$(a,b)$, {\bfseries
coords\_neg}$(a)$ enable to  operate on coordinates, and return the
resulting Coord structure.
\item {\bfseries rot\_set\_rotation}(\textit{Rotation t}, $\phi_x, \phi_y, \phi_z$)
  Get transformation matrix for rotation
  first $\phi_x$ around x axis, then $\phi_y$ around y,
  and last $\phi_z$ around z. $t$ should be a 'Rotation' ([3][3] 'double' matrix).
\item {\bfseries rot\_mul}\textit{(Rotation t1, Rotation t2, Rotation t3)} performs $t3 = t1 . t2$.
\item {\bfseries rot\_copy}\textit{(Rotation dest, Rotation src)} performs $dest = src$ for Rotation arrays.
\item {\bfseries rot\_transpose}\textit{(Rotation src, Rotation dest)} performs $dest = src^t$.
\item {\bfseries rot\_apply}\textit{(Rotation t, Coords a)} returns a Coord structure which is $t.a$
\end{itemize}

\subsection{Mathematical routines}
\begin{itemize}
\item {\bfseries NORM}$(x,y,z)$. Normalizes the vector $(x,y,z)$ to have
  length 1.
\item {\bfseries scalar\_prod}$(a_x,a_y,a_z, b_x,b_y,b_z)$. Returns the scalar
  product of the two vectors $(a_x,a_y,a_z)$ and $(b_x,b_y,b_z)$.
\item {\bfseries vec\_prod}(\&$a_x$,\&$a_y$,\&$a_z$, $b_x$,$b_y$,$b_z$, $c_x$,$c_y$,$c_z$). Sets
  $(a_x,a_y,a_z)$ equal to the vector product $(b_x,b_y,b_z) \times (c_x,c_y,c_z)$.
\item {\bfseries rotate}(\&$x$,\&$y$,\&$z$,$v_x$,$v_y$,$v_z$,$\varphi$,$a_x$,$a_y$,$a_z$). Set
  $(x,y,z)$ to the result of rotating the vector $(v_x,v_y,v_z)$
  the angle $\varphi$ (in radians) around the vector $(a_x,a_y,a_z)$.
\item {\bfseries normal\_vec}($n_x$, $n_y$, $n_z$, $x$, $y$, $z$).
  Computes a unit vector $(n_x, n_y, n_z)$ normal to the vector
  $(x,y,z)$.$^*$
\item {\bfseries solve\_2nd\_order}(*$t_0$,*$t_1$, $A$,  $B$,  $C$).
  Solves the 2$^{nd}$ order equation $At^2 + Bt + C = 0$ and puts the solutions in
  *$t_0$ and *$t_1$. The smallest positive solution into pointer *$t_0$. If $t_1$=\texttt{NULL}
  it is ignored and the second solution is discarded.
\end{itemize}

\subsection{Output from detectors}
Details about using these functions are given in the \MCX\ User Manual.
\begin{itemize}
\item {\bfseries DETECTOR\_OUT\_0D}$(...)$. Used to output the results from a
  single detector. The name of the detector is output together
  with the simulated intensity and estimated statistical error. The
  output is produced in a format that can be read by \MCX\ front-end
  programs.
%See section~\ref{s:comp-finally} ??? for details.
\item {\bfseries DETECTOR\_OUT\_1D}$(...)$. Used to output the results from a
  one-dimensional detector. Integrated intensities error etc. is also
  reported as for DETECTOR\_OUT\_0D.
%See section~\ref{s:comp-finally} for details.
\item {\bfseries DETECTOR\_OUT\_2D}$(\dots...)$. Used to output the results from a
  two-dimentional detector. Integrated intensities error etc. is also
  reported as for DETECTOR\_OUT\_0D.
%See section~\ref{s:comp-finally} for details.
%\item {\bfseries DETECTOR\_OUT\_3D}$(...)$. Used to output
%  the results from a three-dimentional detector. Arguments are the same as
%  in DETECTOR\_OUT\_2D, but with an additional $z$ axis.
%  Resulting data files are treated as 2D data, but the 3rd dimension is
%  specified in the $type$ field. Integrated intensities error etc. is also
%  reported as for DETECTOR\_OUT\_0D.
\item {\bfseries mcinfo\_simulation}\textit{(FILE *f, mcformat,
  char *pre, char *name)} is used to append the simulation parameters into file $f$
  (see for instance {\bfseries Res\_monitor}).
  Internal variable $mcformat$ should be used as specified.
  Please contact the authors for further information.
\end{itemize}

\subsection{Ray-geometry intersections}
\begin{itemize}
\item {\bfseries inside\_rectangle}($x$, $y$, $xw$, $yh$).
  Return 1 if $-xw/2 \leq x \leq xw/2$ AND $-yh/2 \leq y \leq yh/2$.
  Else return 0.
\item {\bfseries box\_intersect}(\&$l_1$, \&$l_2$, $x$, $y$, $z$, $k_x$, $k_y$, $k_z$,
  $d_x$, $d_y$, $d_z$). Calculates the (0, 1, or 2) intersections between
  the x-ray path and a box of dimensions $d_x$, $d_y$, and $d_z$,
  centered at the origin for a x-ray with the parameters
  $(x,y,z,k_x,k_y,k_z)$. The intersection lengths are returned
  in the variables $l_1$ and $l_2$, with $l_1 < l_2$. In the case
  of less than two intersections, $t_1$ (and possibly $t_2$) are set to
  zero. The function returns true if the x-ray intersects the box,
  false otherwise.
\item {\bfseries cylinder\_intersect}(\&$l_1$, \&$l_2$, $x$, $y$, $z$, $k_x$, $k_y$, $k_z$,
  $r$, $h$).  Similar to {\bfseries box\_intersect}, but using a cylinder of height $h$ and radius $r$,
  centered at the origin.
\item {\bfseries sphere\_intersect}(\&$l_1$, \&$l_2$, $x$, $y$, $z$, $k_x$, $k_y$, $k_z$,
  $r$). Similar to {\bfseries box\_intersect}, but using a sphere
  of radius $r$.
\item {\bfseries ellipsoid\_intersect}(\&$l_1$, \&$l_2$, $x$, $y$, $z$, $k_x$, $k_y$, $k_z$,
  $a$,$b$,$c$,$Q$, ). Similar to {\bfseries box\_intersect}, but using an ellipsoid with half-axis $a$,$b$,$c$ oriented by the rotation matrix $Q$.
  If $Q=I$, $a$ is along the $x$-axis, $b $ along $y$ and $c$ along $z$
\end{itemize}

\subsection{Random numbers}
By default  \MCX uses the included Mersenne Twister\cite{matsumoto1998mersenne} algorithm for generating pseudo random numbers.
\begin{itemize}
\item {\bfseries rand01}(). Returns a random number distributed uniformly between 0 and 1.
\item {\bfseries randnorm}(). Returns a random number from a normal
  distribution centered around 0 and with $\sigma=1$. The algorithm used to
  sample the normal distribution is explained in Ref.~\cite[ch.7]{num_rep}.
\item {\bfseries randpm1}(). Returns a random number distributed uniformly between -1 and 1.
\item {\bfseries randtriangle}(). Returns a random number from a triangular distribution between -1 and 1.
\item {\bfseries randvec\_target\_circle}(\&$v_x$, \&$v_y$, \&$v_z$, \&$d\Omega$,
  aim$_x$, aim$_y$, aim$_z$, $r_f$). Generates a random vector $(v_x, v_y,
  v_z)$, of the same length as (aim$_x$, aim$_y$, aim$_z$), which is
  targeted at a \emph{disk} centered at (aim$_x$, aim$_y$, aim$_z$) with
  radius $r_f$ (in meters), and perpendicular to the \emph{aim} vector.. All directions
  that intersect the circle are chosen with equal probability. The solid
  angle of the circle as seen from the position of the x-ray is returned
  in $d\Omega$. This routine was previously called {\bfseries randvec\_target\_sphere}
  (which still works).
\item {\bfseries randvec\_target\_rect\_angular}(\&$v_x$, \&$v_y$, \&$v_z$,
  \&$d\Omega$, aim$_x$, aim$_y$, aim$_z$,$h, w, Rot$) does the same as
  randvec\_target\_circle but targetting at a rectangle with angular dimensions
  $h$ and $w$ (in {\bfseries radians}, not in degrees as other angles). The
  rotation matrix $Rot$ is the coordinate system orientation in the absolute
  frame, usually ROT\_A\_CURRENT\_COMP.
\item {\bfseries randvec\_target\_rect}(\&$v_x$, \&$v_y$, \&$v_z$,
  \&$d\Omega$, aim$_x$, aim$_y$, aim$_z$,$height, width, Rot$) is the same as
  randvec\_target\_rect\_angular but $height$ and $width$ dimensions are given
  in meters. This function is useful to e.g. target at a guide entry window
  or analyzer blade.
\end{itemize}

\section{Reading a data file into a vector/matrix (Table input, \texttt{read\_table-lib})}
\label{s:read-table}
\index{Library!read\_table-lib (Read\_Table)|textbf}
  The \verb+read_table-lib+ library provides functionalities for reading text
  (and binary) data files. To use this library,
  add a \verb+%include "read_table-lib"+ in your component definition
  DECLARE or SHARE section. Tables are structures of type \verb+t_Table+
  (see \verb+read_table-lib.h+ file for details):
  \begin{lstlisting}[language=C]
    /* t_Table structure (most important members) */
    double *data;     /* Use Table_Index(Table, i j) to extract [i,j] element */
    long    rows;     /* number of rows */
    long    columns;  /* number of columns */
    char   *header;   /* the header with comments */
    char   *filename; /* file name or title */
    double  min_x;    /* minimum value of 1st column/vector */
    double  max_x;    /* maximum value of 1st column/vector */
\end{lstlisting}

Available functions to read \emph{a single} vector/matrix are:
\begin{itemize}
\item {\bfseries Table\_Init}(\&$Table$, $rows$, $columns$) returns an allocated
  Table structure. Use $rows=columns=0$ not to allocate memory and return an empty table.
  Calls to Table\_Init are \emph{optional}, since initialization is being
  performed by other functions already.
\item {\bfseries Table\_Read}(\&$Table$, $filename$, $block$)
  reads numerical block number
  $block$ (0 to catenate all) data from \emph{text} file $filename$ into $Table$,
  which is as well initialized in the process.
  The block number changes when the numerical data changes its size,
  or a comment is encoutered (lines starting
  by '\verb+# ; % /+'). If the data could not be read,
  then $Table.data$ is NULL and $Table.rows = 0$.
  You may then try to read it using Table\_Read\_Offset\_Binary.
  Return value is the number of elements read.
\item {\bfseries Table\_Read\_Offset}(\&$Table$, $filename$, $block$, \&\textit{offset}, $n_{rows}$)
  does the same as Table\_Read except that it starts at offset \textit{offset}
  (0 means begining of file) and reads $n_{rows}$ lines (0 for all).
  The \textit{offset} is returned as the final offset reached after
  reading the $n_{rows}$ lines.
\item {\bfseries Table\_Read\_Offset\_Binary}(\&$Table$, $filename$, $type$,
  $block$, \&\textit{offset}, $n_{rows}$, $n_{columns}$) does the same as
  Table\_Read\_Offset, but also specifies the $type$ of the file (may
  be "float" or "double"), the number $n_{rows}$ of rows to read, each
  of them having $n_{columns}$ elements. No text header should be present
  in the file.
\item {\bfseries Table\_Rebin}(\&$Table$) rebins all $Table$ rows with increasing, evenly spaced first column (index 0), e.g. before using Table\_Value. Linear interpolation is performed for all other columns. The number of bins for the rebinned table is determined from the smallest first column step.
\item {\bfseries Table\_Info}$(Table)$ print information about the table $Table$.
\item {\bfseries Table\_Index}($Table, m, n$) reads the $Table[m][n]$ element.
\item {\bfseries Table\_Value}($Table, x, n$) looks for the closest $x$
  value in the first column (index 0), and extracts in this row the
  $n$-th element (starting from 0). The first column is thus the 'x' axis for the data.
\item {\bfseries Table\_Free}(\&$Table$) free allocated memory blocks.
\item {\bfseries Table\_Value2d}($Table$, $X$, $Y$) Uses 2D linear interpolation on a Table, from (X,Y) coordinates and returns the corresponding value.
\end{itemize}

Available functions to read \emph{an array} of vectors/matrices in a \emph{text} file are:
\begin{itemize}
\item {\bfseries Table\_Read\_Array}($File$, \&$n$) read and split $file$
into as many blocks as necessary and return a \verb+t_Table+ array.
Each block contains a single vector/matrix. This only works for text files.
The number of blocks is put into $n$.
\item {\bfseries Table\_Free\_Array}(\&$Table$) free the $Table$ array.
\item {\bfseries Table\_Info\_Array}(\&$Table$) display information about all data blocks.
\end{itemize}

The format of text files is free. Lines starting by '\verb+# ; % /+' characters are considered to be comments, and stored in $Table.header$. Data blocks are vectors and matrices. Block numbers are counted starting from 1, and changing when a comment is found, or the column number changes. For instance, the file 'MCXTRACE/data/Rh.txt' (Material data for Rhodium) looks like:
\begin{lstlisting}
#Rh (Z  45) 
#Atomic weight: A[r]  102.9055 
#Nominal density: rho 1.2390E+01
#    sigma[a](barns/atom) = [mu/rho](cm\^2 g\^-1)  .  1.70879E+02
#    E(eV) [mu/rho](cm\^2 g\^-1) = f[2](e atom\^-1)  .  4.08922E+05
#    14 edges. Edge energies (keV):
#
#
#      K      2.32199E+01  L I    3.41190E+00  L II   3.14610E+00  L III  3.00380E+00
#      M I    6.27100E-01  M II   5.21000E-01  M III  4.96200E-01  M IV   3.11700E-01
#      M V    3.07000E-01  N I    8.10000E-02  N II   4.79000E-02  N III  4.79000E-02
#      N IV   2.50000E-03  N V    2.50000E-03
#
#    Relativistic correction estimate f[rel] (H82,3/5CL) = -4.0814E-01,
#    -2.5440E-01 e atom\^-1
#    Nuclear Thomson correction f[NT] = -1.0795E-02 e atom\^-1
#
#-------------------------------------------------------------------------------
#Form Factors, Attenuation and Scattering Cross-sections
#Z=45, E = 0.001 - 433 keV
#
#      E            f[1]          f[2]        [mu/rho]      [sigma/rho]      [mu/rho]      [mu/rho][K]      lambda
#                                      Photoelectric Coh+inc      Total
#     keV        e atom\^-1      e atom\^-1   cm\^2 g\^-1       cm\^2 g\^-1      cm\^2 g\^-1   cm\^2 g\^-1     nm
1.069000E-02  1.89417E+00  4.8055E+00  1.8382E+05  1.1514E-04  1.8382E+05  0.000E+00  1.160E+02
1.142761E-02  2.09662E+00  5.1028E+00  1.8260E+05  1.5865E-04  1.8260E+05  0.000E+00  1.085E+02
1.221612E-02  2.32705E+00  5.4019E+00  1.8082E+05  2.1741E-04  1.8082E+05  0.000E+00  1.015E+02
1.305903E-02  2.58575E+00  5.6998E+00  1.7848E+05  2.9628E-04  1.7848E+05  0.000E+00  9.494E+01
1.396010E-02  2.87263E+00  5.9931E+00  1.7555E+05  4.0158E-04  1.7555E+05  0.000E+00  8.881E+01
1.492335E-02  3.18714E+00  6.2786E+00  1.7204E+05  5.4136E-04  1.7204E+05  0.000E+00  8.308E+01
1.595306E-02  3.52819E+00  6.5531E+00  1.6797E+05  7.2588E-04  1.6797E+05  0.000E+00  7.772E+01
1.705382E-02  3.89415E+00  6.8134E+00  1.6337E+05  9.6809E-04  1.6337E+05  0.000E+00  7.270E+01
  ...
\end{lstlisting}
Binary files should be of type "float" (i.e. REAL*32) and "double" (i.e. REAL*64),
and should \emph{not} contain text header lines. These files are platform
dependent (little or big endian).

The $filename$ is first searched into the current directory (and all user additional locations specified using the \verb+-I+ option, see the 'Running \MCX\ ' chapter in the User Manual), and if not found, in the \verb+data+ sub-directory of the \verb+MCXTRACE+ library location. \index{Library!Components!data}
\index{Environment variable!MCXTAS} This way, you do not need to have local copies of the \MCX\ Library Data files (see \cref{t:comp-data}).

A usage example for this library part may be:
\begin{lstlisting}[language=C]
  t_Table Table;       // declare a t_Table structure
  char file[]="Rh.txt";  // a file name
  double x,y;

  Table_Read(&Table, file, 1);  // initialize and read the first numerical block
  Table_Info(Table);            // display table informations
  ...
  x = Table_Index(Table, 2,5);  // read the 3rd row, 6th column element
                                // of the table. Indexes start at zero in C.
  y = Table_Value(Table, 1.45,1);  // look for value 1.45 in 1st column (x axis)
                                // and extract 2nd column value of that row
  Table_Free(&Table);           // free allocated memory for table
\end{lstlisting}
Additionally, if the block number (3rd) argument of  {\bfseries Table\_Read} is 0, all blocks will be catenated.
The {\bfseries Table\_Value} function assumes that the 'x' axis is the first column (index 0).
Other functions are used the same way with a few additional parameters, e.g. specifying an offset for reading files, or reading binary data.

This other example for text files shows how to read many data blocks:
\begin{lstlisting}[language=C]
  t_Table *Table;       // declare a t_Table structure array
  long     n;
  double y;

  Table = Table_Read_Array("file.dat", &n); // initialize and read the all numerical block
  n = Table_Info_Array(Table);     // display informations for all blocks (also returns n)

  y = Table_Index(Table[0], 2,5);  // read in 1st block the 3rd row, 6th column element
                                   // ONLY use Table[i] with i < n !
  Table_Free_Array(Table);         // free allocated memory for Table
\end{lstlisting}

You may look into, for instance, the source files for
\textbf{Lens\_parab} or \textbf{Filter}
for other implementation examples.

%\section{Monitor\_nD Library}
%\index{Library!monitor\_nd-lib}
%
%This library gathers a few functions used by a set of monitors e.g. Monitor\_nD, Res\_monitor, Virtual\_output, etc.
%It may monitor any kind of data, create the data files, and may display many geometries (for \verb+mcdisplay+).
%Refer to these components for implementation examples, and ask the authors for more details.
%
%\section{Adaptive importance sampling Library}
%\index{Library!adapt\_tree-lib}
%
%This library is currently only used by the components {\bfseries Source\_adapt}
%and {\bfseries Adapt\_check}. It performs adaptive importance sampling of x-rays for simulation efficiency optimization.
%Refer to these components for implementation examples, and ask the authors for more details.
%
%\section{Vitess import/export Library}
%\index{Library!vitess-lib}
%
%This library is used by the components
%{\bfseries Vitess\_input} and {\bfseries Vitess\_output},
%as well as the \verb+mcstas2vitess+ utility.
%% (see section~\ref{s:mcstas2vitess}).
%\index{Tools!mcstas2vitess}
%Refer to these components for implementation examples, and ask the authors for more details.

\section{Constants for unit conversion etc.}
The following predefined constants are useful for conversion
between units
\def\textvb{\textbf}
\begin{center}
\begin{tabular}{|l|c|p{0.29\textwidth}|p{0.252\textwidth}|}
\hline
Name & Value & Conversion from & Conversion to \\ \hline
\textvb{DEG2RAD} & $2 \pi / 360$ & Degrees & Radians \\
\textvb{RAD2DEG} & $360 / (2 \pi)$ & Radians & Degrees \\
\textvb{MIN2RAD} & $2 \pi / (360 \cdot 60)$
  & Minutes of arc & Radians \\
\textvb{RAD2MIN} & $(360\cdot 60) / (2 \pi)$
  & Radians & Minutes of arc \\
%\textvb{V2K} & $10^{10} \cdot m_\mathrm{N}/\hbar$
%  & Velocity (m/s) & {\bfseries k}-vector (\AA$^{-1}$) \\
%\textvb{K2V} & $10^{-10} \cdot \hbar / m_\mathrm{N}$
%  & {\bfseries k}-vector (\AA$^{-1}$) & Velocity (m/s) \\
%\textvb{VS2E} & $m_\mathrm{N} / (2 e)$
%  & Velocity squared (m$^2$ s$^{-2}$) & Neutron energy (meV) \\
%\textvb{SE2V} & $\sqrt{2 e/m_\mathrm{N}}$
%  & Square root of neutron energy (meV$^{1/2}$) & Velocity (m/s) \\
\textvb{FWHM2RMS} & $1/\sqrt{8\log(2)}$
  & Full width half maximum & Root mean square (standard deviation) \\
\textvb{RMS2FWHM} & $\sqrt{8\log(2)}$
  & Root mean square (standard deviation) & Full width half maximum \\
\textvb{MNEUTRON} & $1.67492 \cdot 10^{-27}$~kg
  & Neutron mass, $m_\mathrm{n}$ & \\
\textvb{HBAR} & $1.05459 \cdot 10^{-34}$~Js
  & Planck constant, $\hbar$ & \\
\textvb{PI} & $3.14159265...$
  & $\pi$ & \\
%\textvb{FLT\_MAX} & 3.40282347E+38F
%         & a big float value & \\
\textvb{CELE} & 1.602176487e-19 & Elementary charge (C) &\\
\textvb{M\_C} & 299792458 & Speed of light in vacuum (m/s) &\\
\textvb{NA} & 6.02214179e23 &  Avogadro's number (\#atoms/g$\cdot$mole)&\\
\textvb{RE} & 2.8179402894e-5 &  Thomson scattering length (AA)&\\
\textvb{E2K} & 0.506773091264796 & Wavenumber (1/AA) & Energy (keV)\\
\textvb{K2E} & 1.97326972808327  & Energy (keV) & Wavenumber (1/AA)\\


\hline
\end{tabular}
\end{center}
