Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
H5MATH(1)			    h5utils			     H5MATH(1)

       h5math -	combine/create HDF5 files with math expressions


       h5math takes any	number of HDF5 files as	input, along with a mathemati-
       cal 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 Univer-
       sity 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  re-
       ferred 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"	 vari-
       ables  (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 coordi-
       nates 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	 over-
	      written, 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  op-
	      erators  and  mathematical  functions  (+, sin, etc.) being sup-
	      ported.  This functionality is provided (and its features	deter-
	      mined) by	GNU libmatheval.

       -f filename
	      Name  of	a  text	file to	read the expression from, if no	-e ex-
	      pression is specified.  Defaults to stdin.

       -x ix, -y iy, -z	iz, -t it
	      This tells h5math	to use a particular slice  of  a  multi-dimen-
	      sional  dataset.	e.g.  -x uses the subset (with one less	dimen-
	      sion) 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  ex-
	      pression 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 ex-
	      pression,	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 man-
	      ually  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.

h5utils				 May 23, 2005			     H5MATH(1)


Want to link to this manual page? Use this URL:

home | help