NAME
h5math - combine/create HDF5 files with math expressions
SYNOPSIS
h5math [OPTION]... OUTPUT-HDF5FILE [INPUT-HDF5FILES...]
DESCRIPTION
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 h5 file can
contain multiple data sets; by default, h5math creates a dataset called
"h5math", but this can be changed via the -d option, or by using the
syntax HDF5FILE:DATASET. The -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:
h5math -e "d1 + 2*d2" out.h5 foo.h5 bar.h5:blah
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 -e), the first input dataset (from left to right) is
referred to as d1, the second as d2, 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 -0 option will
change the x/y/z origin to the center of the dataset (t is unaffected),
and the -r res option will specify the "resolution", dividing the x/y/z
coordinates by res.
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 -n size option, where
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 -xyzt options.
OPTIONS
-h Display help on the command-line options and usage.
-V Print the version number and copyright info for h5math.
-v Verbose output.
-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.
-e expression
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.
-f filename
Name of a text file to read the expression from, if no -e
expression is specified. Defaults to stdin.
-x ix, -y iy, -z iz, -t it
This tells h5math to use a particular slice of a multi-
dimensional dataset. e.g. -x uses the subset (with one less
dimension) at an x index of 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 -t option specifies a slice in the last
dimension, whichever that might be. See also the -0 option to
shift the origin of the x/y/z slice coordinates to the dataset
center.
-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.
(-t 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.
-r res Use a resolution res for x/y/z (but not t) variables in the
expression, so that the data "grid" coordinates are divided by
res. The default res is 1.
For example, if the x dimension has 21 grid steps, setting a res
of 20 will mean that x variables in the expression run from 0.0
to 1.0 (or -0.5 to 0.5 if -0 is specified), instead of 0 to 20.
-r does not affect the coordinates used for slices, which are
always integers.
-n size
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: size is of the form MxNxLx... (with
M, N, L being integers) and may be of any dimensionality.
-d name
Write to dataset name in the output; otherwise, the output
dataset is called "data" by default. Also use dataset name in
the input; otherwise, the first input dataset (alphabetically)
in a file is used. Alternatively, use the syntax
HDF5FILE:DATASET (which overrides the -d option).
BUGS
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
AUTHORS
Written by Steven G. Johnson. Copyright (c) 2005 by the Massachusetts
Institute of Technology.