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


git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGHIO/IOStreamedHDF5/trunk@84 0888f3d4-9f52-45d2-93bc-d00801ff5e46

12 files changed, 157 insertions, 87 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}
diff --git a/par/HDF5socket_demo.par b/par/HDF5socket_demo.par
index 732194e..8f5a59f 100644
--- a/par/HDF5socket_demo.par
+++ b/par/HDF5socket_demo.par
@@ -25,7 +25,7 @@ cactus::cctk_itlast = 500000
 IOBasic::outInfo_every = 1
 IOBasic::outInfo_vars  = "wavetoy::phi"
 
-IO::outdir = "wavebinary"
+IO::out_dir = "wavebinary"
 
 IO::out_every             = 1
 IOStreamedHDF5::out_every = 1
diff --git a/par/checkpoint.par b/par/checkpoint.par
index 4ad45fb..9774f31 100644
--- a/par/checkpoint.par
+++ b/par/checkpoint.par
@@ -28,7 +28,7 @@ IO::checkpoint_every = 1
 #
 # Currently IOStreamedHDF5 can only stream "onefile"
 # but this may be chunked or unchunked.
-IO::out3d_mode = "onefile"
+IO::out_mode = "onefile"
 #IO::out3D_unchunked = "yes"
 
 # enable IOStreamedHDF5 checkpointing
@@ -38,7 +38,7 @@ IOStreamedHDF5::checkpoint = "yes"
 IOStreamedHDF5::checkpoint_accept_timeout = 3
 
 # print some verbose output and timing information
-IO::verbose = "yes"
+IO::verbose = "standard"
 IO::print_timing_info = "yes"
 
 
diff --git a/par/recover.par b/par/recover.par
index adb79ca..6a515e0 100644
--- a/par/recover.par
+++ b/par/recover.par
@@ -32,5 +32,5 @@ IO::recover_file = "localhost:8001"
 IO::checkpoint_every = 0
 
 # print some verbose output and timing information
-IO::verbose = "yes"
+IO::verbose = "standard"
 IO::print_timing_info = "yes"
diff --git a/param.ccl b/param.ccl
index 46f088c..143ce31 100644
--- a/param.ccl
+++ b/param.ccl
@@ -11,11 +11,15 @@ private:
 ########################
 INT out_every "How often to do HDF5 streaming, overrides IO::out_every" STEERABLE = ALWAYS
 {
-  -1:* :: "Values <= 0 disable IOStreamedHDF5 output"
+   1:* :: "Every so many iterations"
+   0:  :: "Disable IOStreamedHDF5 output"
+  -1:  :: "Default to IO::out_every"
 } -1
 INT outHDF5_every "How often to do HDF5 streaming, overrides IO::out_every" STEERABLE = ALWAYS
 {
-  -1:* :: "Values <= 0 disable IOStreamedHDF5 output"
+   1:* :: "Every so many iterations"
+   0:  :: "Disable IOStreamedHDF5 output"
+  -1:  :: "Default to IO::out_every"
 } -1
 
 #####################
@@ -23,10 +27,11 @@ INT outHDF5_every "How often to do HDF5 streaming, overrides IO::out_every" STEE
 #####################
 STRING out_vars "Variables to stream in HDF5 file format" STEERABLE = ALWAYS
 {
-  .* :: A regex which matches everything
+  ".+" :: "Space-separated list of fully qualified variable/group names"
+  "^$" :: "An empty string to output nothing"
 } ""
 
-INT data_port "Port to stream out the HDF5 data files"
+INT data_port "Port to stream out the HDF5 data files" STEERABLE = RECOVER
 {
   1000:32000 :: "Ports below 1000 require root access"
 } 8000
@@ -56,23 +61,13 @@ INT checkpoint_accept_timeout "Timeout in seconds for accepting client connectio
 #############################################################################
 shares: IO
 
-########################
-# How often to do output
-########################
-#FIXME: need USES AS
-#USES INT out_every
+#FIXME: want USES INT out_every AS default_out_every
 
-################
-# various things
-################
-USES BOOLEAN verbose
+USES KEYWORD verbose
 USES BOOLEAN print_timing_info
 
-###################################
-# Checkpointing/recovery parameters
-###################################
+USES INT     checkpoint_every
 USES BOOLEAN checkpoint_ID
-USES KEYWORD recover
-USES INT checkpoint_every
 USES BOOLEAN checkpoint_on_terminate
