Man Linux: Main Page and Category List


       h5math - combine/create HDF5 files with math expressions




       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.


       -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

       -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).


       Send bug reports to S. G. Johnson,


       Written  by Steven G. Johnson.  Copyright (c) 2005 by the Massachusetts
       Institute of Technology.