extended IOHDF5 which can do n dimensional output plus n-1 dimensional hyperslabs - testing phase

git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGHIO/IOHDF5/trunk@2 4825ed28-b72c-4eae-9704-e50c059e567d

1 files changed, 97 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..1a617ab
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,97 @@
+% Thorn documentation template
+\documentclass{article}
+\begin{document}
+
+\title{IOHDF5}
+\author{Thomas Radke}
+\date{1999}
+\maketitle
+
+\abstract{Thorn IOHDF5 provides an IO method for output of variables in HDF5,
+the Hierarchical Data Format version 5 ({\tt http://hdf.ncsa.uiuc.edu/whatishdf5.html}).\\
+It also implements checkpointing/recovery functionality using HDF5.}
+%
+\section{Purpose}
+%
+Thorn IOHDF5 makes HDF5 available to the Cactus user by registering an IO method
+called {\tt IOHDF5\_3D} with the IO interface in the flesh.\\
+This method creates three-dimensional output of 3D grid functions as well as
+plane output of scalar variables.
+Data is written in HDF5 file format and goes into files named
+{\tt "<varname>\_3D.h5"}. Such datafiles can be further processed by
+visualization tools like Amira or AVS.\\
+%
+\newline
+%
+You obtain output by an IO method by either
+%
+\begin{itemize}
+  \item setting the appropriate IO parameters
+  \item calling one the routines of the IO function interface provided by the flesh
+\end{itemize}
+%
+%
+IOHDF5 also provides checkpointing/recovery functionality by registering
+%
+\begin{itemize}
+  \item a checkpoint method with the Runtime Function Repository in the flesh
+     if checkpointing was requested for this thorn.
+     This method is then scheduled at {\em CCTK\_CPINITIAL} and/or
+     {\em CCTK\_CHECKPOINT} (to checkpoint initial and/or evolution data).\\
+     Controled via checkpoint parameters, it decides when to save the current
+     state of simulation by dumping the contents of all Cactus variables and
+     parameters into a checkpoint file which is in HDF5 file format.\\
+     To write this file the thorn's IO method {\tt IOHDF5\_3D} is used.
+  \item a recovery method with the generic recovery function interface of thorn IOUtil.\\
+     At recovery time this method is called by IOUtil's generic recovery
+     routine. It gets passed a filename which is tested to identify a checkpoint
+     file in HDF5 format. If successful the method will then restore the
+     contents of all Cactus variables and parameters from the given checkpoint
+     file.
+\end{itemize}
+%
+For a description of IO and checkpoint/recovery parameters and the generic
+recovery function interface please see also the documentation of thorn IOUtil.\\
+For a description of IO function interface to invoke IO methods by application
+thorns please see the flesh documentation.
+%
+%
+\section{Comments}
+
+Since IOHDF5 uses parameters and the recovery function interface from IOUtil
+it also needs this I/O skeleton thorn compiled into Cactus and activated.\\
+%
+%
+\newline
+{\bf Building Cactus with HDF5}\\
+%
+The Cactus distribution does not contain the HDF5 header files and library which
+is used by thorn IOHDF5. 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 explicitely specify it with
+the {\tt HDF5\_DIR} option.\\
+%
+Configure also checks which library version is contained within the HDF5
+package: it can be either serial or parallel. The latter version includes the parallel IO extensions of the MPI 2 standard. To make use of these extensions
+you need to configure Cactus with both HDF5 and MPI. Please make also sure then
+that the parallel HDF5 library was built with the same MPI version as is used
+for Cactus.\\
+%
+If Cactus was not configured to use HDF5 but has thorn IOHDF5 compiled in
+it will give a warning message each time a thorn's routine is called
+saying HDF5 I/O is not available.
+%
+% Automatically created from the ccl files 
+% Do not worry for now.
+\include{interface}
+\include{param}
+\include{schedule}
+
+\end{document}