-USES STRING recover_file
+USES KEYWORD recover
+USES STRING  recover_file
diff --git a/schedule.ccl b/schedule.ccl
index 9eb7414..d57c1b3 100644
--- a/schedule.ccl
+++ b/schedule.ccl
@@ -17,24 +17,24 @@ schedule IOStreamedHDF5_Terminate at TERMINATE before IOHDF5Util_Terminate
 ########################################################################
 ### register checkpointing routines
 ########################################################################
-schedule IOStreamedHDF5_InitialDataCheckpoint at CCTK_CPINITIAL
+schedule IOStreamedHDF5_InitialDataCheckpoint at CPINITIAL
 {
   LANG:C
 } "Initial data checkpoint routine"
 
-schedule IOStreamedHDF5_EvolutionCheckpoint at CCTK_CHECKPOINT
+schedule IOStreamedHDF5_EvolutionCheckpoint at CHECKPOINT
 {
   LANG:C
 } "Evolution data checkpoint routine"
 
-schedule IOStreamedHDF5_TerminationCheckpoint at CCTK_TERMINATE before IOStreamedHDF5_Terminate
+schedule IOStreamedHDF5_TerminationCheckpoint at TERMINATE before IOStreamedHDF5_Terminate
 {
   LANG:C
 } "Termination checkpoint routine"
 
 if (! CCTK_Equals (recover, "no") && *recover_file)
 {
-  schedule IOStreamedHDF5_RecoverParameters at CCTK_RECOVER_PARAMETERS
+  schedule IOStreamedHDF5_RecoverParameters at RECOVER_PARAMETERS
   {
     LANG:C
   } "Parameter recovery routine"
diff --git a/src/DumpGH.c b/src/DumpGH.c
index dcec1a4..b75ed6b 100644
--- a/src/DumpGH.c
+++ b/src/DumpGH.c
@@ -17,7 +17,7 @@
 #include "CactusBase/IOUtil/src/ioGH.h"
 #include "CactusPUGH/PUGH/src/include/pugh.h"
 #include "CactusBase/IOUtil/src/ioutil_CheckpointRecovery.h"
-#include "BetaThorns/IOHDF5Util/src/ioHDF5UtilGH.h"
+#include "CactusPUGHIO/IOHDF5Util/src/ioHDF5UtilGH.h"
 #include "ioStreamedHDF5GH.h"
 
 #ifdef HAVE_SYS_TIME_H
@@ -31,8 +31,8 @@
 #endif
 
 /* the rcs ID and its dummy function to use it */
-static const char *rcsid = "$Id$";
-CCTK_FILEVERSION(BetaThorns_IOStreamedHDF5_DumpGH_c)
+static const char *rcsid = "$Header$";
+CCTK_FILEVERSION(CactusPUGHIO_IOStreamedHDF5_DumpGH_c)
 
 
 /********************************************************************
@@ -104,7 +104,7 @@ void IOStreamedHDF5_EvolutionCheckpoint (const cGH *GH)
       ((checkpoint_every > 0 && GH->cctk_iteration % checkpoint_every == 0) ||
        checkpoint_next))
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_INFO("------------------------------------------------------------");
       CCTK_VInfo (CCTK_THORNSTRING, "Dumping periodic checkpoint file at "
@@ -236,7 +236,7 @@ static int Checkpoint (const cGH *GH, int called_from)
   /* now open the file */
   if (CCTK_MyProc (GH) == ioUtilGH->ioproc && myGH->checkpoint_socket >= 0)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_VInfo (CCTK_THORNSTRING, "Creating checkpoint file");
     }
