.\" Copyright (c) 2005 Massachusetts Institute of Technology
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.TH H5MATH 1 "May 23, 2005" "h5utils" "h5utils"
.SH NAME
h5math \- combine/create HDF5 files with math expressions
.SH SYNOPSIS
.B h5math
[\fIOPTION\fR]... \fIOUTPUT-HDF5FILE\fR [\fIINPUT-HDF5FILES\fR...]
.SH DESCRIPTION
.PP
." Add any additional description here
h5math takes any number of HDF5 files as input, along with a mathematical
expression, and combines them to produce a new HDF5 file.

HDF5 is a free, portable binary format and supporting library developed
by the National Center for Supercomputing Applications at the University
of Illinois in Urbana-Champaign.  A single
.I h5
file can contain multiple data sets; by default,
.I h5math
creates a dataset called "h5math", but this can be changed via the
.B -d
option, or by using the syntax \fIHDF5FILE:DATASET\fR.  The
.B -a
option can be used to append new datasets to an existing HDF5 file.
The same syntax is used to specify the dataset used in the input
file(s); by default, the first dataset (alphabetically) is used.

A simple example of h5math's usage is:
.IP "" 4
h5math -e "d1 + 2*d2" out.h5 foo.h5 bar.h5:blah
.PP
which produces a new file, out.h5, by adding the first dataset in
foo.h5 with twice the "blah" dataset in bar.h5.  In the expression
(specified by \fB-e\fR), the first input dataset (from left to right)
is referred to as \fId1\fR, the second as \fId2\fR, and so on.

In addition to input datasets, you can also use the x/y/z coordinates
of each point in the expression, referenced by "x" "y" and "z"
variables (for the first three dimensions) as well as a "t" variable
that refers to the last dimension.  By default, these are integers starting at 0 at the corner of the dataset, but the
.B -0
option will change the x/y/z origin to the center of the dataset (t is
unaffected), and the
.B -r
.I res
option will specify the "resolution", dividing the x/y/z coordinates
by \fIres\fR.

All of the input datasets must have the same dimensions, which are
also the dimensions of the output.  If there are no input files, and
you are defining the output purely by a mathematical formula, you can
specify the dimensions of the output explicitly via the
.B -n
.I size
option, where
.I size
is e.g. "2x2x2".

Sometimes, however, you want to use only a smaller-dimensional "slice"
of multi-dimensional data.  To do this, you specify coordinates in one
(or more) slice dimension(s), via the
.B -xyzt
options.
.SH OPTIONS
.TP
.B -h
Display help on the command-line options and usage.
.TP
.B -V
Print the version number and copyright info for h5math.
.TP
.B -v
Verbose output.
.TP
.B -a
If the HDF5 output file already exists, append the data as a new
dataset rather than overwriting the file (the default behavior).  An
existing dataset of the same name within the file is overwritten,
however.
.TP
\fB\-e\fR \fIexpression\fR
Specify the mathematical expression that is used to construct the
output (generally in " quotes to group the expression as one item in
the shell), in terms of the variables for the input datasets and
the coordinates as described above.

Expressions use a C-like infix notation, with most standard operators
and mathematical functions (+, sin, etc.) being supported.  This
functionality is provided (and its features determined) by GNU libmatheval.
.TP
\fB\-f\fR \fIfilename\fR
Name of a text file to read the expression from, if no
.B -e
expression is specified.  Defaults to stdin.
.TP
\fB\-x\fR \fIix\fR, \fB\-y\fR \fIiy\fR, \fB\-z\fR \fIiz\fR, \fB\-t\fR \fIit\fR
This tells
.I h5math
to use a particular slice of a multi-dimensional dataset.  e.g.
.B -x
uses the subset (with one less dimension) at an x index of
.I ix
(where the indices run from zero to one less than the maximum index in
that direction).  Here, x/y/z correspond to the first/second/third
dimensions of the HDF5 dataset. The \fB\-t\fR option specifies a slice
in the last dimension, whichever that might be.  See also the
.B -0
option to shift the origin of the x/y/z slice coordinates to the
dataset center.
.TP
.B -0
Shift the origin of the x/y/z slice coordinates to the dataset center,
so that e.g. -0 -x 0 (or more compactly -0x0) returns the central x
plane of the dataset instead of the edge x plane.  (\fB\-t\fR
coordinates are not affected.)

This also shifts the origin of the x/y/z variables in the expression so
that 0 is the center of the dataset.
.TP
\fB\-r\fR \fIres\fR
Use a resolution
.I res
for x/y/z (but not t) variables in the expression, so that the data
"grid" coordinates are divided by \fIres\fR.  The default \fIres\fR is 1.

For example, if the x dimension has 21 grid steps, setting a \fIres\fR
of 20 will mean that x variables in the expression run from 0.0 to
1.0 (or -0.5 to 0.5 if \fB\-0\fR is specified), instead of 0 to 20.

.B -r
does not affect the coordinates used for slices, which are always integers.
.TP
\fB\-n\fR \fIsize\fR
The output dataset must be the same size as the input datasets.  If
there are no input datasets (if you are defining the output purely by
a formula), then you must specify the output size manually with this
option: \fIsize\fR is of the form MxNxLx... (with M, N, L being
integers) and may be of any dimensionality.
.TP
\fB\-d\fR \fIname\fR
Write to dataset
.I name
in the output; otherwise, the output dataset is called "data" by default.
Also use dataset
.I name
in the input; otherwise, the first input dataset (alphabetically) in a
file is used.  Alternatively, use the syntax \fIHDF5FILE:DATASET\fR
(which overrides the
.B -d
option).
.SH BUGS
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
.SH AUTHORS
Written by Steven G. Johnson.  Copyright (c) 2005 by the Massachusetts
Institute of Technology.