Mention IOHDF5's restriction of not being able to output the same variable

more than once per timestep.


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

1 files changed, 44 insertions, 29 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 6928bd6..ba0dcbc 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,7 +1,7 @@
 \documentclass{article}
 
 % Use the Cactus ThornGuide style file
-% (Automatically used from Cactus distribution, if you have a 
+% (Automatically used from Cactus distribution, if you have a
 %  thorn without the Cactus Flesh download this from the Cactus
 %  homepage at www.cactuscode.org)
 \usepackage{../../../../doc/ThornGuide/cactus}
@@ -17,20 +17,22 @@
 % Do not delete next line
 % START CACTUS THORNGUIDE
 
+\newcommand{\ThisThorn}{{\it IOHDF5}}
+
 \begin{abstract}
-Thorn {\bf IOHDF5} provides an I/O method to output variables in HDF5 file format.
+Thorn \ThisThorn\ provides an I/O method to output variables in HDF5 file format.
 It also implements checkpointing/recovery functionality using HDF5.
 \end{abstract}
 %
 %
 \section{Purpose}
 %
-Thorn {\bf IOHDF5} uses the standard I/O library HDF5\footnote{Hierarchical Data
+Thorn \ThisThorn\ uses the standard I/O library HDF5\footnote{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 IOHDF5} I/O method which thorn {\bf IOHDF5}
+Output is done by invoking the \ThisThorn\ I/O method which thorn \ThisThorn
 registers with the flesh's I/O interface at startup.\\
 
 Data is written into files named {\tt "<varname>.h5"}.
@@ -38,29 +40,29 @@ Such datafiles can be used for further postprocessing (eg. visualization)
 or fed back into Cactus via the filereader capabilities of thorn {\bf IOUtil}.
 
 
-\section{{\bf IOHDF5} Parameters}
+\section{\ThisThorn\ Parameters}
 
-Parameters to control the {\tt IOHDF5} I/O method are:
+Parameters to control the \ThisThorn\ 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
+        How often to do periodic \ThisThorn\ 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 list of variables to output using the \ThisThorn\ 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
+        name. The special keyword {\it all} requests \ThisThorn\ 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.
+        The directory in which to place the \ThisThorn\ 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
+        If this parameter is set to an empty string \ThisThorn\ output will go
         to the standard output directory as specified in {\tt IO::out\_dir}.
 \end{itemize}
 
@@ -69,7 +71,7 @@ Parameters to control the {\tt IOHDF5} I/O method are:
 
 According to the ouptput mode parameter settings ({\tt IO::out\_mode},
 {\tt IO::out\_unchunked},\newline{\tt IO::out\_proc\_every}) of thorn {\bf IOUtil}, thorn
-{\bf IOHDF5} will output distributed data either
+\ThisThorn\ will output distributed data either
 \begin{itemize}
   \item in serial into a single unchunked file
 \begin{verbatim}
@@ -92,7 +94,7 @@ recombiner program.
 \section{Output of Hyperslab Data}
 \label{IOHDF5_output_hyperslabs}
 
-By default, thorn {\bf IOHDF5} outputs multidimensional Cactus variables with
+By default, thorn \ThisThorn\ 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
@@ -161,14 +163,26 @@ The hyperslab parameters which can be set in an option string are:
 \end{itemize}
 
 
+\section{\ThisThorn\ Output Restrictions}
+
+Due to the naming scheme used to build unique names for HDF5 datasets
+(see \ref{IOHDF5_import_data}, the \ThisThorn\ I/O method currently has the
+restriction that it can output a given variable (with a specific timelevel) --
+or a hyperslab of it -- only once per iteration.
+
+As a workaround, you should request output in such a case by using the
+flesh's I/O API {\tt CCTK\_\-OutputVarAs\-ByMethod()} routine with a different
+alias name for each output. Note that this will create multiple output files
+for the same variable then.
+
 \section{Checkpointing \& Recovery}
 
-Thorn {\bf IOHDF5} can also be used for creating HDF5 checkpoint files and
+Thorn \ThisThorn\ 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. Checkpointing for thorn {\bf IOHDF5}
+during evolution, or at termination. Checkpointing for thorn \ThisThorn\
 is enabled by setting the parameter {\tt IOHDF5::checkpoint = "yes"}.
 
 A recovery routine is registered with thorn {\bf IOUtil} in order to restart
@@ -181,17 +195,18 @@ parameters of thorn {\bf IOUtil} (for a description of these parameters please
 refer to this thorn's documentation).
 
 
-\section{Importing External Data Into Cactus With {bf IOHDF5}}
+\section{Importing External Data Into Cactus With \ThisThorn}
+\label{IOHDF5_import_data}
 
 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 {\bf IOHDF5}.
+processed by the registered recovery routine of thorn \ThisThorn.
 
 The following description explains the HDF5 file layout of an unchunked
-datafile which thorn {\bf IOHDF5} expects in order to restore Cactus variables
+datafile which thorn \ThisThorn\ 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 {\bf IOHDF5} file layout. This working example can be used as a
+a datafile with \ThisThorn\ file layout. This working example can be used as a
 template for building your own data converter program.\\
 
 \begin{enumerate}
@@ -203,13 +218,13 @@ template for building your own data converter program.\\
 \begin{verbatim}
   "<full variable name> timelevel <timelevel> at iteration <iteration>"
 \end{verbatim}
-        {\bf IOHDF5}'s recovery routine parses a dataset's name according to this
+        \ThisThorn'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 {\bf IOHDF5} to safely match it against a specific Cactus variable.
+        enough for \ThisThorn\ 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.
@@ -233,7 +248,7 @@ 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.h5} in {\bf IOHDF5} file layout which contains a single dataset named
+{\tt x.h5} in \ThisThorn\ 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.
@@ -252,10 +267,10 @@ it would probably not make much sense to feed this datafile into Cactus for
 initializing your x coordinate grid function :-)
 %
 %
-\section{Building A Cactus Configuration with {\bf IOHDF5}}
+\section{Building A Cactus Configuration with \ThisThorn}
 %
 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
+is used by thorn \ThisThorn. So you need to configure it as an external
 software package via:
 %
 \begin{verbatim}
@@ -267,16 +282,16 @@ 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}
+Thorn \ThisThorn\ inherits from {\it IOUtil} and {\it IOHDF5Util}
 so you need to include these thorns in your thorn list to build a configuration
-with {\bf IOHDF5}.
+with \ThisThorn.
 %
 %
-\section{Utility Programs provided by {\bf IOHDF5}}
+\section{Utility Programs provided by \ThisThorn}
 %
 \label{IOHDF5_utility_programs}
 
-Thorn {\bf IOHDF5} provides the following utility programs:
+Thorn \ThisThorn\ provides the following utility programs:
 %
 \begin{itemize}
   \item {\tt hdf5\_recombiner}\\
@@ -295,7 +310,7 @@ Thorn {\bf IOHDF5} provides the following utility programs:
 \end{itemize}
 %
 All utility programs are located in the {\tt src/util/} subdirectory of thorn
-{\bf IOHDF5}. To build the utilities just do a
+\ThisThorn. To build the utilities just do a
 
 \begin{verbatim}
   make <configuration>-utils