Give a description and an example on how to use option strings to specify

a hyperslab selection and the output frequency for individual variables.
Also added some smaller fixes in the thorn documentation.


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

1 files changed, 142 insertions, 61 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index d75e81f..f59a89d 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -13,36 +13,7 @@ It also implements checkpointing/recovery functionality using HDF5.
 }
 %
 %
-\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}
+\section{Purpose}
 %
 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)
@@ -52,26 +23,39 @@ grid arrays of arbitrary dimension) in the HDF5 file format.\\
 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
-\begin{itemize}
-  \item setting the appropriate I/O parameters in your parameter files, eg.
-\begin{verbatim}
-  IOHDF5::out_every = 10
-  IOHDF5::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", "IOHDF5");
-\end{verbatim}
-\end{itemize}
-
 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 {\bf IOUtil}.
 
 
-\subsection{Serial versus Parallel Output}
+\section{{\bf IOHDF5} Parameters}
+
+Parameters to control the {\tt IOHDF5} I/O method are:
+\begin{itemize}
+  \item {\tt IOHDF5::out\_every} (steerable)\\
+        How often to do periodic {\tt IOHDF5} output. If this parameter is set
+        in the parameter file, it will override the setting of the shared
+        {\tt IO::out\_every} parameter. The output frequency can also be set
+        for individual variables using the {\tt out\_every} option in an option
+        string appended to the {\tt IOHDF5::out\_vars} parameter.
+  \item {\tt IOHDF5::out\_vars} (steerable)\\
+        The list of variables to output using the {\bf IOHDF5} I/O method.
+        The variables must be given by their fully qualified variable or group
+        name. The special keyword {\it all} requests {\tt IOHDF5} output for
+        all variables. Multiple names must be separated by whitespaces.\\
+        An option string can be appended in square brackets to a group/variable
+        name. Supported options are {\tt out\_every} (to set the output
+        frequency for individual variables) and hyperslab options (see section
+        \ref{IOHDF5_output_hyperslabs} for details).
+  \item {\tt IOHDF5::out\_dir}\\
+        The directory in which to place the {\tt IOHDF5} output files.
+        If the directory doesn't exist at startup it will be created.\\
+        If this parameter is set to an empty string {\tt IOHDF5} output will go
+        to the standard output directory as specified in {\tt IO::out\_dir}.
+\end{itemize}
+
+
+\section{Serial versus Parallel Output}
 
 According to the ouptput mode parameter settings ({\tt IO::out\_mode,
 IO::out\_unchunked, IO::out\_proc\_every}) of thorn {\bf IOUtil}, thorn
@@ -90,18 +74,81 @@ IO::out\_unchunked, IO::out\_proc\_every}) of thorn {\bf IOUtil}, thorn
 \end{itemize}
 The default is to output data in parallel, in order to get maximum I/O
 performance. If needed, you can recombine the resulting chunked datafiles
-into a single unchunked file using the recombiner utility program provided
-in {\tt IOHDF5/src/util/}.\\
+into a single unchunked file using the recombiner utility program.
+See section \ref{IOHDF5_utility_programs} for information how to build the
+recombiner program.
+
+
+\section{Output of Hyperslab Data}
+\label{IOHDF5_output_hyperslabs}
+
+By default, thorn {\bf IOHDF5} outputs multidimensional Cactus variables with
+their full contents resulting in maximum data output. This can be changed for
+individual variables by specifying a hyperslab as a subset of the data within
+the N-dimensional volume. Such a subset (called a {\it hyperslab}) is generally
+defined as an orthogonal region into the multidimensional dataset, with an
+origin (lower left corner of the hyperslab), direction vectors (defining the
+number of hyperslab dimensions and spanning the hyperslab within the
+N-dimensional grid), an extent (the length of the hyperslab in each of its
+dimensions), and an optional downsampling factor.
 
-To build the recombiner just do a
+Hyperslab parameters can be set for individual variables using an option string
+appended to the variables' full names in the {\tt IOHDF5::out\_vars} parameter.
+
+Here is an example which outputs two 3D grid functions {\tt Grid::r} and {\tt
+Wavetoy::phi}. While the first is output with their full contents at every
+5th iteration (overriding the {\tt IOHDF5::out\_every} parameter for this
+variable), a two-dimensional hyperslab is defined for the second grid function.
+This hyperslab defines a subvolume to output, starting with a 5 grid points
+offset into the grid, spanning in the yz-plane, with an extent of 10 and 20
+grid points in y- and z-direction respectively. For this hyperslab, only every
+other grid point will be output.
 
 \begin{verbatim}
-  make <configuration>-utils
+  IOHDF5::out_every = 1
+  IOHDF5::out_vars  = "Grid::x[ out_every = 5 ]
+                       Wavetoy::phi[ origin     = {4 4 4}
+                                     direction  = {0 0 0
+                                                   0 1 0
+                                                   0 0 1}
+                                     extent     = {10 20}
+                                     downsample = {2 2}   ]"
 \end{verbatim}
 
