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 AlphaThorns to CactusPUGHIO now.


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

1 files changed, 66 insertions, 37 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index a6b14d9..d75e81f 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -4,22 +4,52 @@
 
 \title{IOHDF5}
 \author{Thomas Radke}
-\date{1999}
+\date{1999\\$ $Revision$ $Date$ $}
 \maketitle
 
 \abstract{
-Thorn IOHDF5 provides an I/O method to output variables in HDF5 file format.
+Thorn {\bf IOHDF5} provides an I/O method to output variables in HDF5 file format.
 It also implements checkpointing/recovery functionality using HDF5.
 }
 %
-\section{Purpose}
 %
-Thorn IOHDF5 uses the standard I/O library HDF5 (Hierarchical Data Format
+\section{Building A Cactus Configuration with {\bf IOHDF5}}
+%
+The Cactus distribution does not contain the HDF5 header files and library which
+is used by thorn {\bf 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 explicitly specify it with
+the {\tt HDF5\_DIR} configure variable.
+
+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}.
+%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.
+%
+%
+\section{Getting HDF5 Output}
+%
+Thorn {\bf IOHDF5} 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 grid variables (grid scalars, grid functions, and arrays
-of arbitrary dimension) in the HDF5 file format.\\
+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 IOHDF5} I/O method which thorn IOHDF5
+Output is done by invoking the {\tt IOHDF5} I/O method which thorn {\bf IOHDF5}
 registers with the flesh's I/O interface at startup.\\
 
 You obtain output by either
@@ -38,24 +68,24 @@ You obtain output by either
 
 Data is written into files named {\tt "<varname>.h5"}.
 Such datafiles can be used for further postprocessing (eg. visualization)
-or fed back into Cactus via the filereader capabilities of thorn IOUtil.
+or fed back into Cactus via the filereader capabilities of thorn {\bf IOUtil}.
 
 
-\subsection{Parallel File I/O}
+\subsection{Serial versus Parallel Output}
 
-According to the ouptput mode parameter settings ({\tt IO::out3D\_mode,
-IO::out3D\_unchunked, IO::out3D\_procs}) of thorn IOUtil, thorn IOHDF5
-will output distributed data either
+According to the ouptput mode parameter settings ({\tt IO::out\_mode,
+IO::out\_unchunked, IO::out\_proc\_every}) of thorn {\bf IOUtil}, thorn
+{\bf IOHDF5} will output distributed data either
 \begin{itemize}
   \item in serial into a single unchunked file
 \begin{verbatim}
-  IO::out3D_mode      = "onefile"
-  IO::out3D_unchunked = "yes"
+  IO::out_mode      = "onefile"
+  IO::out_unchunked = "yes"
 \end{verbatim}
   \item in parallel, that is, into separate files containing chunks of the
         individual processors' patches of the distributed array
 \begin{verbatim}
-  IO::out3D_mode      = "proc | np"
+  IO::out_mode      = "proc|np"
 \end{verbatim}
 \end{itemize}
 The default is to output data in parallel, in order to get maximum I/O
@@ -74,41 +104,39 @@ hdf5\_recombiner} will be placed in the {\tt exe/<configuration>/}
 subdirectory.
 
 
-\subsection{Checkpointing \& Recovery}
+\section{Checkpointing \& Recovery}
 
-Thorn IOHDF5 can also be used for creating HDF5 checkpoint files and recovering
-from such files later on.\\
+Thorn {\bf IOHDF5} can also be used for creating HDF5 checkpoint files and
+recovering from such files later on.
 
 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 IOUtil in order to restart
+A recovery routine is registered with thorn {\bf IOUtil} in order to restart
 a new simulation from a given HDF5 checkpoint.
 The very same recovery mechanism is used to implement a filereader
-functionality to feed back data into Cactus.\\
+functionality to feed back data into Cactus.
 
 Checkpointing and recovery are controlled by corresponding checkpoint/recovery
