Parameter names changes as announced in today's mail to users@cactuscode.org.

You must also update thorns IOHDF5Util and IOUtil now.

This thorn will be moved from BetaThorns to CactusPUGHIO now.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGHIO/IOStreamedHDF5/trunk@84 0888f3d4-9f52-45d2-93bc-d00801ff5e46

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..7741cc6
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,98 @@
+% 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}