mpb-data - transformations of HDF5 files output by MPB
mpb-data [OPTION]... [HDF5FILE]...
mpb-data is a utility to perform additional processing and
transformations of HDF5 files output by MPB, the MIT Photonic-Bands program.
In particular, it is designed to make the output more amenable to
visualization by reformatting it into a rectangular grid, extending it to
multiple periods, and rescaling the data.
MIT Photonic Bands (MPB) is a free program to compute the band
structures (dispersion relations) and electromagnetic modes of periodic
dielectric structures.
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, mpb-data operates on all of
the MPB-produced datasets in the file, but this can be changed via the
-d option, or by using the syntax HDF5FILE:DATASET.
mpb-data writes its output datasets as additional datasets
in the input file(s), with "-new" appended to the dataset names.
Alternatively, it can write its output to a separate file, specified by the
-o option.
Note also that, by default, the output datasets are identical to
the input datasets; you must use one or more of the options below to specify
a transformation (e.g. the -r/-e and -n options are
very useful).
- -h
- Display help on the command-line options and usage.
- -V
- Print the version number and copyright info for mpb-data.
- -v
- Verbose output.
- -o file
- Write output datasets to file (for the first input file only)
rather than as additional datasets in the input file(s) (the
default).
- -r
- Output a rectangular cell with the same volume as the cell of the input
data. This option is particularly useful for visualizing data from
non-orthogonal unit cells (e.g. a triangular lattice), as otherwise the
data will appear skewed or warped in most graphics programs. This option
should almost always be accompanied by the -n option to ensure a
uniform resolution.
- -e x,y,z
- As the -r option, but also make the first axis of the output along
the x,y,z direction (in Cartesian coordinates) instead of along the
first lattice vector as for -r.
- -P phaseangle
- For complex-valued datasets, this option causes the output values to be
rotated by phaseangle degrees in the complex plane. That is, they
are multiplied by exp(2 pi i phaseangle / 360).
- -n n
- Output n grid points per lattice unit ("a"). This is
useful not only for interpolating to finer (or coarser) resolutions, but
also to ensure that the resolution is uniform in each direction (to
prevent the data from looking distorted when you visualize it).
- -x mx, -y
my, -z mz
- This tells mpb-data to output multiple periods in the corresponding
lattice directions. to use a particular slice of a two- or
three-dimensional dataset. e.g. -x 3.2 causes the output of 3.2
periods in the first lattice direction. The default is to output only a
single period.
- -m s
- Output s periods in each lattice direction; equivalent to:
-x s -y s -z s.
- -T
- The output has the first two dimensions (x and y) transposed. This is
useful in conjunction with the parallel (MPI) version of MPB, which for
performance reasons outputs all arrays with the first two dimensions
transposed. -T can undo this transposition.
- -p
- Pixellized output. Normally, the input data is linearly interpolated to
the output grid, but the -p option causes it to instead use the
nearest grid point in the input data. This is useful, for example, if you
want to study the discretization of the dielectric-function
representation.
- -d name
- Use dataset name from the input files; otherwise, the first dataset
from each file is used. Alternatively, use the syntax
HDF5FILE:DATASET, which allows you to specify a different dataset
for each file. You can use the h5ls command (included with hdf5) to
find the names of datasets within a file.
Note that this option is generally unnecessary, since mpb-data
can already find the relevant dataset(s) for files created by MPB. Also,
note that mpb-data treats the dataset specified by this option as a real
scalar dataset and does not include the exp(ikx) factors when extending
the dataset to multiple periods.
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
Written by Steven G. Johnson. Copyright (c) 1999-2012 by the
Massachusetts Institute of Technology.