From 89a1b3fb7ab8d064f54f0c9fedfc84ab237c5804 Mon Sep 17 00:00:00 2001 From: tradke Date: Tue, 28 May 2002 14:57:54 +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/IOFlexIO/trunk@250 ebee0441-1374-4afa-a3b5-247f3ba15b9a --- doc/documentation.tex | 173 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 135 insertions(+), 38 deletions(-) diff --git a/doc/documentation.tex b/doc/documentation.tex index e0f91c5..fadcd46 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -31,7 +31,34 @@ Such datafiles can be used for further postprocessing (eg. visualization) or fed back into Cactus via the filereader capabilities of thorn IOUtil.\\[3ex] -\subsection{Parallel File I/O} +\section{{\bf IOFlexIO} Parameters} + +Parameters to control the {\tt IOFlexIO} I/O method are: +\begin{itemize} + \item {\tt IOFlexIO::out\_every} (steerable)\\ + How often to do periodic {\tt IOFlexIO} 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 IOFlexIO::out\_vars} parameter. + \item {\tt IOFlexIO::out\_vars} (steerable)\\ + The list of variables to output using the {\bf IOFlexIO} I/O method. + The variables must be given by their fully qualified variable or group + name. The special keyword {\it all} requests {\tt IOFlexIO} 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{IOFlexIO_output_hyperslabs} for details). + \item {\tt IOFlexIO::out\_dir}\\ + The directory in which to place the {\tt IOFlexIO} output files. + If the directory doesn't exist at startup it will be created.\\ + If this parameter is set to an empty string {\tt IOFlexIO} 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 {\bf IOFlexIO} @@ -50,30 +77,9 @@ will output distributed data either \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 IOFlexIO/src/util/}.\\ - -To build the recombiner just do a - -\begin{verbatim} - make -utils -\end{verbatim} - -in the Cactus toplevel directory. The recombiner executable {\tt -ieee\_recombiner} will be placed in the {\tt exe//} -subdirectory.\\ -Its usage is: -\begin{verbatim} -~/Cactus/exe/wave> ieee_recombiner - -------------------------------- -Cactus 4 IEEEIO File Recombiner -------------------------------- - -Usage: recombiner - eg, recombiner alp_3d.file_0.ieee alp_3d.ieee - -\end{verbatim} +into a single unchunked file using the recombiner utility program. +See section \ref{IOFlexIO_utility_programs} for information how to build the +recombiner program. If you have a lot of different variables to recombine you can use the following Bourne shell commands to recombine them. @@ -95,27 +101,99 @@ the current working directory: \vspace*{3ex} -\subsection{Checkpointing \& Recovery} +\section{Output of Hyperslab Data} +\label{IOFlexIO_output_hyperslabs} + +By default, thorn {\bf IOFlexIO} 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 IOFlexIO::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 IOFlexIO::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} + IOFlexIO::out_every = 1 + IOFlexIO::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 IOFlexIO} can also be used for creating IEEEIO checkpoint files and -recovering from such files later on.\\ +recovering from such files later on. Checkpoint routines are scheduled at several timebins so that you can save the current state of your simulation atfer the initial data phase, -during evolution, or at termination. +during evolution, or at termination. Checkpointing for thorn {\bf IOFlexIO} +is enabled by setting the parameter {\tt IOFlexIO::checkpoint = "yes"}. + A recovery routine is registered with thorn IOUtil in order to restart a new simulation from a given {\bf IOFlexIO} 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). -\section{Comments} - -\subsection{Importing external data into Cactus with {\bf IOFlexIO}} +\section{Importing External Data into Cactus with {\bf IOFlexIO}} In order to import external data into Cactus (eg. to initialize some variable) you first need to convert this data into an IEEEIO datafile which then can be @@ -173,27 +251,46 @@ 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 {\bf IOFlexIO}} +\section{Utility programs provided by {\bf IOFlexIO}} % -In addition to the IEEEIO recombiner program, thorn {\bf IOFlexIO} also provides -some other utilities which can be build the same way: +\label{IOFlexIO_utility_programs} + +Thorn {\bf IOFlexIO} provides the following utility programs: % \begin{itemize} - \item {\tt ieee\_merge.c}\\ + \item {\tt ieee\_recombiner}\\ + Recombines chunked IEEEIO datafile(s) into a single unchunked IEEEIO datafile. + \item {\tt ieee\_merge}\\ Merges the contents of its input files into a single output file.\\ This might be useful for {\bf IOFlexIO} datafile created by different runs. - \item {\tt ieee\_extract.c}\\ + \item {\tt ieee\_extract}\\ Extracts a hyperslab from all datasets of the input file.\\ You can select a hyperslab by specifying an origin and an extent (eg. 128x128x128+32+32+32 selects a 128-cubed hyperslab with origin (32, 32, 32)). - \item {\tt ieee\_convert\_from\_cactus3.c}\\ + \item {\tt ieee\_convert\_from\_cactus3}\\ Converts Cactus 3 IEEEIO datafiles into Cactus 4.\\ It also takes a textfile as input with mapping information for variable names. + \item {\tt ioinfo}\\ + Displays the contents of an IEEEIO datafile (number of datasets stored, + datatype, rank, dimenions, and number of attributes for each dataset). \end{itemize} % +All utility programs are located in the {\tt src/util/} subdirectory of thorn +{\bf IOFlexIO}. To build the utilities just do a + +\begin{verbatim} + make -utils +\end{verbatim} + +in the Cactus toplevel directory. The executables will then be placed in the +{\tt exe//} 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} -- cgit v1.2.3