H5MATH(1)

💅 H5MATH(1) — like, the h5math page from the h5utils fam ✨

okay bestie, buckle up, because this one is a whole vibe 🌈

🌸 NAME 🌸

h5math — combine/create HDF5 files with math expressions, fr fr 🧮💖

🎀 SYNOPSIS 🎀

h5math [OPTION]... OUTPUT-HDF5FILE [INPUT-HDF5FILES...]

✨ DESCRIPTION ✨

so h5math takes literally any number of HDF5 files as input, plus a mathematical expression, and smushes them together to make a brand-new HDF5 file. it's giving chef's kiss 🔥

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. iconic institution behavior, no cap 👑

a single h5 file can contain multiple data sets, and by default h5math creates a dataset called "h5math" — but you can change that with the -d option, or by using the syntax HDF5FILE:DATASET. the -a option lets you append new datasets to an existing HDF5 file. same syntax applies for specifying the dataset in the input file(s); by default, the first dataset (alphabetically) is used. alphabetically! not by vibes 📚

here's a lil example of h5math in the wild, so you can see the vision:

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. honestly so clean 🫶

so besides 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, she's minding her business 💅), 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. no mixing and matching, bestie, that's not the vibe today 🚫

if there are no input files, and you're 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". main character energy, honestly ✨

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. slicing is lowkey underrated 🍰

---

🔥 OPTIONS 🔥

• -h — display help on the command-line options and usage. when in doubt, -h it out 🫶
• -V — print the version number and copyright info for h5math. know your roots 👑
• -v — verbose output. she'll tell you what she's doing, and honestly? we love a transparent queen 😭
• -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. so, append yes, but same-name dataset? she's getting replaced, periodt 💀
• -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. shoutout libmatheval, the real MVP 🧮✨

• -f filename — name of a text file to read the expression from, if no -e expression is specified. defaults to stdin. yes, stdin is the default, she's chill like that 🌸
• -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. slicing, slicing, slicing 🍓
• -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.) and yes, -0x0 really is the compact flex 💅

this also shifts the origin of the x/y/z variables in the expression so that 0 is the center of the dataset. so everything's centered, everything's balanced, we love a symmetrical moment 🦋

• -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. normalized coordinates!! she's fancy 🌈

-r does not affect the coordinates used for slices, which are always integers. integers only, no decimals allowed at the slice party 🙈

• -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. any dimensionality!! go wild 🎀
• -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). HDF5FILE:DATASET said "I'm the captain now" 👑

⚠️ ok real talk, the DESCRIPTION says the default output dataset is "h5math" and this option says it's "data" by default. that's literally what the page says, so we're reporting it exactly like that — don't come for me, I'm just the messenger 💀

---

💀 BUGS 💀

send bug reports to S. G. Johnson, stevenj@alum.mit.edu. he's ready for your emails, bestie 📧

👑 AUTHORS 👑

written by Steven G. Johnson. Copyright (c) 2005 by the Massachusetts Institute of Technology. MIT said "we invented this" and honestly? valid 🎓✨

---

and that's the whole page, bestie 🫶 this lil manual comes from h5utils, dated May 23, 2005 — vintage but still slaying 💜💅