@@ -273,7 +273,7 @@ static int Checkpoint (const cGH *GH, int called_from)
   {
     if (checkpoint_accept_timeout > 0)
     {
-      if (verbose)
+      if (CCTK_Equals (verbose, "full"))
       {
         CCTK_VInfo (CCTK_THORNSTRING, "Waiting %d seconds to send "
                                       "checkpoint file to port %d",
@@ -287,7 +287,7 @@ static int Checkpoint (const cGH *GH, int called_from)
       timeout.tv_usec = 0;
       select (myGH->checkpoint_socket + 1, &readset, NULL, NULL, &timeout);
     }
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_VInfo (CCTK_THORNSTRING, "Closing checkpoint file on port %d",
                   checkpoint_port);
diff --git a/src/Output.c b/src/Output.c
index 15450c1..576b34f 100644
--- a/src/Output.c
+++ b/src/Output.c
@@ -17,8 +17,8 @@
 #include "ioStreamedHDF5GH.h"
 
 /* the rcs ID and its dummy function to use it */
-static const char *rcsid = "$Id$";
-CCTK_FILEVERSION(BetaThorns_IOStreamedHDF5_Output_c)
+static const char *rcsid = "$Header$";
+CCTK_FILEVERSION(CactusPUGHIO_IOStreamedHDF5_Output_c)
 
 
 /********************************************************************
@@ -36,7 +36,7 @@ static void CheckSteerableParameters (const cGH *GH);
    @enddesc
 
    @calls      IOStreamedHDF5_TimeFor
-               IOStreamedHDF5_OutputVarAs
+               IOStreamedHDF5_Write
 
    @var        GH
    @vdesc      Pointer to CCTK GH
@@ -53,44 +53,21 @@ static void CheckSteerableParameters (const cGH *GH);
 int IOStreamedHDF5_OutputGH (const cGH *GH)
 {
   int vindex, retval;
-  ioStreamedHDF5GH *myGH;
-  const char *name;
-  char *fullname;
-  DECLARE_CCTK_PARAMETERS
+  const ioStreamedHDF5GH *myGH;
 
 
-  myGH = (ioStreamedHDF5GH *) CCTK_GHExtension (GH, "IOStreamedHDF5");
-
-  CheckSteerableParameters (GH);
-
-  if (myGH->out_every <= 0)
-  {
-    return (0);
-  }
+  retval = 0;
+  myGH = (const ioStreamedHDF5GH *) CCTK_GHExtension (GH, "IOStreamedHDF5");
 
   /* loop over all variables */
-  for (vindex = retval = 0; vindex < CCTK_NumVars (); vindex++)
+  for (vindex = CCTK_NumVars () - 1; vindex >= 0; vindex--)
   {
-    if (IOStreamedHDF5_TimeFor (GH, vindex))
+    if (IOStreamedHDF5_TimeFor (GH, vindex) &&
+        IOStreamedHDF5_Write (GH, vindex, CCTK_VarName (vindex)) == 0)
     {
-      name     = CCTK_VarName (vindex);
-      fullname = CCTK_FullName (vindex);
-
-      if (verbose)
-      {
-        CCTK_VInfo (CCTK_THORNSTRING, "IOStreamedHDF5_OutputGH: "
-                                      "output of variable (fullname, name) = "
-                                      "('%s', '%s')", fullname, name);
-      }
-
-      if (IOStreamedHDF5_OutputVarAs (GH, fullname, name) == 0)
-      {
-        /* register variable as having output this iteration */
-        myGH->out_last[vindex] = GH->cctk_iteration;
-        retval++;
-      }
-
-      free (fullname);
+      /* register variable as having output this iteration */
+      myGH->out_last[vindex] = GH->cctk_iteration;
+      retval++;
     }
   }
 
@@ -140,7 +117,7 @@ int IOStreamedHDF5_OutputVarAs (const cGH *GH, const char *fullname,
 
   vindex = CCTK_VarIndex (fullname);
 
-  if (verbose)
+  if (CCTK_Equals (verbose, "full"))
   {
     CCTK_VInfo (CCTK_THORNSTRING, "IOStreamedHDF5_OutputVarAs: "
                                   "output of variable (fullname, alias) = "
@@ -253,7 +230,7 @@ int IOStreamedHDF5_TriggerOutput (const cGH *GH, int vindex)
 
   myGH = (ioStreamedHDF5GH *) CCTK_GHExtension (GH, "IOStreamedHDF5");
 
-  if (verbose)
+  if (CCTK_Equals (verbose, "full"))
   {
     fullname = CCTK_FullName (vindex);
     CCTK_VInfo (CCTK_THORNSTRING, "IOStreamedHDF5_TriggerOutput: "
diff --git a/src/RecoverGH.c b/src/RecoverGH.c
index d1339f3..2007672 100644
--- a/src/RecoverGH.c
+++ b/src/RecoverGH.c
@@ -24,8 +24,8 @@
 #include "ioStreamedHDF5GH.h"
 
 /* the rcs ID and its dummy function to use it */
-static const char *rcsid = "$Id$";
-CCTK_FILEVERSION(BetaThorns_IOStreamedHDF5_RecoverGH_c)
+static const char *rcsid = "$Header$";
+CCTK_FILEVERSION(CactusPUGHIO_IOStreamedHDF5_RecoverGH_c)
 
 
 /********************************************************************
@@ -130,7 +130,7 @@ int IOStreamedHDF5_Recover (cGH *GH, const char *basefilename, int called_from)
   }
 
   /* Recover variables */
-  if (verbose)
+  if (CCTK_Equals (verbose, "full"))
   {
     CCTK_VInfo (CCTK_THORNSTRING, "Recovering %schunked data with ioproc %d, "
                 "ioproc_every %d", fileinfo.unchunked ? "un" : "",
@@ -141,7 +141,7 @@ int IOStreamedHDF5_Recover (cGH *GH, const char *basefilename, int called_from)
   /* Recover GH extensions */
   if (result == 0 && called_from == CP_RECOVER_DATA)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_INFO ("Recovering GH extensions");
     }
@@ -151,7 +151,7 @@ int IOStreamedHDF5_Recover (cGH *GH, const char *basefilename, int called_from)
   /* Close the file */
   if (CCTK_MyProc (GH) == fileinfo.ioproc)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       if (called_from == CP_RECOVER_DATA)
       {
@@ -321,7 +321,7 @@ static int OpenFile (cGH *GH, const char *basefilename, int called_from,
 
   if (myproc == 0)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_VInfo (CCTK_THORNSTRING, "Opening streamed HDF5 file from '%s'",
                   fileinfo->filename);
@@ -375,7 +375,7 @@ static int OpenFile (cGH *GH, const char *basefilename, int called_from,
       if ((fileinfo->ioproc_every == nprocs && nprocs > 1) ||
           fileinfo->unchunked)
       {
-        if (verbose)
+        if (CCTK_Equals (verbose, "full"))
         {
           CCTK_VInfo (CCTK_THORNSTRING, "Recovering from one %schunked file",
                                         fileinfo->unchunked ? "un":"");
@@ -393,7 +393,7 @@ static int OpenFile (cGH *GH, const char *basefilename, int called_from,
         }
         else
         {
-          if (verbose)
+          if (CCTK_Equals (verbose, "full"))
           {
             CCTK_VInfo (CCTK_THORNSTRING, "Recovering from %d chunked files",
                         nprocs / fileinfo->ioproc_every +
diff --git a/src/Startup.c b/src/Startup.c
index d93d3af..4bed822 100644
--- a/src/Startup.c
+++ b/src/Startup.c
@@ -24,8 +24,8 @@
 #endif
 
 /* the rcs ID and its dummy function to use it */
-static const char *rcsid = "$Id$";
-CCTK_FILEVERSION(BetaThorns_IOStreamedHDF5_Startup_c)
+static const char *rcsid = "$Header$";
+CCTK_FILEVERSION(CactusPUGHIO_IOStreamedHDF5_Startup_c)
 
 
 /********************************************************************
diff --git a/src/Write.c b/src/Write.c
index fd0f98b..303c6be 100644
--- a/src/Write.c
+++ b/src/Write.c
@@ -15,12 +15,12 @@
 #include "cctk_Parameters.h"
 #include "StoreNamedData.h"
 #include "CactusBase/IOUtil/src/ioGH.h"
-#include "BetaThorns/IOHDF5Util/src/ioHDF5UtilGH.h"
+#include "CactusPUGHIO/IOHDF5Util/src/ioHDF5UtilGH.h"
 #include "ioStreamedHDF5GH.h"
 
 /* the rcs ID and its dummy function to use it */
-static const char *rcsid = "$Id$";
-CCTK_FILEVERSION(BetaThorns_IOStreamedHDF5_Write_c)
+static const char *rcsid = "$Header$";
+CCTK_FILEVERSION(CactusPUGHIO_IOStreamedHDF5_Write_c)
 
 
 /*@@
@@ -99,7 +99,7 @@ int IOStreamedHDF5_Write (const cGH *GH, int vindex, const char *alias)
   file = -1;
   if (CCTK_MyProc (GH) == 0 && myGH->data_socket >= 0)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_VInfo (CCTK_THORNSTRING, "Opening HDF5 output file "
                                     "on data output port %d", data_port);
@@ -130,7 +130,7 @@ int IOStreamedHDF5_Write (const cGH *GH, int vindex, const char *alias)
   /* close the file */
   if (file >= 0)
   {
-    if (verbose)
+    if (CCTK_Equals (verbose, "full"))
     {
       CCTK_INFO ("Closing HDF5 output file from this iteration");
     }
diff --git a/src/ioStreamedHDF5GH.h b/src/ioStreamedHDF5GH.h
index 0f6ae79..f8dc2c7 100644
--- a/src/ioStreamedHDF5GH.h
+++ b/src/ioStreamedHDF5GH.h
@@ -10,7 +10,7 @@
 #ifndef _IOSTREAMEDHDF5_IOSTREAMEDHDF5GH_H_
 #define _IOSTREAMEDHDF5_IOSTREAMEDHDF5GH_H_
 
-#include "BetaThorns/IOHDF5Util/src/ioHDF5UtilGH.h"
+#include "CactusPUGHIO/IOHDF5Util/src/ioHDF5UtilGH.h"
 
 
 /* IOStreamedHDF5 GH extension structure */