-in the Cactus toplevel directory. The recombiner executable {\tt
-hdf5\_recombiner} will be placed in the {\tt exe/<configuration>/}
-subdirectory.
+The hyperslab parameters which can be set in an option string are:
+\begin{itemize}
+  \item{\tt origin}\\
+    This specifies the origin of the hyperslab. It must be given as an array
+    of integer values with $N$ elements. Each value specifies the offset in
+    grid points in this dimension into the N-dimensional volume of the grid
+    variable.\\
+    If the origin for a hyperslab is not given, if will default to 0.
+  \item{\tt direction}\\
+    The direction vectors specify both the directions in which the hyperslab
+    should be spanned (each vector defines one direction of the hyperslab)
+    and its dimensionality ($=$ the total number of dimension vectors).
+    The direction vectors must be given as a concatenated array of integer
+    values. The direction vectors must not be a linear combination of each other
+    or null vectors.\\
+    If the direction vectors for a hyperslab are not given, the hyperslab
+    dimensions will default to $N$, and its directions are parallel to the
+    underlying grid.
+  \item{\tt extent}\\
+    This specifies the extent of the hyperslab in each of its dimensions as
+    a number of grid points. It must be given as an array of integer values
+    with $M$ elements ($M$ being the number of hyperslab dimensions).\\
+    If the extent for a hyperslab is not given, it will default to the grid
+    variable's extent. Note that if the origin is set to
+    a non-zero value, you should also set the hyperslab extent otherwise
+    the default extent would possibly exceed the variable's grid extent.
+  \item{\tt downsample}\\
+    To select only every so many grid points from the hyperslab you can set
+    the downsample option. It must be given as an array of integer values
+    with $M$ elements ($M$ being the number of hyperslab dimensions).\\
+    If the downsample option is not given, it will default to the settings
+    of the general downsampling parameters {\tt IO::downsample\_[xyz]} as
+    defined by thorn {\bf IOUtil}.
+\end{itemize}
 
 
 \section{Checkpointing \& Recovery}
@@ -111,7 +158,9 @@ 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.
+during evolution, or at termination. Checkpointing for thorn {\bf IOHDF5}
+is enabled by setting the parameter {\tt IOHDF5::checkpoint = "yes"}.
+
 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
@@ -189,31 +238,63 @@ it would probably not make much sense to feed this datafile into Cactus for
 initializing your x coordinate grid function :-)
 %
 %
-\section{Other Utility Programs in {\bf IOHDF5}}
+\section{Building A Cactus Configuration with {\bf IOHDF5}}
 %
-In addition to the HDF5 recombiner program, thorn {\bf IOHDF5} also provides
-some other utilities which can be build the same way:
+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 IOHDF5} inherits from {\bf IOUtil} and {\bf IOHDF5Util}
+so you need to include these thorns in your thorn list to build a configuration
+with {\bf IOHDF5}.
+%
+%
+\section{Utility Programs provided by {\bf IOHDF5}}
+%
+\label{IOHDF5_utility_programs}
+
+Thorn {\bf IOHDF5} provides the following utility programs:
 %
 \begin{itemize}
-  \item {\tt hdf5\_convert\_from\_ieeeio.c}\\
+  \item {\tt hdf5\_recombiner}\\
+    Recombines chunked HDF5 datafile(s) into a single unchunked HDF5 datafile.
+  \item {\tt hdf5\_convert\_from\_ieeeio}\\
     Converts a datafile created by thorn {\bf IOFlexIO} into an HDF5 datafile.
-  \item {\tt hdf5\_merge.c}\\
+  \item {\tt hdf5\_merge}\\
     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
     timestep.
-  \item {\tt hdf5\_extract.c}\\
+  \item {\tt hdf5\_extract}\\
     Extracts a given list of named objects (groups or datasets) from an HDF5
     input file and writes them into a new HDF5 output file.
     This is the reverse operation to what {\tt hdf5\_merge.c} does. Useful eg.
     for extracting individual timesteps from a time series HDF5 datafile.
 \end{itemize}
 %
+All utility programs are located in the {\tt src/util/} subdirectory of thorn
+{\bf IOHDF5}. To build the utilities just do a
+
+\begin{verbatim}
+  make <configuration>-utils
+\end{verbatim}
+
+in the Cactus toplevel directory. The executables will then be placed in the
+{\tt exe/<configuration>/} subdirectory.
+
 All utility programs are self-explaining -- just call them without arguments
 to get a short usage info.
-%
 If any of these utility programs is called without arguments it will print
 a usage message.
-%
+
 % Automatically created from the ccl files
 % Do not worry for now.
 \include{interface}