% Thorn documentation template
\documentclass{article}
\begin{document}

\title{IOStreamedHDF5}
\author{Thomas Radke}
\date{2000\\$ $Revision$ $Date$ $}
\maketitle

\abstract{
Thorn {\bf IOStreamedHDF5} provides an I/O method to stream variables in HDF5
file format via live sockets to any connected clients.
It also implements checkpointing/recovery functionality using HDF5.
}
%
%
\section{Building A Cactus Configuration with {\bf IOStreamedHDF5}}
%
The Cactus distribution does not contain the HDF5 header files and library which
is used by thorn {\bf IOStreamedHDF5}. So you need to configure it as an external
software package via:
%
\begin{verbatim}
  make <configuration>-config HDF5=yes
                             [HDF5_DIR=<path to HDF5 package>]
\end{verbatim}
%
The configuration script will look in some default places for an installed
HDF5 package. If nothing is found this way you can explicitly specify it with
the {\tt HDF5\_DIR} configure variable.

Thorn {\bf IOStreamedHDF5} uses the {\tt Stream Virtual File Driver} of the
HDF5 library as its low-level driver. Note that this driver is not built into
an HDF5 configuration by default. The configure script of {\bf IOStreamedHDF5} will warn you if your HDF5 configuration doesn't contain this driver and stop
the configuration process. Building an HDF5 library with {\tt Stream} driver
is very easy: just configure it with the {\tt --enable-stream-vfd} option
and build/install as usual.\\

Thorn {\bf IOStreamedHDF5} inherits from {\bf IOUtil} and {\bf IOHDF5Util}
so you need to include these thorns in your thorn list to build a configuration
with {\bf IOStreamedHDF5}.
%
%
\section{Getting HDF5 Streaming Output}
%
Thorn {\bf IOStreamedHDF5} uses the standard I/O library HDF5 (Hierarchical Data Format
version 5, see {\tt http://hdf.ncsa.uiuc.edu/whatishdf5.html} for details)
to output any type of CCTK grid variables (grid scalars, grid functions, and
grid arrays of arbitrary dimension) in the HDF5 file format.\\

Output is done by invoking the {\tt IOStreamedHDF5} I/O method which thorn
{\bf IOStreamedHDF5} registers with the flesh's I/O interface at startup.\\

You obtain output by either
\begin{itemize}
  \item setting the appropriate I/O parameters in your parameter files, eg.
\begin{verbatim}
  IOStreamedHDF5::out_every = 10
  IOStreamedHDF5::out_vars  = "wavetoy::phi"
\end{verbatim}
  \item calling one the flesh's I/O interface routines in your thorn's
        code, eg.
\begin{verbatim}
  CCTK_OutputVarByMethod (cctkGH, "wavetoy::phi", "IOStreamedHDF5");
\end{verbatim}
\end{itemize}

Data is always written unchunked by processor 0, ie. the chunks of a distributed
grid function or array will be collected from all other processors and streamed
out as a single dataset. Parallel streaming from multiple processors is not
supported yet.


\section{Checkpointing \& Recovery}

Thorn {\bf IOStreamedHDF5} can also be used to create HDF5 checkpoints and
stream them to another Cactus simulation which recovers from such a checkpoint
at the same time.

Checkpoint routines are scheduled at several timebins so that you can save
the current state of your simulation after the initial data phase,
during evolution, or at termination.
A recovery routine is registered with thorn {\bf IOUtil} in order to restart
a new simulation from a given HDF5 checkpoint.

Checkpointing and recovery are controlled by corresponding checkpoint/recovery
parameters of thorn {\bf IOUtil} (for a description of these parameters please
refer to this thorn's documentation).


%
% Automatically created from the ccl files
% Do not worry for now.
\include{interface}
\include{param}
\include{schedule}

\end{document}