From b680f5e2cd952c64e5fc3069dcadb507fc261151 Mon Sep 17 00:00:00 2001 From: tradke Date: Tue, 28 May 2002 14:57:55 +0000 Subject: 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/IOStreamedHDF5/trunk@92 0888f3d4-9f52-45d2-93bc-d00801ff5e46 --- doc/documentation.tex | 176 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 132 insertions(+), 44 deletions(-) diff --git a/doc/documentation.tex b/doc/documentation.tex index 7741cc6..71dc4d8 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -14,56 +14,19 @@ 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 -config HDF5=yes - [HDF5_DIR=] -\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} +\section{Purpose} % 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.\\ +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 streamed as serialized HDF5 files over sockets to any connected client. +Such datafiles can be used by appropriate programs for further postprocessing +(eg. remote visualization). 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 @@ -71,6 +34,100 @@ out as a single dataset. Parallel streaming from multiple processors is not supported yet. +\section{{\bf IOStreamedHDF5} Parameters} + +Parameters to control the {\tt IOStreamedHDF5} I/O method are: +\begin{itemize} + \item {\tt IOStreamedHDF5::out\_every} (steerable)\\ + How often to do periodic {\tt IOStreamedHDF5} 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 IOStreamedHDF5::out\_vars} parameter. + \item {\tt IOStreamedHDF5::out\_vars} (steerable)\\ + The list of variables to output using the {\bf IOStreamedHDF5} I/O method. + The variables must be given by their fully qualified variable or group + name. The special keyword {\it all} requests {\tt IOStreamedHDF5} 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{IOStreamedHDF5_output_hyperslabs} for details). +\end{itemize} + + +\section{Output of Hyperslab Data} +\label{IOStreamedHDF5_output_hyperslabs} + +By default, thorn {\bf IOStreamedHDF5} 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. + +Hyperslab parameters can be set for individual variables using an option string +appended to the variables' full names in the {\tt IOStreamedHDF5::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 IOStreamedHDF5::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} + IOStreamedHDF5::out_every = 1 + IOStreamedHDF5::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} + +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} Thorn {\bf IOStreamedHDF5} can also be used to create HDF5 checkpoints and @@ -79,7 +136,9 @@ 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. +during evolution, or at termination. Checkpointing for thorn {\bf IOStreamedHDF5} +is enabled by setting the parameter {\tt IOStreamedHDF5::checkpoint = "yes"}. + A recovery routine is registered with thorn {\bf IOUtil} in order to restart a new simulation from a given HDF5 checkpoint. @@ -88,6 +147,35 @@ parameters of thorn {\bf IOUtil} (for a description of these parameters please refer to this thorn's documentation). +\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 -config HDF5=yes + [HDF5_DIR=] +\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. + +Note that thorn {\bf IOStreamedHDF5} uses the {\tt Stream Virtual File Driver} +of the HDF5 library as its low-level driver. 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}. +% +% + + % % Automatically created from the ccl files % Do not worry for now. -- cgit v1.2.3