-parameters of thorn IOUtil (for a description of these parameters please refer
-to this thorn's documentation).
+parameters of thorn {\bf IOUtil} (for a description of these parameters please
+refer to this thorn's documentation).
 
 
-\section{Comments}
-
-\subsection{Importing external data into Cactus with IOHDF5}
+\section{Importing External Data Into Cactus With {bf IOHDF5}}
 
 In order to import external data into Cactus (eg. to initialize some variable)
 you first need to convert this data into an HDF5 datafile which then can be
-processed by the registered recovery routine of thorn IOHDF5.\\
+processed by the registered recovery routine of thorn {\bf IOHDF5}.
 
 The following description explains the HDF5 file layout of an unchunked
-datafile which thorn IOHDF5 expects in order to restore Cactus variables
+datafile which thorn {\bf IOHDF5} expects in order to restore Cactus variables
 from it properly. There is also a well-documented example C program provided
 ({\tt IOHDF5/doc/CreateIOHDF5datafile.c}) which illustrates how to create
-a datafile with IOHDF5 file layout. This working example can be used as a
+a datafile with {\bf IOHDF5} file layout. This working example can be used as a
 template for building your own data converter program.\\
 
 \begin{enumerate}
-  \item Actual data is stored as multidimensional datasets in an IOHDF5 file.
+  \item Actual data is stored as multidimensional datasets in an HDF5 file.
         There is no nested grouping structure, every dataset is located
         in the root group.\\
         A dataset's name must match the following naming pattern which
@@ -116,13 +144,13 @@ template for building your own data converter program.\\
 \begin{verbatim}
   "<full variable name> timelevel <timelevel> at iteration <iteration>"
 \end{verbatim}
-        IOHDF5's recovery routine parses a dataset's name according to this
+        {\bf IOHDF5}'s recovery routine parses a dataset's name according to this
         pattern to determine the Cactus variable to restore, along with its
         timelevel. The iteration number is just informative and not needed here.
 
   \item The type of your data as well as its dimensions are already
         inherited by a dataset itself as metainformation. But this is not
-        enough for IOHDF5 to safely match it against a specific Cactus variable.
+        enough for {\bf IOHDF5} to safely match it against a specific Cactus variable.
         For that reason, the variable's groupname, its grouptype, and the
         total number of timelevels must be attached to every dataset
         as attribute information.
@@ -142,17 +170,18 @@ template for building your own data converter program.\\
 \end{enumerate}
 
 The example C program goes through all of these steps and creates a datafile
-{\tt x\_3d.h5} in IOHDF5 file layout which contains a single dataset named
+{\tt x.h5} in {\bf IOHDF5} file layout which contains a single dataset named
 {\tt "grid::x timelevel 0 at iteration 0"}, with groupname
 {\tt "grid::coordinates"}, grouptype {\tt CCTK\_GF} (thus identifying the
-variable as a grid function), and the total number of timelevels set to 1.\\
+variable as a grid function), and the total number of timelevels set to 1.
+
 The global attributes are set to
 {\tt "unchunked" $=$ "yes", nprocs $=$ 1,} and {\tt ioproc\_every $=$ 1}.\\
 
 Once you've built and ran the program you can easily verify if it worked
 properly with
 \begin{verbatim}
-  h5dump x_3d.h5
+  h5dump x.h5
 \end{verbatim}
 which lists all objects in the datafile along with their values.
 It will also dump the contents of the 3D dataset. Since it only contains zeros
@@ -160,14 +189,14 @@ it would probably not make much sense to feed this datafile into Cactus for
 initializing your x coordinate grid function :-)
 %
 %
-\subsection{Other utility programs in IOHDF5}
+\section{Other Utility Programs in {\bf IOHDF5}}
 %
-In addition to the HDF5 recombiner program, thorn IOHDF5 also provides
+In addition to the HDF5 recombiner program, thorn {\bf IOHDF5} also provides
 some other utilities which can be build the same way:
 %
 \begin{itemize}
   \item {\tt hdf5\_convert\_from\_ieeeio.c}\\
-    Converts a datafile created by thorn IOFlexIO into an HDF5 datafile.
+    Converts a datafile created by thorn {\bf IOFlexIO} into an HDF5 datafile.
   \item {\tt hdf5\_merge.c}\\
     Merges a list of HDF5 input files into a single HDF5 output file.
     This can be used to concatenate HDF5 output data created as one file per