diff options
Diffstat (limited to 'doc/documentation.tex')
-rw-r--r-- | doc/documentation.tex | 98 |
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} |