% $Id: functionality.tex 1708 2008-01-29 04:42:52Z gmcmanus $

% Copyright (C) 2000-2007
%
% Code contributed by Greg Collecutt, Joseph Hope and the xmds-devel team
%
% This file is part of xmds.
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software 
% Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

\chapter{Functionality} 
\label{chap:functionality}

This chapter describes the full functionality of \xmds, but in
practice most of this detail is not required to integrate common types
of ODEs and PDEs. One of the particularly useful features of {\bf
xmds} is that both the high-level description of the problem and the
generated program can efficiently handle systems with widely varying
complexity.  Skip to the worked examples to see how very different
kinds of equations can be easily integrated.

\xmds is designed to integrate the following general PDE:
\begin{align}
\frac{\partial}{\partial x^0}\vect{a}(\vect{x}) & =
  \vect{\mathcal{N}}\left(\vect{x}, \vect{a}(\vect{x}),\vect{p}(\vect{x}),
  \vect{b}(\vect{x}),\;\vect{\xi}(\vect{x}\;, \int dx_j f(\vect{x}, \vect{a}(\vect{x}),\vect{p}(\vect{x}),
  \vect{b}(\vect{x}),\vect{\xi}(\vect{x}))\right),\\ 
  p^i(\vect{x}) & = \mathcal{F}^{-1}\left[\Sigma_j
  \mathcal{L}^{ij}\left(x^0,\vect{k_\bot}\right)
  \mathcal{F}\left[a^j(\vect{x})\right]\right],\\
  \frac{\partial}{\partial x^{c}}\vect{b}(\vect{x}) & =
  \vect{\mathcal{H}}\left(\vect{x}, \vect{a}(\vect{x}), 
  \vect{b}(\vect{x})\right),
  \label{eq:xmdsPdeEx}
\end{align}
where the vector $\vect{a}$ represents an m-component real or complex
valued field, though for some problems the field may only have one
component. The vector $\vect{x}$ is the real-valued space in which
$\vect{a}$ lies, which is the propagation dimension, $x^0$, plus the
transverse dimensions, $x^{i\neq 0}$, if any. The number of transverse
dimensions that the field may have is limited to 64 by \xmds, but
is more likely to be further limited by the complier and stack size
used when the output code is compiled. The vector $\vect{p}$ may have
any number of components (including zero), and may be derived through
the action of a matrix of linear operators, $\mathcal{L}^{ij}$, on the
main vector components. The action of these linear operators is
calculated with the main vector in Fourier space, hence, as explained
in \Sec{sec:transverseDerivatives}, transverse partial
derivatives reduce simply to multiplication by the transverse Fourier
space dimensions. The vector $\vect{b}$ is optional, and is an
n-component real or complex valued field which propagates along the
transverse dimension $x^c$. For stochastic problems $\vect{\xi}$ is a
vector of independent real Gaussian noises. The total derivatives for
vectors $\vect{a}$ and $\vect{b}$ are expressed as the general
functionals $\vect{\mathcal{N}}$ and $\vect{\mathcal{H}}$
respectively. Note that this form allows for nonlinear partial
derivatives that may have spatial dependence, for example
$\frac{1}{r}\left(\frac{\partial}{\partial r}\right)^2$.

\eqn{eq:xmdsPdeEx} is ``Schr\"{o}dinger-like'' in that it is
first order in the propagation dimension. As an example, if the field
was a vector field representing three dimensional fluid flow then
there would be three components to the field, which itself would exist
in four dimensional space, with perhaps the propagation dimension
being time and the three transverse dimensions being space.

\xmds can only handle problems whose only {\em non-local} terms are integrals over some or all of the transverse dimensions.  For local equations, the evolution of the field at any point in $\vect{x}$ is only
ever a function (including derivatives) of the field components at
that exact point in space---not anywhere else. This is clearly
restrictive of the range of physical problems that may be
modelled. However, many non-local problems are only so because of
variables that propagate in a dimension which is transverse to the
main propagation dimension, and thus are easily modelled by including
a secondary field which is propagated orthogonally along this
transverse dimension. This is the purpose of the $\vect{b}$ field which
is the secondary or ``cross'' field propagating in the transverse
dimension $x^c$, where $c \neq 0$.

In order to maximise the efficiency of the generated code while being
able to handle a broad range of problems, \xmds utilises a range of
algorithms. These were covered in \Sec{sec:numericalMethodsPde}.
Re-capping, the algorithms fell into two main categories:
\begin{enumerate}
\item {\bf Explicit picture.}  As detailed in \Sec{sec:exMethod} the
transverse derivatives of the field are calculated using the Fourier
Transform method of \Sec{sec:transverseDerivatives}. In all cases this
requires extra memory and computational expense, but it enables any
equations of the general from of \eqn{eq:xmdsPdeEx} to be solved.
\item {\bf Interaction picture.}  Here the field components are also
evolved in Fourier space using the interaction picture technique, as
detailed in \Sec{sec:ipMethod}.  The form of PDE that may be
solved using this technique is shown in \eqn{eq:xmdsPdeIp}.
\begin{align} 
  \frac{\partial}{\partial x^0}a^i(x^0,\vect{x}_\bot) & =
 \mathcal{F}^{-1}\left[\mathcal{L}^i(x^0,\vect{k}_{\bot})
 \mathcal{F}[a^i(\vect{x})] \right] +
 \mathcal{N}^i\left(\vect{x}, \vect{a}(\vect{x}), \vect{b}(\vect{x}), 
 \vect{\xi}(\vect{x})\right),\\ 
 \frac{\partial}{\partial x^{c}}\vect{b}(\vect{x}) & =
 \vect{\mathcal{H}}\left(\vect{x}, \vect{a}(\vect{x}),
 \vect{b}(\vect{x})\right).
 \label{eq:xmdsPdeIp}
\end{align}
This form is significantly more restrictive than that of
\eqn{eq:xmdsPdeEx}. In particular, the linear operator matrix must be
diagonal, and may not have coefficients with spatial dependence.
\end{enumerate}

Within both of these pictures, either the semi-Implicit or
Runge-Kutta algorithms may be employed.  For more detail
refer \Sec{sec:numericalMethodsPde}. This gives rise to the
matrix of algorithms listed in \tab{tab:algorithmMatrix}.
\begin{table}[ht]
\begin{center}
\begin{tabular}{|c|c|c|}
\hline 
 & Explicit picture & Interaction picture\\
\hline 
\hline 
Semi-Implicit & SIEX & SIIP\\
\hline 
4th Order Runge-Kutta & RK4EX & RK4IP\\
\hline 
4th/5th Order adaptive Runge-Kutta & ARK45EX & ARK45IP\\
\hline 
9th Order Runge-Kutta & RK9EX & RK9IP\\
\hline 
8th/9th Order adaptive Runge-Kutta & ARK89EX & ARK89IP\\
\hline 
\end{tabular}
\end{center}
\caption{The Algorithm Matrix}
\label{tab:algorithmMatrix}
\end{table}

There are two main things that \xmds can do to a field: forward
evolve (integrate/ propagate) it according to the set of PDEs, and
reshape (filter) it according to a set of functions. These two actions
may serve as the building blocks for an elaborate sequence of
operations to be performed on the field. This is done by defining a
sequence of {\em segments}; a segment being either an integrate step,
a filter step, or else a sub-loop of further segments.

The key to \xmds, as explained in the introduction, is that it is
a {\em code generator}. \xmds requires the user to write their
particular PDEs (or ODEs) as a few lines of C code, which are
transplanted from the input script to the relevant points in the
output code. This technique proves itself well for efficient code that
is extremely flexible. A potential user should not be daunted at the
prospect of having to learn basic C syntax -- the flexibility gained
by this approach well justifies the effort.

In terms of output results, it is usually desired to sample the field
at various points throughout the sequence of operations and thus
generate a sequence of samples. Further, when sampling, often the raw
complex value of the field at the point in question is not relevant,
it is a more general {\em moment} of field components and dimensions
that is desired. The examples provided in
Chapters~\ref{chap:exampleNlse} and~\ref{chap:moreExamples} will help
explain. Also, the evolution of the field is usually solved on a
lattice much finer than is necessary to make a good plot of the
output. Thus to save on memory and also size of output file it is
better to sample on some reduced lattice rather than at every point in
the main field lattice. It may also be desirable, when sampling for a
particular group of moments, to transform the field to Fourier space
in one, some or all of the transverse dimensions. At this point it is
also possible to collapse one or more of the transverse dimensions by
requesting either to sample a cross-section or else to integrate over
the dimension in question with a particular kernel function. Once all
field propagations are finished the sampled output can be
post-processed to transform the propagation dimension into Fourier
space, and again place the remaining transverse dimensions into any
partial Fourier space, which may be the same or different to the one
in which the field was sampled in. The original sampled moments may be
used here or moments of these moments may be specified. Finally, if
the evolution of the field involves stochastic terms, it will usually
be desired to perform this sequence of operations a number of times
(re-initialising the field each time) so as to determine averages and
standard errors in those averages for the output moments over multiple trajectories,
or {\em paths}.

Diagrammatically, the functionality of \xmds is shown in
\fig{fig:functionality}.
\begin{figure}[ht]
\centerline{\includegraphics[width=\figwidth]{figures/funct}}
\caption{\xmds---a functional diagram}
\label{fig:functionality}
\end{figure}
Usually, using \xmds is much simpler than this---look at the
worked examples!

\section{Installing and Running \xmds}

This software package is designed to install onto Unix and Linux
operating systems (including the Cygwin environment on Windows),
though an experienced programmer might easily port it to another
platform. \xmds requires a very small amount of disk space, and the RAM 
required is dependent algorithm, but is usually little more than the size needed 
to store a certain number of copies of the fields to be integrated. A C++ compiler is
required as are also the FFTW (Fastest Fourier Transform in the West)
libraries for C. Further, for stochastic problems \xmds can produce
output code which uses MPI routines to parallelise the problem for
running on multiple CPUs or computer clusters.  An MPI compiler is
required to take advantage of this.  XMDS can also use an OpenMP threads
to use multiple processors on single jobs if an OpenMP-enabled compiler is 
available.

\subsection{Installation}

Installation instructions and files are available at:
\htmladdnormallink{http://www.xmds.org/downloads}{http://www.xmds.org/downloads}

First, if parallel processing is desired, a working MPI system and/or an OpenMP-enabled compiler should be installed.

Second, the FFTW libraries must be installed if they are not already
present. These libraries may be found at:
\htmladdnormallink{http://www.fftw.org/}{http://www.fftw.org/}.  Version 2.1.x (and, optionally 3.x) of the fftw library is required for proper execution of
\xmds.  \xmds expects that the \ttt{fftw.h} header file is in one of
the \ttt{/usr/include} or the \ttt{/usr/local/include} directories,
with the libraries in a sibling \ttt{/usr/lib} or \ttt{/usr/local/lib}
directory. These are the standard locations. If the fftw installation
is non-standard then you will need to use the\ttt{--with-fftw-path}
option for the \ttt{configure} program, pointing to the
parent directory containing the fftw \ttt{/include} and \ttt{/lib}
sub-directories.  If parallel processing is desired, FFTW must be built with
MPI or OpenMP options enabled.

The main method of installation is from a ``tarball''.  Download
  \ttt{xmds-\xmdsVersion.tar.gz} and then (as
  root)~\footnote{\tbf{Note:} when \ttt{fftw} is installed in
  \ttt{/usr/local} then \ttt{--with-fftw-path} must be specified so
  that the configure script can find the libraries and headers.}:
\begin{latexonly}
\begin{shellCode}[escapeinside='']
tar -xzvf xmds-'\xmdsVersion'.tar.gz
cd xmds-'\xmdsVersion'
./configure
make
make install
\end{shellCode}
\end{latexonly}
%
\begin{htmlonly}
\begin{shellCode}
tar -xzvf xmds-\xmdsVersion.tar.gz
cd xmds-\xmdsVersion
./configure
make
make install
\end{shellCode}
\end{htmlonly}
  or as a user (to be installed in the \ttt{bin} directory of your
  home directory):
\begin{latexonly}
\begin{shellCode}[escapeinside='']
tar -xvzf xmds-'\xmdsVersion'.tar.gz
cd xmds-'\xmdsVersion'
./configure --with-user
make
make install
\end{shellCode}
\end{latexonly}
%
\begin{htmlonly}
\begin{shellCode}[escapeinside='']
tar -xvzf xmds-\xmdsVersion.tar.gz
cd xmds-\xmdsVersion
./configure --with-user
make
make install
\end{shellCode}
\end{htmlonly}
  For help on the various configuration options, one can run the
  command
\begin{shellCode}
./configure --help
\end{shellCode}
  which will show a (very long) list of options which can be changed
  to customise the way \xmds is installed and the options that it can
  use to build simulations.  The different variables that one can
  change are:
  \begin{itemize}
  \item \ttt{XMDS\_CC}: the C++ compiler used by \xmds to compile
  simulations
  \item \ttt{XMDS\_CFLAGS}: the C++ compiler flags used to build
  simulations
  \item \ttt{XMDS\_LIBS}: the libraries used to build simulations
  \item \ttt{XMDS\_INCLUDES}: the include flags used for building
  simulations
  \item \ttt{FFTW\_LIBS}: the libraries specific to \ttt{fftw}
  \item \ttt{FFTW\_MPI\_LIBS}: the libraries specific to \ttt{fftw} but
    for the MPI compiler
  \item \ttt{FFTW3\_LIBS}: the libraries specific to version 3 of \ttt{fftw}
  \item \ttt{MPICC}: the MPI C++ compiler
  \item \ttt{MPICCFLAGS}: the compiler flags to use with \ttt{mpicc}
  \item \ttt{MPILIBS}: the library flags to pass to \ttt{mpicc}
  \item \ttt{USER\_LIB}: the location of the file \xmds library
    functions, only necessary if \xmds is compiled for user use
    (e.g. \ttt{-L/home/cochrane/bin})
  \item \ttt{USER\_INCLUDE}: the location of the \xmds header files,
    only necessary if \xmds is compiled for user use
    (e.g. \ttt{-I/home/cochrane/bin})
  \end{itemize}
  One can also set various options on the command line as arguments to
  the configure script.  The options available are:
  \begin{itemize}
  \item \ttt{--with-user}: to install \xmds into the user's \ttt{bin}
    directory within their home directory.  This will also point the
    \ttt{USER\_LIB} and \ttt{USER\_INCLUDE} variables to the correct
    places so that \xmds will find its required headers and libraries
    so that it can build simulations.
  \item \ttt{--enable-mpi}: to check for MPI in the configuration and
    to enable the use of MPI for building simulations.
  \item \ttt{--enable-threads}: to check for the ability of the fftw libraries to use threads, and enable their use  in simulations.
  \item \ttt{--enable-fftw3}: to check for version 3 of fftw and enable
    use of it for building simulations.
  \item \ttt{--with-fftw-path}: the path to the \ttt{fftw}
    installation.  \tbf{Note:} when \ttt{fftw} is installed in
    \ttt{/usr/local} then \ttt{--with-fftw-path} must be specified so
    that the configure script can find the libraries and headers.
  \item \ttt{--with-fftw3-path}: the path to the \ttt{fftw3} installation
     (if different to the path for fftw2).
  \item \ttt{--with-mpi-libs}: extra libraries needed when checking
    for MPI.
  \item \ttt{--with-mpi-path}: set the path to the prefix of your MPI
    distribution.
  \item \ttt{--with-mpi-compiler}: set the mpi C++ compiler.
  \end{itemize}

\subsection{Usage}

For usage, at the command prompt type:
\begin{shellCode}
% xmds
\end{shellCode}
and the output should be:
\begin{alltt}
This is xmds version \xmdsVersion,
 
        using C compiler 'gcc'
        (and C compiler 'mpicc' for parallel work)
 
 
Usage: xmds [-v] [-c] infile
        infile: required,  the input file
             v: optional,  verbose mode
             c: optional,  turns off automatic compilation of simulation
\end{alltt}
or something similar. The ``verbose'' mode can be quite useful as it
will repeat back to the user exactly how it is interpreting the input
file.  Switching off automatic compilation can be handy when one is
testing a script and doesn't want to wait for the script to compile,
especially if the resultant binary isn't wanted anyway.  This option
can also be used by those people who want to use \xmds to produce a
skeleton C++ code with which they want to change directly themselves
to perform something more complex than is yet possible with \xmds.

The first thing \xmds does is run the input file through its own
XML parser. If the input file contains bad XML syntax then these will
be the first errors to be picked upon. \xmds then processes the
input file, and writes the code dedicated to solving the particular
simulation, and compiles it.

\begin{shellCode}
% xmds nlse.xmds
compiling ...
     gcc    -pthread -O3 -ffast-math -funroll-all-loops
     -fomit-frame-pointer -o nlse nlse.cc  -I/home/cochrane/bin
     -lstdc++ -lm -lxmds -L/home/cochrane/bin -lfftw_threads -lfftw 
'nlse' ready to execute
\end{shellCode}

All that remains is to execute the compiled program:
\begin{shellCode}
% nlse
\end{shellCode}

Refer to the \ttt{kubo.xmds} example in \Sec{sec:kubo.xmds} for
execution of a parallel problem.  Or see
\Chap{chap:stochasticSimsAndMPI}.

\subsection{Preferences}

As of \ttt{xmds-1.3-1} it is possible for people to specify the
simulation build options in a preferences file.  Previously, if one
wanted to change how the simulations were built, one had to recompile
\xmds with the relevant compile flags etc.  Now, all one has to do is
specify the compilation flags in a preferences file.  \xmds looks for
a file called \ttt{xmds.prefs} in \ttt{\$HOME/.xmds/} and (if not
found there) in the directory local to the xmds script you are trying
to compile.  The format of the preferences file is:
\begin{quotation}
\ttt{<compile flag name> = <compile flag value>}
\end{quotation}
For example:
\begin{quotation}
\ttt{XMDS\_CC = gcc}
\end{quotation}

Comments can be added by using a hash character (\ttt{\#}).  Any thing
after (and including) the hash are ignored.  As another example of a
preferences file, here is an example \ttt{xmds.prefs}:
\begin{shellCode}
# xmds preferences file
XMDS_CC=gcc  # this, here, is a comment
XMDS_CFLAGS = -pthread -O3 -ffast-math -funroll-all-loops
XMDS_LIBS=-lstdc++ -lm -lxmds -L/home/cochrane/bin
XMDS_INCLUDES = -I/home/cochrane/bin
THREADLIBS = -lfftw_threads
\end{shellCode}

The use of preferences can be switched on and off with the use of the
\xmdsTag{use\_prefs} tag (which should be located after the
\xmdsTag{simulation} element, near where \xmdsTag{error\_check} and
friends live).  This is a boolean option, so to switch preferences off
one should use \ttt{no}.  The default is \ttt{yes}, but if you don't
have any preferences, or you haven't specified them all, then the
default values (that were decided when \xmds was built) are used for
anything not specified.


\section{Syntax summary} 
\label{sec:syntaxSummary}

The xml elements used can be divided into two main categories: those
that may contain code and/or other elements, and those that merely
contain variable assignments. The former can perhaps be called
``structural'' elements, and the latter perhaps ``assignment''
elements.  These are summarised in Tables~\ref{tab:structuralElements}
and~\ref{tab:assignmentElements} respectively.

\begin{center}
\begin{longtable}{|c|c|c|l|}
\hline 
Element name & Used in & Req. & May contain\\
\hline
\hline
\xmdsTag{simulation}    &top level &yes   &\xmdsTag{name}, \xmdsTag{prop\_dim}, \xmdsTag{error\_check},\\
                       &          &   &\xmdsTag{stochastic}, \xmdsTag{paths}, \xmdsTag{noises}, \xmdsTag{argv}\\
                       &          &   &\xmdsTag{globals}, \xmdsTag{field}, \xmdsTag{sequence}, \xmdsTag{output}\\
                       &          &   &\xmdsTag{binary\_output}, \xmdsTag{use\_double}, \xmdsTag{use\_wisdom}\\
                       &          &   &\xmdsTag{benchmark}, \xmdsTag{use\_prefs}, \xmdsTag{argv},  \xmdsTag{threads}\\
                       &          &   &\xmdsTag{fftw\_version}\\
\hline
\xmdsTag{globals}       &\xmdsTag{simulation} &no    &C code\\
\hline
\xmdsTag{argv}         & \xmdsTag{simulation} & no & \xmdsTag{arg}\\
\hline
\xmdsTag{arg}          & \xmdsTag{argv}       & yes & \xmdsTag{name}, \xmdsTag{type}, \xmdsTag{default\_value}\\
\hline
\xmdsTag{field}         &\xmdsTag{simulation} &yes   &\xmdsTag{name},
\xmdsTag{dimensions}, \xmdsTag{lattice}\\
                       &                    &      &\xmdsTag{domains}, \xmdsTag{samples}, \xmdsTag{vector}\\
\hline
\xmdsTag{vector}        &\xmdsTag{field}      &yes   &\xmdsTag{name}, \xmdsTag{type}, \xmdsTag{components}, \xmdsTag{vectors}\\
                       &                    & &\xmdsTag{filename}, \xmdsTag{fourier\_space}, and C code\\
\hline
\xmdsTag{sequence}      &\xmdsTag{simulation} &yes &\xmdsTag{integrate}, \xmdsTag{filter}, \xmdsTag{sequence}\\
\cline{2-4}
                       &\xmdsTag{sequence} &no   &\xmdsTag{cycles}, \xmdsTag{integrate}\\
                       &                  &     &\xmdsTag{filter}, \xmdsTag{sequence}\\
\hline
\xmdsTag{integrate}     &\xmdsTag{sequence} &no &\xmdsTag{algorithm}, \xmdsTag{interval}, \xmdsTag{lattice}, \xmdsTag{samples},\\
                       &                  & &\xmdsTag{k\_operators}, \xmdsTag{vectors}, \xmdsTag{cross\_propagation},\\
                       &                  &     &\xmdsTag{iterations}, \xmdsTag{moment\_group}, \xmdsTag{tolerance},\\ 
                       &                  &     &\xmdsTag{max\_iterations}, \xmdsTag{min\_time\_step}, \xmdsTag{cutoff},\\
                       &                  &     & \xmdsTag{smallmemory}, \xmdsTag{no\_noise}, \xmdsTag{halt\_non\_finite},\\
                       &                  &     &and C code\\
\hline
\xmdsTag{k\_operators}   &\xmdsTag{integrate} &no   &\xmdsTag{constant},\\
                       &                   &     &\xmdsTag{operator\_names}, and C Code\\
\hline
\xmdsTag{cross\_propagation} &\xmdsTag{integrate} &no&\xmdsTag{prop\_dim}, \xmdsTag{vectors}, and C Code\\
\hline
\xmdsTag{filter}        &\xmdsTag{sequence} &no&\xmdsTag{fourier\_space}, \xmdsTag{vectors},  \xmdsTag{functions}, \\
		   &	&	& \xmdsTag{moment\_group}, and C Code\\
\hline
\xmdsTag{output}        &\xmdsTag{simulation} &yes &\xmdsTag{filename}, \xmdsTag{group}\\
\hline
\xmdsTag{group}         &\xmdsTag{output} &yes  &\xmdsTag{sampling}, \xmdsTag{post\_propagation}\\
\hline
\xmdsTag{sampling}      &\xmdsTag{group} &yes  &\xmdsTag{lattice}, \xmdsTag{fourier\_space},\\
                       &               &     &\xmdsTag{vectors}, \xmdsTag{moments}, \xmdsTag{type}, and C code\\
\hline
\xmdsTag{post\_propagation}&\xmdsTag{group} &no& \xmdsTag{fourier\_space}, \xmdsTag{moments}, and C Code\\
\hline
\caption{The structural elements}
\label{tab:structuralElements}
\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|c|c|c|l|}
\hline 
Element name           &Used in &Req. &May contain\\
\hline
\hline
\xmdsTag{name}          &\xmdsTag{simulation} &no    &string: defaults to filename-extn\\
\cline{2-4}
                       &\xmdsTag{field}      &no    &string: defaults to ``main''\\
\cline{2-4}
                       &\xmdsTag{vector}     &yes   &string\\
\cline{2-4}
                       & \xmdsTag{arg}      & yes  & string\\
\hline
\xmdsTag{prop\_dim}      &\xmdsTag{simulation}        &yes   &string\\
                       &\xmdsTag{cross\_propagation} &      &\\
\hline
\xmdsTag{error\_check}   &\xmdsTag{simulation} &no    &yes/no: defaults to yes\\
\hline
\xmdsTag{stochastic}    &\xmdsTag{simulation} &no    &yes/no: defaults to no\\
\hline
\xmdsTag{use\_mpi}       &\xmdsTag{simulation} &no    &yes/no: defs. to no\\
\hline
\xmdsTag{MPI\_Method}       &\xmdsTag{simulation} &no    &Scheduling/Uniform: defs. to Scheduling\\
\hline
\xmdsTag{paths}         &\xmdsTag{simulation} &--    &integer: reqd. if stochastic\\
\hline
\xmdsTag{seed}          &\xmdsTag{simulation} &--    &integer: 2 reqd. if stochastic\\
\hline
\xmdsTag{noises}        &\xmdsTag{simulation} &--    &integer: reqd. if stochastic\\
\hline
\xmdsTag{dimensions}    &\xmdsTag{field} &no   &array of strings\\
\hline
\xmdsTag{lattice}       &\xmdsTag{field}     &--   &array of integers,\\
                       &\xmdsTag{sampling}  &     &same no. as trans. dims \\
\cline{2-4}
                       &\xmdsTag{integrate} &yes  &integer\\
\hline
\xmdsTag{domains}       &\xmdsTag{field} &--   &array of bracketed pairs of floats\\
\hline
\xmdsTag{components}    &\xmdsTag{vector}       &yes &array of strings\\
\hline
\xmdsTag{type}          &\xmdsTag{vector}       &no &\xmdsTag{complex} or \xmdsTag{double}\\
				&\xmdsTag{sampling} & & \\
\cline{2-4}
                       & \xmdsTag{arg}        & yes & string\\
\hline
\xmdsTag{vectors}       &\xmdsTag{vector}       &no &array of strings\\
                       &\xmdsTag{k\_operators}  & &\\
                       &\xmdsTag{sampling}     & &\\
\cline{2-4}
                       &\xmdsTag{integrate}    & yes & array of strings\\
                       &\xmdsTag{filter}     & &\\
                       &\xmdsTag{cross\_propagation}    & &\\
\hline
\xmdsTag{moment\_group}       &\xmdsTag{integrate}       &no &array of strings\\
                       &\xmdsTag{filter}     & &\\
\hline
\xmdsTag{functions}       &\xmdsTag{integrate}       &no &array of strings\\
                       &\xmdsTag{filter}     & &\\
\hline
\xmdsTag{constant}      &\xmdsTag{k\_operators}            &no &yes/no: defaults to no\\
\hline
\xmdsTag{operator\_names}    &\xmdsTag{k\_operators}            &yes &array of strings\\
\hline
\xmdsTag{filename}      &\xmdsTag{vector} &no &string\\
\cline{2-4}
                       &\xmdsTag{output} &no &string: defaults to \ttt{<name>.xsil}\\
\hline
\xmdsTag{fourier\_space} &\xmdsTag{vector}, \xmdsTag{filter}   &no    &array of yes/no\\
\cline{2-4}
                       &\xmdsTag{sampling} &yes   &array of yes/no \\
\cline{2-4}
                       &\xmdsTag{post\_propagation} &yes  &array of yes/no: same no. as\\
                       &                          &     &non-collapsed trans. dims + 1\\
\hline
\xmdsTag{samples}       &\xmdsTag{field}   &yes &integer: as many as are \xmdsTag{group}\\
                       &\xmdsTag{integrate} &    & \\
\hline
\xmdsTag{cycles}        &\xmdsTag{sequence} &yes   &integer (not in main sequence)\\
\hline
\xmdsTag{algorithm}     &\xmdsTag{integrate} &no  &string: defaults to RK4EX (or\\
                       &                   &    &SIEX for stochastic problems)\\
\hline
\xmdsTag{interval}      &\xmdsTag{integrate} &yes  &string\\
\hline
\xmdsTag{no\_noise}      &\xmdsTag{integrate} &no  &yes/no, defaults to no\\
\hline
\xmdsTag{iterations}    &\xmdsTag{integrate} &no   &(SIIP: integer, defaults to 3)\\
\hline
\xmdsTag{tolerance}    &\xmdsTag{integrate} &yes   &(ARK45: string)\\
\hline
\xmdsTag{max\_iterations}    &\xmdsTag{integrate} &no   &(ARK45: integer, defaults to infinity)\\
\hline
\xmdsTag{min\_time\_step}    &\xmdsTag{integrate} &no   &(ARRK45/89: double, defaults to \ttt{1e-13})\\
\hline
\xmdsTag{cutoff}    &\xmdsTag{integrate} &no   &(ARK45: string, defaults to 1e-3)\\
\hline
\xmdsTag{smallmemory}    &\xmdsTag{integrate} &no   &(ARK45IP: yes/no, defaults to no)\\
\hline
\xmdsTag{halt\_non\_finite} & \xmdsTag{integrate} & no & yes/no: defaults to no\\
\hline
\xmdsTag{moments}       &\xmdsTag{sampling}         &yes  &array of strings\\
                       &\xmdsTag{post\_propagation} &     &\\
\hline
\xmdsTag{default\_value} & \xmdsTag{arg}   & yes & depends upon \xmdsTag{type} declaration\\
\hline
\xmdsTag{benchmark}    & \xmdsTag{simulation} & no & yes/no: defaults to no\\
\hline
\xmdsTag{use\_wisdom}  & \xmdsTag{simulation} & no & yes/no: defaults to no\\
\hline
\xmdsTag{binary\_output}& \xmdsTag{simulation} & no & yes/no: defaults to no (\tbf{deprecated})\\
\hline
\xmdsTag{use\_double}  & \xmdsTag{simulation} & no & yes/no: defaults to no (\tbf{deprecated})\\
\hline
\xmdsTag{use\_prefs} & \xmdsTag{simulation} & no & yes/no: defaults to yes\\
\hline
\caption{The assignment elements}
\label{tab:assignmentElements}
\end{longtable}
\end{center}

\section{C-coding within elements} 
\label{sec:c-coding}

\xmds is all about transplanting equations into the necessary
multi-dimensional loop structure to solve them, which has the direct
consequence that it is necessary for your equations to be written in
standard C syntax. To begin with, variable names may not start with a
number, and may not be a reserved keyword such as {\em void, int,
long, double, complex, for, while, if, switch, return, etc...}. This
applies to the variable names listed in the \xmdsTag{dimensions},
\xmdsTag{components}, \xmdsTag{operator\_names}, and \xmdsTag{moments}
assignments. It also applies to user defined variables where C-code is
allowed.

Globals should be declared as:
\begin{CCode}
const long int1 = 7;
const double real1 = 23.45;
const complex comp1 = complex(0.4,0.2);

double r = sqrt(x*x + y*y);
complex z = pcomplex(r,M_PI/2);
\end{CCode}
As can be seen there are three main variable types available:
integers, reals, and complex -- best declared as \ttt{long},
\ttt{double}, and \ttt{complex} respectively. The range of
mathematical functions available is the same as that for
C-programming, as well as some complex functions defined in the
\ttt{xmdscomplex.h} header file in the \ttt{/source} directory. The
ones most likely to be of use are summarised in
\tab{tab:functions}. And remember, avoid using transcendental
functions in the main integration equations if speed is important.

\begin{table}
\begin{center}
\begin{tabular}{|c|c|c|c|}
\hline 
Function name&Math&Argument(s)&Result\\
\hline 
\hline 
\ttt{abs(n)}&$|n|$&integer&integer\\
\hline 
\ttt{fabs(x)}&$|x|$&real&real\\
\hline 
\ttt{exp(x)}&$e^{x}$&real&real\\
\hline 
\ttt{log(x)}&$ln(x)$&real&real\\
\hline 
\ttt{sqrt(x)}&$\sqrt{x}$&real&real\\
\hline 
\ttt{pow(x,y)}&$x^{y}$&real,real&real\\
\hline
\ttt{sin(x)}&$sin(x)$&real&real\\
\hline
\ttt{asin(x)}&$sin^{-1}(x)$&real&real\\
\hline 
\ttt{cos(x)}&$cos(x)$&real&real\\
\hline 
\ttt{acos(x)}&$cos^{-1}(x)$&real&real\\
\hline 
\ttt{tan(x)}&$tan(x)$&real&real\\
\hline 
\ttt{atan(x)}&$tan^{-1}(x)$&real&real\\
\hline 
\ttt{cot(x)}&$cotan(x)$&real&real\\
\hline 
\ttt{complex(x,y)}&$x+iy$&real,real&complex\\
\hline 
\ttt{rcomplex(x,y)}&$x+iy$&real,real&complex\\
\hline 
\ttt{pcomplex(x,y)}&$xe^{iy}$&real,real&complex\\
\hline 
\ttt{conj(z)} or \ttt{~z} &$z^{*}$&complex&complex\\
\hline 
\ttt{c\_exp(z)}&$e^{z}$&complex&complex\\
\hline 
\ttt{c\_log(z)}&$ln(z)$&complex&complex\\
\hline 
\ttt{c\_sqrt(z)}&$\sqrt{z}$&complex&complex\\
\hline 
\ttt{real(z)}&$real\{z\}$&complex&real\\
\hline 
\ttt{imag(z)}&$imag\{z\}$&complex&real\\
\hline 
\ttt{mod(z)}&$|z|$&complex&real\\
\hline 
\ttt{arg(z)}&$imag\{ln(z)\}$&complex&real\\
\hline 
\ttt{mod2(z)}&$|z|^{2}$&complex&real\\
\hline
\end{tabular}
\end{center}
\caption{Commonly used functions}
\label{tab:functions}
\end{table}

It is also possible to create piece-wise functions by using \ttt{if}
statements, which must be done in the usual C syntax.  Here are two
alternate syntaxes that will turn on functions \ttt{damping1} and
\ttt{damping2} after \ttt{t=1.0} and \ttt{t=2.0} respectively:
\begin{CCode}
double damping1;

if(t>1.0)
  damping1 = 1.0;
else
  damping1 = 0;

const double damping2 = t>2.0? 1 : 0;
\end{CCode}

\xmds automatically declares a number of variables, depending on
the element, for the equations to reference. These are summarised in
\tab{tab:declaredVariables}. If a particular dimension is in
Fourier space (ie. if the corresponding \xmdsTag{fourier\_space}
assignment was ``\ttt{yes}'') then it is referenced by its name as
specified in the \xmdsTag{field} element but prefixed by a
``\ttt{k}''.

\begin{table}
\begin{center}
\begin{tabular}{|c|l|}
\hline
                 & Example for:\\
                 & \xmdsTag{prop\_dim}z\xmdsTag{/prop\_dim}\\
                 & \xmdsTag{noises}2\xmdsTag{/noises}\\
                 & \xmdsTag{dimensions}x y\xmdsTag{/dimensions}\\
\hline
\hline
Variable         & Available in\\
\hline
\hline
\ttt{z}         & \xmdsTag{integrate}, \xmdsTag{k\_operators},\\
                 & \xmdsTag{filter}, \xmdsTag{sampling}\\
\hline
\ttt{z} or \ttt{kz}   & \xmdsTag{post\_propagation}\\
\hline
\ttt{dz}        & \xmdsTag{integrate}, \xmdsTag{k\_operators}\\
\hline
\ttt{x} or \ttt{kx}   & \xmdsTag{vector}, \xmdsTag{integrate}, \xmdsTag{k\_operators},\\
\ttt{y} or \ttt{ky}   & \xmdsTag{sampling},\\
\ttt{dx} or \ttt{dkx} & and \xmdsTag{post\_propagation} where dimension\\
\ttt{dy} or \ttt{dky} & hasn't been collapsed\\
\hline
\ttt{n\_1, n\_2}          & \xmdsTag{vector}, \xmdsTag{integrate}, \xmdsTag{filter}\\
\hline
\end{tabular}
\end{center}
\caption{Automatically declared variables}
\label{tab:declaredVariables}
\end{table}

Finally, be wary of unintentional integer divisions, for example
\ttt{const double c = 1/2;}, as the compiler will perform an integer
division on the \ttt{1/2} before converting to a double, resulting in
\ttt{c=0.0}!  It ought to be written as \ttt{const double c = 1.0/2;}
if \ttt{c=0.5} was the intended result.