% Thorn documentation template
\documentclass{article}

\begin{document}
\title{SampleIO}
\author{Thomas Radke}
\date{$ $Date$ $}
\maketitle

\abstract{
Thorn {\bf SampleIO} serves as an example for creating your own I/O thorns.
Its code is clearly structured and well documented, and implements a very
simple and light-weight but fully functioning Cactus I/O method.\\
Together with the documentation about I/O methods in the {\it Cactus Users'
Guide} and the chapter about thorn {\bf IOUtil} in the {\it Cactus Thorn Guide}
you should be able to use this code and modify/extend it according to your
needs.
}

\section{Purpose}
Thorn {\bf SampleIO} registers the I/O method {\tt SampleIO} with the Cactus
flesh I/O interface. This method prints the data values of
three-dimensional, distributed Cactus grid functions/arrays at a chosen
location to screen.

The implemented I/O method makes use of the Cactus Hyperslabbing API to obtain
the data values to print.

\section{{\bf SampleIO} Parameters}
Parameters to control the {\tt SampleIO} I/O method are:

\begin{itemize}
  \item{\tt SampleIO::out\_vars}\\
    This parameter denotes the variables to output as a space-separated list
    of full variable and/or group names.
  \item{\tt SampleIO::point\_x, SampleIO::point\_y, SampleIO::point\_z}\\
    The location of the data point to output for all variables is given in
    index coordinates (starting from 0) on a three-dimensional computational
    grid.
  \item{\tt SampleIO::out\_every}\\
    This parameter sets the frequency for periodic output.
    A positive value means to output every so many iterations. A negative value
    chooses the value of the general {\tt IO::out\_every} integer parameter to
    be taken.  A value of zero disables {\tt SampleIO} periodic output.\\
    The value for {\tt out\_every} is used for all variables by default.
    This can be overwritten for individual variables by appending an option
    string to the variable name, like in
    \center{\tt SampleIO::out\_vars = "MyThorn::MyVar[out\_every=2]"}.
\end{itemize}

All parameters are steerable, ie. they can be changed at runtime.\\
The code in thorn {\bf SampleIO} includes the logic to check whether a parameter
has been changed since the last output, and how to re-evaluate the I/O
parameters.

\section{Notes}
Like any other I/O thorn should do, {\bf SampleIO} inherits general I/O
parameters from thorn {\bf IOUtil}. Therefore this I/O helper thorn must be
included in the {\tt ThornList} of a Cactus configuration in order to compile
thorn {\bf SampleIO}, and also activated at runtime in the {\tt ActiveThorns}
parameter in your parameter file.

\end{document}
