% $Id: languageReference.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{Language Reference}
\label{chap:languageRef}

%%% simulation
\section{simulation}
\label{lab:simulation}
\index{simulation@\xmdsTag{simulation}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{simulation}{simulation}
\xmdsOption{xmds tags} \xmdsTag{/simulation}

\item[Contains:]  
\xmdsTagLink{name(simulation)}{name}, 
\xmdsTagLink{prop_dim(simulation)}{prop\_dim}, 
\xmdsTagLink{error_check}{error\_check}, 
\xmdsTagLink{stochastic}{stochastic}, 
\xmdsTagLink{globals}{globals}, 
\xmdsTagLink{use_mpi}{use\_mpi}, 
\xmdsTagLink{MPI_Method}{MPI\_Method}, 
\xmdsTagLink{field}{field}, 
\xmdsTagLink{sequence}{sequence}, 
\xmdsTagLink{output}{output}, 
\xmdsTagLink{noises}{noises}, 
\xmdsTagLink{paths}{paths}, 
\xmdsTagLink{benchmark}{benchmark}, 
\xmdsTagLink{binary_output}{binary\_output} (obsolete), 
\xmdsTagLink{use_wisdom}{use\_wisdom}, 
\xmdsTagLink{use_double}{use\_double} (obsolete),
\xmdsTagLink{use_prefs}{use\_prefs},
\xmdsTagLink{argv}{argv},
\xmdsTagLink{threads}{threads},
\xmdsTagLink{use_openmp}{use\_openmp},
\xmdsTagLink{fftw_version}{fftw\_version}

\item[Subelement of:] None

\item[Path to tag:] \xmdsTag{simulation}

\item[Description:] Container tag for the \xmds simulation code.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
   <!-- xmds tags -->
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% name (simulation)
\section{name (simulation)}
\label{lab:name(simulation)}
\index{name (simulation)@\xmdsTag{name} (simulation)}
\begin{xmdsDoc}
\item \optl 
\xmdsTagTarg{name(simulation)}{name}
\xmdsOption{string} \xmdsTag{/name}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{name}

\item[Description:] The name of the \xmds simulation.  Defines the 
name of the output C code file and subsequently the name of the 
simulation binary executable.  This tag is optional, and if not 
specified then the output filenames will be derived from the xmds 
script filename minus its last extension.  For instance, for the 
\texttt{atomlaser.xmds} script, the base for the output \texttt{.cc} 
file will be \texttt{atomlaser}.  This isn't really a very instructive 
example\ldots

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <name> atomlaser </name>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% prop_dim (simulation)
\section{prop\_dim (simulation)}
\label{lab:prop_dim(simulation)}
\index{prop_dim (simulation)@\xmdsTag{prop\_dim} (simulation)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{prop_dim(simulation)}{prop\_dim}
\xmdsOption{string} \textsf{variableName} \xmdsTag{/prop\_dim}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{prop\_dim}

\item[Description:] The name of the main propagation direction.  This 
name must appear in the equations supplied.  This condition, however, 
is not checked and therefore a possible source of error for the user.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <prop_dim> z </prop_dim>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% error_check
\section{error\_check}
\label{lab:error_check}
\index{error_check@\xmdsTag{error\_check}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{error_check}{error\_check}
\xmdsOption{bool} \xmdsTag{/error\_check}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{error\_check}

\item[Description:] Whether or not to run the simulation at half the
time step as well as at the full time step and give the difference
between the results.  Defaults to \texttt{yes}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <error_check> yes </error_check>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% use_mpi
\section{use\_mpi}
\label{lab:use_mpi}
\index{use_mpi@\xmdsTag{use\_mpi}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{use_mpi}{use\_mpi}
\xmdsOption{bool} \xmdsTag{use\_mpi}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{use\_mpi}

\item[Description:] Whether or not to use MPI routines for parallel processing of the simulation.  This writes very different code depending on whether the simulation is stochastic or non-stochastic.  Only certain problems on certain systems can be efficiently parallelised when the equations are non-stochastic.  Defaults to \texttt{no}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <use_mpi> yes </use_mpi>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% stochastic
\section{stochastic}
\label{lab:stochastic}
\index{stochastic@\xmdsTag{stochastic}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{stochastic}{stochastic}
\xmdsOption{bool} \xmdsTag{/stochastic}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{stochastic}

\item[Description:] Defaults to \ttt{no}.  Tells \xmds whether or not
the simulation uses Gaussian noise terms.  If this tag is set to
\texttt{yes} then the \xmdsTag{paths}, \xmdsTag{seeds} and
\xmdsTag{noises} tags become compulsory.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <stochastic> no </stochastic>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% MPI_Method
\section{MPI\_Method}
\label{lab:MPI_Method}
\index{MPI_Method@\xmdsTag{MPI\_Method}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{MPI_Method}{MPI\_Method}
\xmdsOption{string} \xmdsTag{/MPI\_Method}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{MPI\_Method}

\item[Description:] Defaults to \ttt{Scheduling}.  For stochastic simulations
using MPI, it tells \xmds which method to use for splitting the paths 
between different processors.  The default "Scheduling" option is 
usually optimal, but requires the use of threads.  If threads are unavailable, the 
"Uniform" option should be used.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <MPI_Method> Uniform </MPI_Method>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% paths
\section{paths}
\label{lab:paths}
\index{paths@\xmdsTag{paths}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{paths}{paths}
\xmdsOption{int} \xmdsTag{/paths}\\
(\reqd if \xmdsTag{stochastic} is \texttt{yes})

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{paths}

\item[Description:] The number of stochastic paths to integrate.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <paths> 3 </paths>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% seed
\section{seed}
\label{lab:seed}
\index{seed@\xmdsTag{seed}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{seed}{seed} \xmdsOption{int} \xmdsOption{int}
\xmdsTag{/seed}\\
(\reqd if \xmdsTag{stochastic} is \texttt{yes})

\item[Contains:] array of two integers

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{seed}

\item[Description:] The seed to the random number generator.
  Internally, these are the seeds passed to the C routine
  \ttt{erand48()} to generate two independent random number
  generators, hence the use of two integers.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <seed> 1 2 </seed>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% noises
\section{noises}
\label{lab:noises}
\index{noises@\xmdsTag{noises}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{noises}{noises}
\xmdsOption{int} \xmdsTag{/noises}\\
(\reqd if \xmdsTag{stochastic} is \texttt{yes})

\item[Contains:] integer

\item[Attributes:] \optl
  \ttt{kind="gaussian|gaussFast|poissonian|uniform"},
  \ttt{mean="\xmdsOption{int}"} (\reqd for \ttt{poissonian})

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{noises}

\item[Description:] The number of noise terms in the simulation.
  \xmds automatically declares the variables \ttt{n\_1} \ldots
  \ttt{n\_\tit{m}} where \tit{m} is the number of noises specified.
  As of \xmds-1.3-3 the \xmdsTag{noises} tag now accepts attributes.
  Currently these are \ttt{gaussian}, \ttt{gaussFast},
  \ttt{poissonian}, and \ttt{uniform}.  Each refers to a different
  noise source; 
  \begin{description}
    \item[\ttt{gaussian}] refers to the original noise routine
      that \xmds uses.  It produces a Gaussian-distributed variable with mean of zero and
      variance of 1/(product of the propagation and transverse step sizes).
    \item[\ttt{gaussFast}] is a slightly faster implementation
      of the same routine, and will eventually replace the old
      \ttt{gaussian} routine.
    \item[\ttt{poissonian}] is a Poissonian noise
      source, and requires the \ttt{mean\_rate} attribute to be set to the
      desired mean rate of the Poissonian noise distribution.  Simulations where the mean rate
      is a function of the propagation dimension or other variables are not supported via this method,
      but judicious use of the functions element can allow this rate to be adjusted manually.
    \item[\ttt{uniform}] gives uniformly distributed noise on the
      interval $[0,1)$.
  \end{description}

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <noises kind="gaussian"> 1 </noises>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% benchmark
\section{benchmark}
\label{lab:benchmark}
\index{benchmark@\xmdsTag{benchmark}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{benchmark}{benchmark}
\xmdsOption{bool} \xmdsTag{/benchmark} \xmdsOneTwo

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{benchmark}

\item[Description:] Defaults to \texttt{no}.  Tells \xmds whether or
  not to put timing code around the main section of code (that part of
  the code excluding fftw creation and deletion) as a way of
  benchmarking the simulation, or at least giving an idea of how long
  the main section of code will take.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <benchmark> yes </benchmark>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% binary_output
\section{binary\_output}
\label{lab:binary_output}
\index{binary_output@\xmdsTag{binary\_output}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{binary_output}{binary\_output}
\xmdsOption{bool} \xmdsTag{/binary\_output} \xmdsOneTwo\\
\tsc{Obsolete}: see \xmdsTag{output}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{binary\_output}

\item[Description:] Defaults to \texttt{no}.  If set to \texttt{yes} 
\xmds saves data file in binary format instead of the default, ascii.

This tag is now obsolete.  Please specify the \ttt{format} attribute
in the \xmdsTag{output} tag.  
For example: \xmdsTag{output format="binary"}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <binary_output> yes </binary_output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% use_wisdom
\section{use\_wisdom}
\label{lab:use_wisdom}
\index{use_wisdom@\xmdsTag{use\_wisdom}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{use_wisdom}{use\_wisdom}
\xmdsOption{bool} \xmdsTag{/use\_wisdom} \xmdsOneTwo

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{use\_wisdom}

\item[Description:] Defaults to \texttt{no}.  If \texttt{yes} the 
simulation will use fftw's wisdom feature.  The simulation will look 
in the user's \texttt{\~{}/.xmds/wisdom} directory (or failing the 
existence of such a directory, in the directory local to the 
simulation binary executable) for a file labelled 
\texttt{<hostname>.wisdom} where \texttt{<hostname>} is the name of 
the computer currently running the simulation.  If such a file exists, 
then the \xmds simulation will load this wisdom as part of the fftw 
plan creation step, thus drastically reducing startup time of the 
simulation.  Any accumulated wisdom will be then added back to this 
file at the fftw plan deletion stage.  If no wisdom file is found, the 
simulation will create one in an appropriate location and then save 
any accumulated wisdom to this file.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <use_wisdom> no </use_wisdom>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% use_double
\section{use\_double}
\label{lab:use_double}
\index{use_double@\xmdsTag{use\_double}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{use_double}{use\_double}
\xmdsOption{bool} \xmdsTag{/use\_double} \xmdsOneTwo\\
\tsc{Obsolete}: see \xmdsTag{output}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{use\_double}

\item[Description:] Defaults to \texttt{yes}.  Decides the precision 
of the output data.  Only useful when \xmdsTag{use\_binary} is set 
to \texttt{yes}.  If set to \texttt{no} then single precision output 
is used.  This option is useful in reducing the size of the output 
files.

This tag is now obsolete.  Please specify the \ttt{precision}
attribute in the \xmdsTag{output} tag.  
For example: \xmdsTag{output precision="double"}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <use_double> no </use_double>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% use_prefs
\section{use\_prefs}
\label{lab:use_prefs}
\index{use_prefs@\xmdsTag{use\_prefs}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{use_prefs}{use\_prefs}
\xmdsOption{bool} \xmdsTag{/use\_prefs} \xmdsOneTwo

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{use\_prefs}

\item[Description:] Defaults to \ttt{yes}.  Tells \xmds whether or
  not to use the user preferences file (called \ttt{xmds.prefs})
  located in either the user's \ttt{.xmds} directory or within the
  directory local to the \xmds simulation script.  By default, \xmds
  will use the preferences file if it exists, if not then it uses the
  preferences set when \xmds was built.  One can explicitly use the
  build preferences by setting \xmdsTag{use\_prefs} to \ttt{no}.

  The format of the preferences file is a sequence of key/value pairs
  separated by an equals sign (=).  For instance, if one wished to
  change the compiler used by \xmds to compile simulations then one
  needs to change the \ttt{XMDS\_CC} variable.  Hence, to do set this
  to \ttt{icc}, for example, one would enter the following line into
  the \ttt{xmds.prefs} file:\\
  \ttt{XMDS\_CC = icc}

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <use_prefs> no </use_prefs>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% threads
\section{threads}
\label{lab:threads}
\index{threads@\xmdsTag{threads}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{threads}{threads}
\xmdsOption{int} \xmdsTag{/threads}

\item[Contains:] integer
\item[Subelement of:] \xmdsTagLink{simulation}{simulation}
\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{threads}
\item[Description:] If set to a value of $n \neq 1$, this tag tells \xmds to create a simulation that uses the threaded version of the FFT library, and to use $n$ threads for calculating the FFT's.
\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
	<threads> 3 </threads>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% use_openmp
\section{use\_openmp}
\label{lab:use_openmp}
\index{use_openmp@\xmdsTag{use\_openmp}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{use_openmp}{use\_openmp}
\xmdsOption{bool} \xmdsTag{/use\_openmp}

\item[Contains:] boolean
\item[Subelement of:] \xmdsTagLink{simulation}{simulation}
\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{use\_openmp}
\item[Description:] Defaults to \ttt{no}. Tells \xmds whether to make use of \htmladdnormallink{OpenMP}{http://www.openmp.org} compiler directives to instruct the compiler how to parallelise parts of the simulation other than the FFT's. The simulation will compile correctly if OpenMP by the compiler, and you will need to ensure that the correct flags are passed to the compiler to ensure that it does enable OpenMP support (e.g.\ for Intel's C compiler the flag \ttt{-openmp} must be passed to the compiler to enable OpenMP). OpenMP cannot be used simultaneously with MPI for deterministic simulations. Also, the number of OpenMP threads used in a simulation defaults to the number of physical processors available. Note that best performance will be achieved if FFTW is compiled to use OpenMP threads instead of the default \ttt{pthreads} if your simulations make use of OpenMP threads.

See the OpenMP website (\htmladdnormallink{http://www.openmp.org}{http://www.openmp.org}) for more information about OpenMP. As of mid-2006, Intel's icc compiler supports OpenMP, however the current release of GCC (4.1.1) does not. Support for OpenMP is planned for the 4.2 release of GCC.
\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <use_openmp> yes </use_openmp>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%% 

%%% fftw_version
\section{fftw\_version}
\label{lab:fftw_version}
\index{fftw_version@\xmdsTag{fftw\_version}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{fftw_version}{fftw\_version}
\xmdsOption{int} \xmdsTag{/fftw\_version}

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow \xmdsTag{fftw\_version}

\item[Description:] Defaults to \ttt{2}. This tag tells \xmds which version of the fftw
    library to use. Currently, fftw3 does not support distributed-memory fourier transforms
    using MPI, but only shared-memory transforms using threads. Consequently, fftw version 3
    can only be used for simulations that are not MPI-using deterministic simulations. Stochastic
    MPI simulations can take advantage of fftw3 as they do not need distributed-memory fourier transforms.
    
    To override the libraries that \xmds links against when compiling a simulation that uses fftw3, override
    the \ttt{FFTW3\_LIBS} library in your \ttt{xmds.prefs} file.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <fftw_version> 3 </fftw_version>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% globals
\section{globals}
\label{lab:globals}
\index{globals@\xmdsTag{globals}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{globals}{globals}
\xmdsOption{C code} \xmdsTag{/globals}

\item[Contains:] \CDATA block with C++ code

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{globals}

\item[Description:] Defines variables and constants that are globally
available to all sections of the output C code.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <globals>
        <![CDATA[
            const double energy = 4;
            const double vel = 0.0;
            const double hwhm = 1.0;
        ]]>
    </globals>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% argv
\section{argv}
\label{lab:argv}
\index{argv@\xmdsTag{argv}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{argv}{argv}
\xmdsOption{xmds tags} \xmdsTag{/argv} \xmdsOneTwo

\item[Contains:] \xmdsTagLink{arg}{arg}

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{argv}

\item[Description:] Overall tag containing the arguments to be
  supplied at the simulation command line.  Command line arguments can
  be very useful if one wants to vary parameters within the simulation,
  between simulation runs.  Hence one can write a (Perl/Python/shell)
  script to run the simulation over the various parameters, without
  having to rewrite an \xmds script, recompile and then rerun.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <argv>
        <!-- xmds tags -->
    </argv>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% arg
\subsection{arg}
\label{lab:arg}
\index{arg@\xmdsTag{arg}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{arg}{arg}
\xmdsOption{xmds tags} \xmdsTag{/arg} \xmdsOneTwo

\item[Contains:] \xmdsTagLink{name(arg)}{name}, 
\xmdsTagLink{type(arg)}{type},
\xmdsTagLink{default_value}{default\_value}

\item[Subelement of:] \xmdsTagLink{argv}{argv}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{argv} \textarrow \xmdsTag{arg}

\item[Description:] Container for the tags describing a given command
  line argument.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <argv>
        <arg>
            <!-- xmds tags -->
        </arg>
    </argv>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% name (arg)
\subsection{name (arg)}
\label{lab:name(arg)}
\index{name (arg)@\xmdsTag{name} (arg)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{name(arg)}{name}
\xmdsOption{char *} \xmdsTag{/name} \xmdsOneTwo

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{arg}{arg}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{argv} \textarrow \xmdsTag{arg} \textarrow \xmdsTag{name}

\item[Description:] The name of the command line argument.  This tag
  is used to create a flag to specify the value of the variable
  entered at the command line.  Two forms are accepted: a short form
  and a long form, each conforming to the GNU getopt conventions.  For
  instance, for a variable named \ttt{nconst} the flag used at the
  command line will have a short form of \ttt{-n} and a long form of
  \ttt{--nconst}.  However, if another variable has been chosen
  beginning with the letter n, then \ttt{-n} is no longer unique, and
  to make the short flag unique, \xmds chooses the next character in
  the variable name, in this case the letter c, and making the short
  form flag \ttt{-c}.  The long form remains the same,
  i.e.~\ttt{--nconst}.  Of course, if the letter c has also been used
  then \xmds loops through all of the other letters in the variable
  name until it finds a match.  If no match is found \xmds reports an
  error.

  To check the short and long forms of the flags the simulation
  expects, the user can use the \ttt{-h} or \ttt{--help} options with
  the simulation.  For instance, with the \ttt{nlse} simulation, one
  can enter the following command to get a listing of the arguments
  the \xmds simulation expects at its command line:
\begin{xmdsCode}
% nlse --help
\end{xmdsCode}

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <argv>
        <arg>
            <name> nconst </name>
            <type> int </type>
            <default_value> 2 </default_value>
        </arg>
    </argv>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% type (arg)
\subsection{type (arg)}
\label{lab:type(arg)}
\index{type (arg)@\xmdsTag{type} (arg)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{type(arg)}{type}
\xmdsOption{char *} \xmdsTag{/type} \xmdsOneTwo

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{arg}{arg}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{argv} \textarrow \xmdsTag{arg} \textarrow \xmdsTag{type}

\item[Description:] The type of the command line argument, e.g. int,
  double, char *.  At present this mechanism cannot handle complex
  inputs.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <argv>
        <arg>
            <name> nconst </name>
            <type> int </type>
            <default_value> 2 </default_value>
        </arg>
    </argv>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% default_value (arg)
\subsection{default\_value}
\label{lab:default_value}
\index{default_value@\xmdsTag{default\_value}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{default_value}{default\_value}
\xmdsOption{char *} \xmdsTag{/default\_value} \xmdsOneTwo

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{arg}{arg}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{argv} \textarrow \xmdsTag{arg} \textarrow \xmdsTag{default\_value}

\item[Description:] The default value of the command line argument.
  Values will be converted from the string entered into the type
  given in the \xmdsTag{type} tag.  If the variable is not specified
  at the command line then this is the value used by the simulation.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <argv>
        <arg>
            <name> nconst </name>
            <type> int </type>
            <default_value> 2 </default_value>
        </arg>
    </argv>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% field
\section{field}
\label{lab:field}
\index{field@\xmdsTag{field}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{field}{field}
\xmdsOption{xmds tags} \xmdsTag{/field}

\item[Contains:] \xmdsTagLink{name(field)}{name}, 
\xmdsTagLink{dimensions}{dimensions}, 
\xmdsTagLink{lattice(field)}{lattice}, 
\xmdsTagLink{domains}{domains}, 
\xmdsTagLink{samples(field)}{samples},
\xmdsTagLink{vector}{vector}

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{globals} \textarrow \xmdsTag{field}

\item[Description:] Container element to hold the tags describing the
  field to be integrated.  At present, only one field is permitted in
  a simulation.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <!-- xmds tags -->
    </field>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% name (field)
\subsection{name (field)}
\label{lab:name(field)}
\index{name (field)@\xmdsTag{name} (field)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{name(field)}{name}
\xmdsOption{string} \xmdsTag{/name}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{name}

\item[Description:] The name of the field to integrate.  Defaults to
  \ttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <name> main </name>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% dimensions
\subsection{dimensions}
\label{lab:dimensions}
\index{dimensions@\xmdsTag{dimensions}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{dimensions}{dimensions}
\xmdsOption{string} \textsf{variableName} \xmdsOption{string} 
\textsf{variableName} \ldots \xmdsTag{/dimensions}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{dimensions}

\item[Description:] A space delimited array of the names of dimensions
  in the field other than the propagation dimension.  This element is
  therefore a list of the transverse field dimensions.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <dimensions> t </dimensions>
    </field>
<simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% lattice (field)
\subsection{lattice (field)}
\label{lab:lattice(field)}
\index{lattice (field)@\xmdsTag{lattice} (field)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{lattice(field)}{lattice}
\xmdsOption{int} \xmdsOption{int} \ldots
\xmdsTag{/lattice}\\
(\reqd if \xmdsTag{dimensions} assignment present)

\item[Contains:] array of integers

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{lattice}

\item[Description:] A space delimited array of integers giving the
  number of points in the grid for each dimension listed in the
  \xmdsTag{dimensions} tag.

\item[Exmaple:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <lattice> 100 </lattice>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% domains
\subsection{domains}
\label{lab:domains}
\index{domains@\xmdsTag{domains}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{domains}{domains}
\xmdsOption{(double, double)} 
\xmdsOption{(double, double)} \ldots \xmdsTag{/domains}\\
(\reqd if \xmdsTag{dimensions} assignment present)

\item[Contains:] array of ordered pairs of doubles

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{domains}

\item[Description:] This tag specifies the domain range of each
  dimension listed in the \xmdsTag{dimensions} tag.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <domains> (-5, 5) </domains>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% samples (field)
\subsection{samples (field)}
\label{lab:samples(field)}
\index{samples (field)@\xmdsTag{samples} (field)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{samples(field)}{samples}
\xmdsOption{int} \xmdsOption{int} \ldots
\xmdsTag{/samples}

\item[Contains:] array of integers, specifically either \ttt{1} or
  \ttt{0}

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{samples}

\item[Description:] Tells \xmds which moment groups to sample.  This
  tag should contain a space separated list of \ttt{1}'s and
  \ttt{0}'s.  A \ttt{1} meaning sample the moment group in question,
  and a \ttt{0} meaning do not.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <samples> 1 </samples>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vector
\subsection{vector}
\label{lab:vector}
\index{vector@\xmdsTag{vector}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vector}{vector}
\xmdsOption{xmds tags} \xmdsTag{/vector}

\item[Contains:] \xmdsTagLink{name(vector)}{name}, 
\xmdsTagLink{filename(vector)}{filename},
\xmdsTagLink{type(vector)}{type}, 
\xmdsTagLink{components}{components}, 
\xmdsTagLink{fourier_space(vector)}{fourier\_space},
\xmdsTagLink{vectors(vector)}{vectors},
\CDATA

\item[Subelement of:] \xmdsTagLink{field}{field}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector}

\item[Description:] A container for tags describing a vector of the
  field.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <!-- xmds tags -->
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% name (vector)
\subsubsection{name (vector)}
\label{lab:name(vector)}
\index{name (vector)@\xmdsTag{name} (vector)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{name(vector)}{name}
\xmdsOption{string} \xmdsTag{/name}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{name}

\item[Description:] Name of the vector in question.  At least one
  vector must be present, and at least one vector must be called
  \ttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <name> main </name>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% filename (vector)
\subsubsection{filename (vector)}
\label{lab:filename(vector)}
\index{filename (vector)@\xmdsTag{filename} (vector)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{filename(vector)}{filename}
\xmdsOption{string} \xmdsTag{/filename}

\item[Contains:] string

\item[Attributes:] \optl \ttt{format="ascii"|"binary"|"xsil"}
\item[Attributes for the XSIL format:] 
\optl \ttt{moment\_group="N"} \\
\optl \ttt{geometry\_matching\_mode="strict"|"loose"}

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{filename}

\item[Description:] Tells \xmds the file from which to load the
  initial field.

  The \xmdsTag{filename} tag accepts one optional attribute:
  \ttt{format}.  This attribute can take one of three options;
  \ttt{"ascii"}, \ttt{"binary"}, or \ttt{"xsil"} where \ttt{"ascii"} is the
  default option. However, \ttt{"xsil"} is the most robust of these formats
  as it can load any binary XSIL file produced by XMDS (irrespective of what
  architecture the file was produced on). See \Chap{chap:extraAndAdvancedFeatures}, \Sec{subsec:InitialisationFromXSILFile} for more information on loading XSIL files.

  Caution should be taken here when using the \ttt{"binary"} format
  since loading a binary file is more
  difficult to get correct than loading an ascii file.  However, the
  added difficulty is offset by being able to have smaller and more
  complex input data.  A first thing to note is that the byte ordering
  of the system you are going to be loading the file into has to be
  the same as the file itself.  For instance, creating a binary file
  for input to \xmds on PowerPC \tbf{will not} load correctly on an
  x86 platform.

  For the \ttt{"binary"} and \ttt{"ascii"} formats, \xmds expects the input data
  to be essentially interlaced so that it
  is loaded into memory correctly. The best way to explain this is
  by way of example.  If the input data is to be three vectors, say
  \ttt{x}, \ttt{y} and \ttt{z}, then \xmds expects the data to be
  formed thus:
\begin{alltt}
x[0] y[0] z[0] x[1] y[1] z[1] \ldots
\end{alltt}
  and so on with a new line or space between each entry.  The only difference between the ascii and binary input
  formats is that the newline (or space) character is unnecessary, and \xmds just
  expects a sequence of \tbf{double} values ordered as above.

For complex types, \xmds expects the imaginary part of each variable to follow the real part. If the input data for the previous example were complex numbers, then \xmds would expect the data to be in the order:
\begin{alltt}
real(x[0]) imag(x[0]) real(y[0]) imag(y[0]) real(z[0]) imag(z[0]) \ldots
\end{alltt}

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <filename format="binary"> blah </filename>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% type
\subsubsection{type (vector)}
\label{lab:type(vector)}
\index{type (vector)@\xmdsTag{type} (vector)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{type(vector)}{type}
\xmdsOption{string} of \textsf{complex} or \textsf{double} \xmdsTag{/type}

\item[Contains:] string interpreted as either \tbf{complex} or
  \tbf{double} type

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{type}

\item[Description:] The data type of the vector.  Defaults to
  \tbf{complex} if not specified.  It is a good idea to use
  \tbf{complex} here when one is using a Fourier transform technique to
  integrate the equations, even if initially the variables are
  \tbf{double}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <type> complex </type>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% components
\subsubsection{components}
\label{lab:components}
\index{components@\xmdsTag{components}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{components}{components}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/components}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{components}

\item[Description:] Names the components of the vector.  If a large array of components are required, it is possible to declare that here by putting the size of the array in parentheses immediately after the name.  Subsequent references to these components must have the index afterwards in parentheses.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <components> phi JoeIsGreat(256) </components>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% fourier_space (vector)
\subsubsection{fourier\_space (vector)}
\label{lab:fourier_space(vector)}
\index{fourier_space (vector)@\xmdsTag{fourier\_space} (vector)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{fourier_space(vector)}{fourier\_space}
\xmdsOption{bool} \xmdsOption{bool} \ldots 
\xmdsTag{/fourier\_space}\\
(\reqd if \xmdsTag{filename} not present)

\item[Contains:] array of booleans

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{fourier\_space}

\item[Description:] Tells \xmds whether the dimension specified is
  initialised in Fourier space.  This is a space separated list of
  \ttt{yes}/\ttt{no} values.  A value of \ttt{yes} meaning the
  dimension is defined in Fourier space, and \ttt{no} meaning the
  dimension is defined in $x$-space.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <fourier_space> no </fourier_space>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (vector)
\subsubsection{vectors (vector)}
\label{lab:vectors(vector)}
\index{vectors (vector)@\xmdsTag{vectors} (vector)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vectors(vector)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{vector}{vector}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{field} \textarrow \xmdsTag{vector} \textarrow 
\xmdsTag{vectors}

\item[Description:] Tells \xmds the names of the variables are to be
  referenced in a \CDATA block.  Defaults to \texttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <field>
        <vector>
            <vectors> main vc1 </vectors>
        </vector>
    </field>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% sequence
\section{sequence}
\label{lab:sequence}
\index{sequence@\xmdsTag{sequence}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{sequence}{sequence}
\xmdsOption{xmds tags} \xmdsTag{/sequence}

\item[Contains:] \xmdsTagLink{integrate}{integrate}, 
\xmdsTagLink{filter}{filter}, 
\xmdsTagLink{sequence}{sequence}

\item[Subelement of:] \xmdsTagLink{simulation}{simulation} or 
\xmdsTagLink{sequence}{sequence}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} (\textarrow \xmdsTag{sequence})

\item[Description:] Container tag for the sequence of integrations to
  perform.  May contain other sequences within itself.  If
  subsequences exist, then they must contain a \xmdsTag{cycles}
  assignment.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <!-- xmds tags -->
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% cycles
\subsection{cycles}
\label{lab:cycles}
\index{cycles@\xmdsTag{cycles}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{cycles}{cycles}
\xmdsOption{int} \xmdsTag{/cycles}\\
(\reqd in nested \xmdsTag{sequence}s) 

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{sequence}{sequence}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{cycles}

\item[Description:] The number of times to perform a given sequence
  (as a subsequence of the main sequence).  Defaults to \ttt{1}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <cycles> 3 </cycles>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% integrate
\subsection{integrate}
\label{lab:integrate}
\index{integrate@\xmdsTag{integrate}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{integrate}{integrate}
\xmdsOption{xmds tags} \xmdsTag{/integrate}

\item[Contains:]
\xmdsTagLink{algorithm}{algorithm},
\xmdsTagLink{interval}{interval},
\xmdsTagLink{iterations}{iterations},
\xmdsTagLink{tolerance}{tolerance},
\xmdsTagLink{max_iterations}{max\_iterations},
\xmdsTagLink{smallmemory}{smallmemory},
\xmdsTagLink{cutoff}{cutoff},
\xmdsTagLink{halt_non_finite}{halt\_non\_finite},
\xmdsTagLink{lattice(integrate)}{lattice},
\xmdsTagLink{samples(integrate)}{samples},
\xmdsTagLink{k_operators}{k\_operators},
\xmdsTagLink{moment_group(integrate)}{moment\_group},
\xmdsTagLink{functions(integrate)}{functions},
\xmdsTagLink{vectors(integrate)}{vectors},
\CDATA

\item[Subelement of:] \xmdsTagLink{sequence}{sequence}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate}

\item[Description:] Container element holding the tags that describe
  how the integration should take place.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <!-- xmds tags -->
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% algorithm
\subsubsection{algorithm}
\label{lab:algorithm}
\index{algorithm@\xmdsTag{algorithm}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{algorithm}{algorithm}
\xmdsOption{string} \textsf{algorithmName} \xmdsTag{/algorithm}

\item[Contains:] string, one of \ttt{RK4EX}, \ttt{RK4IP}, \ttt{ARK45EX}, \ttt{ARK45IP}, \ttt{SIEX},
  or \ttt{SIIP}

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{algorithm}

\item[Description:] The algorithm to use when integrating the
  equations.  Defaults to \ttt{SIEX} if \xmdsTag{stochastic} is
  \texttt{yes} or \ttt{RK4EX} if \xmdsTag{stochastic} is \texttt{no}.
  The six algorithms that \xmds currently contains are:
  \begin{description}
  \item[\ttt{RK4EX}] Fourth-order Runge-Kutta in the explicit
    picture.
  \item[\ttt{RK4IP}] Fourth-order Runge-Kutta in the interaction
    picture.
   \item[\ttt{ARK45EX}] adaptive step size Runge-Kutta-Fehlberg in the explicit
    picture.
  \item[\ttt{ARK45IP}] adaptive step size Runge-Kutta-Fehlberg in the interaction
    picture.
  \item[\ttt{SIEX}] Semi-implicit method in the explicit picture.
  \item[\ttt{SIIP}] Semi-implicit method in the interaction picture.
  \end{description}

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <algorithm> RK4IP </algorithm>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% interval
\subsubsection{interval}
\label{lab:interval}
\index{interval@\xmdsTag{interval}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{interval}{interval}
\xmdsOption{double} \xmdsTag{/interval}

\item[Contains:] double

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{interval}

\item[Description:] The integration range.  This is the interval over
  which the main propagation dimension will be integrated.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <interval> 20 </interval>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% iterations
\subsubsection{iterations}
\label{lab:iterations}
\index{iterations@\xmdsTag{iterations}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{iterations}{iterations}
\xmdsOption{int} \xmdsTag{/iterations}

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{iterations}

\item[Description:] When using one of the semi-implicit algorithms
  this option can be altered to control the number of iterations of the
  algorithm to for convergence of the method.  Defaults to \ttt{3}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <iterations> 5 </iterations>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%%% tolerance
\subsubsection{tolerance}
\label{lab:tolerance}
\index{tolerance@\xmdsTag{tolerance}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{tolerance}{tolerance}
\xmdsOption{double} \xmdsTag{/tolerance}

\item[Contains:] double

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{tolerance}

\item[Description:] If one of the adaptive step size methods is used, this assignment controls the maximum \emph{relative} error that is allowed per step on any of the grid points.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <tolerance>1e-10</tolerance>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%%

%%%% max_iterations
\subsubsection{max\_iterations}
\label{lab:max_iterations}
\index{max_iterations@\xmdsTag{max\_iterations}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{max_iterations}{max\_iterations}
\xmdsOption{int} \xmdsTag{/max\_iterations}

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{max\_iterations}

\item[Description:] Applies to the ARK45 algorithms only. If the behaviour of the solution is unknown and might result in a very small step size the maximum number of iterations (steps and discarded steps) can be limited with this optional tag. This is particularly useful in the debugging stage or on systems that impose time limits on their running programs.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <max_iterations>5000000</max_iterations>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%%

%%% min_time_step
\subsubsection{min\_time\_step}
\label{lab:min_time_step}
\index{min_time_step@\xmdsTag{min\_time\_step}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{iterations}{min\_time\_step}
\xmdsOption{double} \xmdsTag{/min\_time\_step}

\item[Contains:] double

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow
\xmdsTag{min\_time\_step}

\item[Description:]
The minimum time-step an integration algorithm should try,
before halting that pass of the integration.
This option applies to the adaptive algorithms (ARK45 and ARK89) only.

The default value is \texttt{1e-13},
that is, $10^{-13}$.
A value of \texttt{0} disables the check on the time-step,
which will slightly speed up integrations that do not require the check.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <min_time_step>1e-10</min_time_step>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%%

%%%% smallmemory
\subsubsection{smallmemory}
\label{lab: smallmemory}
\index{smallmemory@\xmdsTag{smallmemory}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{smallmemory}{smallmemory}
\xmdsOption{bool} \xmdsTag{/smallmemory}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{smallmemory}

\item[Description:] Defaults to \ttt{no}. In this case, when using the ARK45IP algorithm \xmds calculates and stores six copies of the derivative operators per step as each of them can be reused once. For problems with memory limitations it might be better to assign \ttt{yes} to this element, then each array of derivatives needs to be calculated twice per step, but significantly less memory should be used.
\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <smallmemory> yes </smallmemory>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%%

%%%% cutoff
\subsubsection{cutoff}
\label{lab: cutoff}
\index{iterations@\xmdsTag{cutoff}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{cutoff}{cutoff}
\xmdsOption{double} \xmdsTag{/cutoff}

\item[Contains:] double

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{cutoff}

\item[Description:] If one of the adaptive step size methods is used, the \ttt{cutoff} value sets the threshold for the function values that are included in the determination of relative errors. Grid points where the function is less than \ttt{cutoff}*peakvalue are not included.
The value defaults to 1/1000;

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <cutoff> 1e-5 </cutoff>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%%

%%% halt_non_finite

\subsubsection{halt\_non\_finite}
\label{lab:halt_non_finite}
\index{halt_non_finite@\xmdsTag{halt\_non\_finite}}
\begin{xmdsDoc}

\item \optl \xmdsTagTarg{halt_non_finite}{halt\_non\_finite}
\xmdsOption{bool} \xmdsTag{/halt\_non\_finite}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow
\xmdsTag{halt\_non\_finite}

\item[Description:]
If \texttt{yes}, then halt the current integration pass
if it produces a non-finite number
in the first component of the main vector.
Since non-finite numbers usually propogate quickly
through the components of the main vector,
this will quickly detect any non-finite number.

Examples of non-finite numbers
are \texttt{1.0/0.0}, which is infinite,
and \texttt{0.0/0.0}, which is not a number (NaN).
Some platforms process non-finite numbers slower than finite numbers;
others process them faster.
Regardless, they are unlikely to be useful results from an integration.

Note that, by default,
\xmds compiles the generated C++ code with optimizations
that sacrifice strict compliance with floating-point arithmetic standards
(e.g. IEEE 754).

Many of these optimizations assume that all floating-point numbers are finite.
Naturally, this may pose problems for a non-finite number check.
In some cases, the check for non-finite numbers is optimized to oblivion.
Depending on other optimizations, the time-step may become NaN
and the integration will never move forward
and therefore never terminate.

An easy way to see if the check for non-finite numbers
survived optimization is to run the following
(supposing \xmds compiled the \ttt{simulation} binary
from \ttt{simulation.xmds}):
\begin{quote}
\begin{verbatim}
strings simulation | grep halt_non_finite:
\end{verbatim}
\end{quote}
(The colon is important.)
If this command prints output similar to the following:
\begin{quote}
\begin{verbatim}
* NOTICE: halt_non_finite: Integration halted.
\end{verbatim}
\end{quote}
then at least the check is not optimized away
and \ttt{halt\_non\_finite} is more likely to work.

When using GCC \xmds enables the \texttt{-ffast-math} flag.
In GCC version 3.3, this seems to pose problems with \ttt{halt\_non\_finite}.
Removing the \texttt{-ffast-math} flag should solve the problem.
Alternatively, keeping this flag
and adding the \texttt{-fno-unsafe-math-optimizations} flag
\textit{after} the \texttt{-ffast-math} flag seems to work
(and should produce faster code).
GCC~4 seems to have no problem.

There seems to be no problem using version 10.1 of Intel's compiler \ttt{icc}.
Note that \ttt{icc} sacrifices floating-point compliance for speed by default,
but this can be changed using the \ttt{-fp-model} flag.

Remember you can change compilation flags by editing the preference file
(see section \ref{sec:preferences} for more information on preferences).
Of course, you can also edit the compilation command printed by \xmds
and run it by hand.

Overall, however, there are no guarantees that \ttt{halt\_non\_finite}
will work when sacrificing accuracy for speed in floating-point arithmetic.

Defaults to \texttt{no}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <halt_non_finite> yes </halt_non_finite>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}

%%% lattice (integrate)
\subsubsection{lattice (integrate)}
\label{lab:lattice(integrate)}
\index{lattice (integrate)@\xmdsTag{lattice} (integrate)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{lattice(integrate)}{lattice}
\xmdsOption{int} \xmdsTag{/lattice}

\item[Contains:] integer

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{lattice}

\item[Description:] The number of points to use over the integration
  interval i.e.~over the number entered in the \xmdsTag{interval}
  assignment.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <lattice> 1000 </lattice>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% samples (integrate)
\subsubsection{samples (integrate)}
\label{lab:samples(integrate)}
\index{samples (integrate)@\xmdsTag{samples} (integrate)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{samples(integrate)}{samples}
\xmdsOption{int} \xmdsOption{int} \ldots
\xmdsTag{/samples}

\item[Contains:] array of integers

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{samples}

\item[Description:] The number of samples to take of each output
  moment group.  This is a space separated list of integers, the
  number of which must be equal to the number of output moment
  groups.  Each integer must be a factor of the \xmdsTag{lattice}
  assignment or \ttt{0}.  If set to \ttt{0} then the given moment
  group is not sampled.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <samples> 50 </samples>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% k_operators
\subsubsection{k\_operators}
\label{lab:k_operators}
\index{k_operators@\xmdsTag{k\_operators}}
\begin{xmdsDoc}
\item \optl
\xmdsTagTarg{k_operators}{k\_operators}
\xmdsOption{xmds tags} \xmdsTag{/k\_operators}

\item[Contains:]
  \xmdsTagLink{vectors(k_operators)}{vectors},
  \xmdsTagLink{constant}{constant},
  \xmdsTagLink{operator_names}{operator\_names}, 
  \CDATA

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{k\_operators}

\item[Description:] Container for tags describing the $k$-space
  (i.e.~Fourier space) operators.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <k_operators>
                <!-- xmds tags -->
            </k_operators>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (k_operators)
\paragraph{vectors (k\_operators)}
\label{lab:vectors(k_operators)}
\index{vectors (k_operators)@\xmdsTag{vectors} (k\_operators)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{vectors(k_operators)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{k_operators}{k\_operators}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow
\xmdsTag{k\_operators} \textarrow \xmdsTag{vectors}

\item[Description:] Vectors to be referred to in \CDATA block.
  Defaults to \texttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <k_operators>
                <vectors> main vc1 </vectors>
            </k_operators>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% constant
\paragraph{constant}
\label{lab:constant}
\index{constant@\xmdsTag{constant}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{constant}{constant}
\xmdsOption{bool} \xmdsTag{/constant}

\item[Contains:] boolean

\item[Subelement of:] \xmdsTagLink{k_operators}{k\_operators}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{k\_operators} \textarrow \xmdsTag{constant}

\item[Description:] Tells \xmds whether or not the $k$-space operators
  are constant over the course of the simulation, in other words, they
  don't depend upon the propagation dimension.  If they are constant,
  then giving a value of \ttt{yes} for this tag speeds up the
  simulation as more efficient code can be used.  Defaults to \texttt{no}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <k_operators>
                <constant> yes </constant>
            </k_operators>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% operator_names
\paragraph{operator\_names}
\label{lab:operator_names}
\index{operator_names@\xmdsTag{operator\_names}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{operator_names}{operator\_names}
\xmdsOption{string} \textsf{variableName}
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/operator\_names}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{k_operators}{k\_operators}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{k\_operators} \textarrow \xmdsTag{operator\_names}

\item[Description:] The names of the $k$-space operators as they
  appear in the \CDATA block within the \xmdsTag{k\_operators}
  element.  This is a space separated list of strings of the operator
  names.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <k_operators>
                <operator_names> L </operator_names>
            </k_operators>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% moment_group (integrate)
\subsubsection{moment\_group (integrate)}
\label{lab: moment_group(integrate)}
\index{moment_group (integrate)@\xmdsTag{moment\_group} (integrate)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{moment_group(integrate)}{moment\_group}
\xmdsOption{xmds tags} \xmdsTag{/moment\_group}

\item[Contains:] \xmdsTagLink{moments}{moments},
  \xmdsTagLink{integrate_dimension}{integrate\_dimension}, 
  \CDATA

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{moment\_group}

\item[Description:] Defines and calculates a number or vector integrated through zero or more of the transverse dimensions of the problem. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
  <sequence>
      <integrate>
         <moment_group>
            <moments>joe is great</moments>
            <integrate_dimension>no yes</integrate_dimension>
	  <![CDATA[
		joe += ~psi*psi;
		is += ~phi*phi;
		great += theta;   
		]]>
        </moment_group>      
      </integrate>
   </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% functions (integrate)
\subsubsection{functions (integrate)}
\label{lab: functions(integrate)}
\index{functions (integrate)@\xmdsTag{functions} (integrate)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{functions(integrate)}{functions}
\CDATA \xmdsTag{/functions}

\item[Contains:] \CDATA

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{functions}

\item[Description:] This is the best place to define any functions that do not depend on the transverse dimensions. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <functions> 
	     <![CDATA[
		/* Some C code */
               ]]>  
            </functions >
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (integrate)
\subsubsection{vectors (integrate)}
\label{lab:vectors(integrate)}
\index{vectors (integrate)@\xmdsTag{vectors} (integrate)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vectors(integrate)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{vectors}

\item[Description:] The vectors \xmds needs to access in the
  equations.  Given as a space separated list of strings.  Defaults to
  \texttt{main}. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <vectors> main vc1 </vectors>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% filter
\subsection{filter}
\label{lab:filter}
\index{filter@\xmdsTag{filter}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{filter}{filter}
\xmdsOption{xmds tags} \xmdsTag{/filter}

\item[Contains:] \xmdsTagLink{vectors(filter)}{vectors}, 
\xmdsTagLink{fourier_space(filter)}{fourier\_space},
\CDATA

\item[Subelement of:] \xmdsTagLink{sequence}{sequence}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{filter}

\item[Description:] Container element for the tags describing how the
  field is to be filtered, if at all.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <filter>
            <!-- xmds tags -->
        </filter>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% moment_group (filter)
\subsubsection{moment\_group (filter)}
\label{lab: moment_group(filter)}
\index{moment_group (filter)@\xmdsTag{moment\_group} (filter)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{moment_group(filter)}{moment\_group}
\xmdsOption{xmds tags} \xmdsTag{/moment\_group}

\item[Contains:] \xmdsTagLink{moments}{moments},
  \xmdsTagLink{integrate_dimension}{integrate\_dimension}, 
  \CDATA

\item[Subelement of:] \xmdsTagLink{filter}{filter}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{filter} \textarrow 
\xmdsTag{moment\_group}

\item[Description:] Defines and calculates a number or vector integrated through zero or more of the transverse dimensions of the problem. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
  <sequence>
      <filter>
         <moment_group>
            <moments>joe is great</moments>
            <integrate_dimension>no yes</integrate_dimension>
	  <![CDATA[
		joe += ~psi*psi;
		is += ~phi*phi;
		great += theta;   
		]]>
        </moment_group>      
      </filter>
   </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% functions (filter)
\subsubsection{functions (filter)}
\label{lab: functions(filter)}
\index{functions (filter)@\xmdsTag{functions} (filter)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{functions(filter)}{functions}
\CDATA \xmdsTag{/functions}

\item[Contains:] \CDATA

\item[Subelement of:] \xmdsTagLink{filter}{filter}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{filter} \textarrow 
\xmdsTag{functions}

\item[Description:] This is the best place to define any functions that do not depend on the transverse dimensions. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <filter>
            <functions> 
	     <![CDATA[
		/* Some C code */
               ]]>  
            </functions >
        </filter>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (filter)
\subsubsection{vectors (filter)}
\label{lab:vectors(filter)}
\index{vectors (filter)@\xmdsTag{vectors} (filter)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vectors(filter)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{filter}{filter}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{filter} \textarrow 
\xmdsTag{vectors}

\item[Description:] The names of the vectors \xmds should apply the
  filter to.  Given as a space separated list of strings.  Defaults to
  \texttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
        <filter>
            <vectors> main vc1 </vectors>
        </filter>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% fourier_space (filter)
\subsubsection{fourier\_space (filter)}
\label{lab:fourier_space(filter)}
\index{fourier_space (filter)@\xmdsTag{fourier\_space} (filter)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{fourier_space(filter)}{fourier\_space}
\xmdsOption{boolean} \xmdsOption{boolean} \ldots
\xmdsTag{/fourier\_space}

\item[Contains:] array of booleans

\item[Subelement of:] \xmdsTagLink{filter}{filter}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{integrate} \textarrow \xmdsTag{filter} \textarrow 
\xmdsTag{fourier\_space}

\item[Description:] Tells \xmds in which space the filter is to be
  applied.  This is a list of \ttt{yes}/\ttt{no} options for each
  vector.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <integrate>
        <filter>
            <fourier_space> yes no </fourier_space>
        </filter>
    </integrate>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% cross_propagation
\subsubsection{cross\_propagation}
\label{lab:cross_propagation}
\index{cross_propagation@\xmdsTag{cross\_propagation}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{cross_propagation}{cross\_propagation}
\xmdsOption{xmds tags} \xmdsTag{/cross\_propagation}

\item[Contains:] \xmdsTagLink{vectors(cross_propagation)}{vectors}, 
\xmdsTagLink{prop_dim(cross_propagation)}{prop\_dim},
\CDATA

\item[Subelement of:] \xmdsTagLink{integrate}{integrate}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{integrate} \textarrow \xmdsTag{cross\_propagation}

\item[Description:] Container of the tags describing the cross
  propagation vectors, if any.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <integrate>
        <cross_propagation>
            <!-- xmds tags -->
        </cross_propagation>
    </integrate>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% prop_dim
\paragraph{prop\_dim (cross\_propagation)}
\label{lab:prop_dim(cross_propagation)}
\index{prop_dim (cross_propagation)@\xmdsTag{prop\_dim} (cross\_propagation)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{prop_dim(cross_propagation)}{prop\_dim}
\xmdsOption{string} \xmdsTag{/prop\_dim}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{cross_propagation}{cross\_propagation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{integrate} \textarrow \xmdsTag{cross\_propagation} 
\textarrow \xmdsTag{prop\_dim}

\item[Description:] The propagation dimension of the cross propagating
  vector.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <integrate>
        <cross_propagation>
            <prop_dim> z </prop_dim>
        </cross_propagation>
    </integrate>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (cross_propagation)
\paragraph{vectors (cross\_propagation)}
\label{lab:vectors(cross_propagation)}
\index{vectors (cross_propagation)@\xmdsTag{vectors} (cross\_propagation)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vectors(cross_propagation)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{cross_propagation}{cross\_propagation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{integrate} \textarrow 
\xmdsTag{cross\_propagation} \textarrow \xmdsTag{vectors}

\item[Description:] The names of the cross propagating vectors as a
  list of strings.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <integrate>
            <cross_propagation>
                <vectors> main vc1 </vectors>
            </cross_propagation>
        </integrate>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% breakpoint
\subsection{breakpoint}
\label{breakpoint}
\index{breakpoint@\xmdsTag{breakpoint}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{breakpoint}{breakpoint}
\xmdsOption{xmds tags} \xmdsTag{/breakpoint}

\item[Contains:] \xmdsTagLink{filename(breakpoint)}{filename}, \xmdsTagLink{fourier_space(breakpoint)}{fourier\_space}, \xmdsTagLink{vectors(breakpoint)}{vectors}

\item[Subelement of:] \xmdsTagLink{sequence}{sequence}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{breakpoint}

\item[Description:] Saves some vectors to a binary XSIL file when this element is reached in the simulation. This can be used for generating an XSIL file that can be used as an input for another simulation, or to check the behaviour of the simulation part way through. This feature is described further in \Chap{chap:extraAndAdvancedFeatures}, \Sec{sec:Breakpoints}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <breakpoint>
            <!-- xmds tags -->
        </breakpoint>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% filename (breakpoint)
\subsubsection{filename (breakpoint)}
\label{lab:filename(breakpoint)}
\index{filename (breakpoint)@\xmdsTag{filename} (breakpoint)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{filename(breakpoint)}{filename}
\xmdsOption{string} \xmdsTag{/filename}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{breakpoint}{breakpoint}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{breakpoint} \textarrow 
\xmdsTag{filename}

\item[Description:] Sets the XSIL file to which the breakpoint information should be saved.


\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <breakpoint>
            <filename> blah.xsil </filename>
        </breakpoint>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% fourier_space (breakpoint)
\subsubsection{fourier\_space (breakpoint)}
\label{lab:fourier_space(breakpoint)}
\index{fourier_space (breakpoint)@\xmdsTag{fourier\_space} (breakpoint)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{fourier_space(breakpoint)}{fourier\_space}
\xmdsOption{boolean} \xmdsOption{boolean} \ldots
\xmdsTag{/fourier\_space}

\item[Contains:] array of booleans

\item[Subelement of:] \xmdsTagLink{breakpoint}{breakpoint}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{breakpoint} \textarrow 
\xmdsTag{fourier\_space}

\item[Description:] Tells \xmds in which space the breakpoint is to be
  written in.  This is a list of \ttt{yes}/\ttt{no} options for each
  vector.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <breakpoint>
            <fourier_space> yes no </fourier_space>
        </breakpoint>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (breakpoint)
\subsubsection{vectors (breakpoint)}
\label{lab:vectors(breakpoint)}
\index{vectors (breakpoint)@\xmdsTag{vectors} (breakpoint)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{vectors(breakpoint)}{vectors}
\xmdsOption{string} \textsf{vectorName} 
\xmdsOption{string} \textsf{vectorName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{breakpoint}{breakpoint}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{sequence} \textarrow \xmdsTag{breakpoint} \textarrow \xmdsTag{vectors}

\item[Description:] The names of the vectors that will be saved to the XSIL file.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <sequence>
        <breakpoint>
            <vectors> main vc1 </vectors>
        </breakpoint>
    </sequence>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% output
\section{output}
\label{lab:output}
\index{output@\xmdsTag{output}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{output}{output}
\xmdsOption{xmds tags} \xmdsTag{/output}

\item[Contains:] \xmdsTagLink{filename(output)}{filename}, 
\xmdsTagLink{group}{group}

\item[Attributes:] \optl \ttt{format="ascii|binary"}, 
  \optl \ttt{precision="double|single"}

\item[Subelement of:] \xmdsTagLink{simulation}{simulation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output}

\item[Description:]  Container for elements describing what data
  should be output and how it should be output.  

  Accepts two optional attributes, \ttt{format} and \ttt{precision}.
  The \ttt{format} attribute defines the output format of the data.
  The options available are \ttt{"ascii"} and \ttt{"binary"}, with
  \ttt{"ascii"} being the default option.  The \ttt{precision}
  attribute defines the output data precision.  This can be either
  \ttt{"double"} or \ttt{"single"}, with these options referring to
  double or single precision floating point numbers respectively.  This
  option is only meaningful when \ttt{format} is set to \ttt{"binary"}
  as the precision does not affect the output when \ttt{"ascii"} is
  chosen.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output format="binary" precision="single">
        <!-- xmds tags -->
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% filename (output)
\subsection{filename (output)}
\label{lab:filename(output)}
\index{filename (output)@\xmdsTag{filename} (output)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{filename(output)}{filename}
\xmdsOption{string} \xmdsTag{/filename}

\item[Contains:] string

\item[Subelement of:] \xmdsTagLink{output}{output}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{filename}

\item[Description:] Optional filename for output data.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <filename> nlse.xsil </filename>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% group
\subsection{group}
\label{lab:group}
\index{group@\xmdsTag{group}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{group}{group}
\xmdsOption{xmds tags} \xmdsTag{/group}

\item[Contains:] \xmdsTagLink{sampling}{sampling}, 
\xmdsTagLink{post_propagation}{post\_propagation}

\item[Subelement of:] \xmdsTagLink{output}{output}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group}

\item[Description:]  Container for tags describing the relevant moment
  group.  There must be at least one group element given.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <!-- xmds tags -->
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% sampling
\subsubsection{sampling}
\label{lab:sampling}
\index{sampling@\xmdsTag{sampling}}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{sampling}{sampling}
\xmdsOption{xmds tags} \xmdsTag{/sampling}

\item[Contains:] \xmdsTagLink{vectors(sampling)}{vectors}, 
  \xmdsTagLink{fourier_space(sampling)}{fourier\_space},
  \xmdsTagLink{lattice(sampling)}{lattice},
  \xmdsTagLink{moments(sampling)}{moments},
  \CDATA

\item[Subelement of:] \xmdsTagLink{group}{group}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{sampling}

\item[Description:] Container for tags describing how to sample the
  moment group.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <!-- xmds tags -->
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% type (sampling)
\paragraph{type (sampling)}
\label{lab:type(sampling)}
\index{type (sampling)@\xmdsTag{type} (sampling)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{type(sampling)}{type}
\xmdsOption{string} of \textsf{complex} or \textsf{double} \xmdsTag{/type}

\item[Contains:] string interpreted as either \tbf{complex} or \tbf{double} type

\item[Subelement of:] \xmdsTagLink{sampling}{sampling}

\item[Path to tag:] \xmdsTag{simulation} \textarrow
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow
\xmdsTag{sampling} \textarrow \xmdsTag{type}

\item[Description:] The data type of the output data. Defaults to \tbf{complex}
if the vector that the output data depends on is of type \tbf{complex}, and \tbf{double}
otherwise. Note that a type of \tbf{double} cannot be used with a \xmdsTagLink{post\_propagation}{post\_propagation} tag
as the fourier transforms available to the \xmdsTagLink{post\_propagation}{post\_propagation} tag require the output data
to be of type \tbf{complex}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <type> complex </type>
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% fourier_space (sampling)
\paragraph{fourier\_space (sampling)}
\label{lab:fourier_space(sampling)}
\index{fourier_space (sampling)@\xmdsTag{fourier\_space} (sampling)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{fourier_space(sampling)}{fourier\_space}
\xmdsOption{bool} \xmdsOption{bool} \ldots
\xmdsTag{/fourier\_space}

\item[Contains:] array of booleans

\item[Subelement of:] \xmdsTagLink{sampling}{sampling}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{sampling} \textarrow \xmdsTag{fourier\_space}

\item[Description:] A boolean telling \xmds whether or not to sample
  in Fourier space.  This should be a space separated list of
  booleans, one for each transverse dimension.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <fourier_space> no </fourier_space>
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% vectors (sampling)
\paragraph{vectors (sampling)}
\label{lab:vectors(sampling)}
\index{vectors (sampling)@\xmdsTag{vectors} (sampling)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{vectors(sampling)}{vectors}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/vectors}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{sampling}{sampling}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{sampling} \textarrow \xmdsTag{vectors}

\item[Description:] Space separated list of strings giving the names
  of the vectors to sample.  Defaults to \texttt{main}.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <vectors> main vc1 </vectors>
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% lattice (sampling)
\paragraph{lattice (sampling)}
\label{lab:lattice(sampling)}
\index{lattice (sampling)@\xmdsTag{lattice} (sampling)}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{lattice(sampling)}{lattice}
\xmdsOption{int} \xmdsOption{int} \ldots
\xmdsTag{/lattice}

\item[Contains:] array of integers

\item[Subelement of:] \xmdsTagLink{sampling}{sampling}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{sampling} \textarrow \xmdsTag{lattice}

\item[Description:] A space separated list of integers, each
  describing how many points to sample of each transverse dimension
  (if greater than 1: see below).  One entry must exist for each
  transverse dimension.

  If an entry is set to \ttt{0}, then \xmds integrates the moments
  over this dimension.  this will cause the output field to no longer
  be a function of this transverse dimension.

  If an entry is set to \ttt{1}, then \xmds will sample the moments on
  a cross-sectional slice of this dimension, also causing the output
  field to lose this transverse dimension.  If this dimension is in
  normal space then \xmds will extract the slice at the middle lattice
  point (point number $N/2+1$ using integer division), otherwise \xmds
  will extract the slice at the zero momentum point, $k=0$.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <lattice> 50 </lattice>
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% moments (sampling)
\paragraph{moments (sampling)}
\label{lab:moments(sampling)}
\index{moments (sampling)@\xmdsTag{moments} (sampling)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{moments(sampling)}{moments}
\xmdsOption{string} \textsf{variableName} 
\xmdsOption{string} \textsf{variableName} \ldots
\xmdsTag{/moments}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{sampling}{sampling}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{sampling} \textarrow \xmdsTag{moments}

\item[Description:] A list of strings of the names of the moments to
  sample.  These variables will then be mentioned in the \CDATA block
  following this tag.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <sampling>
                <moments> pow_dens </moments>
            </sampling>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% post_propagation
\subsubsection{post\_propagation}
\label{lab:post_propagation}
\index{post_propagation@\xmdsTag{post\_propagation}}
\begin{xmdsDoc}
\item \optl \xmdsTagTarg{post_propagation}{post\_propagation}
\xmdsOption{xmds tags} \xmdsTag{/post\_propagation}

\item[Contains:]
  \xmdsTagLink{fourier_space(post_propagation)}{fourier\_space},
  \xmdsTagLink{moments(post_propagation)}{moments},
  \CDATA

\item[Subelement of:] \xmdsTagLink{group}{group}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{post\_propagation}

\item[Description:] Container for tags describing any post propagation
  processing of the data that should be done prior to output to file.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <post_propagation>
                <!-- xmds tags -->
            </post_propagation>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% fourier_space (post_propagation)
\paragraph{fourier\_space (post\_propagation)}
\label{lab:fourier_space(post_propagation)}
\index{fourier_space (post_propagation)@\xmdsTag{fourier\_space} (post\_propagation)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{fourier_space(post_propagation)}{fourier\_space}
\xmdsOption{bool} \xmdsOption{bool} \ldots
\xmdsTag{/fourier\_space}

\item[Contains:] array of booleans

\item[Subelement of:] \xmdsTagLink{post_propagation}{post\_propagation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{post\_propagation} \textarrow \xmdsTag{fourier\_space}

\item[Description:] Whether or not the post propagation is performed
  in Fourier space.  This is a list of \ttt{yes}/\ttt{no} entries for
  the propagation dimension and as many \emph{remaining} transverse
  dimensions. 

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <post_propagation>
                <fourier_space> no </fourier_space>
            </post_propagation>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%

%%% moments (post_propagation)
\paragraph{moments (post\_propagation)}
\label{lab:moments(post_propagation)}
\index{moments (post_propagation)@\xmdsTag{moments} (post\_propagation)}
\begin{xmdsDoc}
\item \reqd \xmdsTagTarg{moments(post_propagation)}{moments}
\xmdsOption{string} \textsf{variableName} \xmdsOption{string}
\tsf{variableName} \ldots \xmdsTag{/moments}

\item[Contains:] array of strings

\item[Subelement of:] \xmdsTagLink{post_propagation}{post\_propagation}

\item[Path to tag:] \xmdsTag{simulation} \textarrow 
\xmdsTag{output} \textarrow \xmdsTag{group} \textarrow 
\xmdsTag{post\_propagation} \textarrow \xmdsTag{moments}

\item[Description:] The names of the moments (with different names to
  the moments defined directly within the group element) to be derived
  from the post processing.

\item[Example:] \forcenewline
\begin{xmdsCode}
<simulation>
    <output>
        <group>
            <post_propagation>
                <moments> pow_dens </moments>
            </post_propagation>
        </group>
    </output>
</simulation>
\end{xmdsCode}
\end{xmdsDoc}
%%%