Ubuntu Manpage: mpb-data - transformations of HDF5 files output by MPB

NAME

       mpb-data - transformations of HDF5 files output by MPB

SYNOPSIS

       mpb-data [OPTION]... [HDF5FILE]...

DESCRIPTION

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

OPTIONS

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

BUGS

       Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.

AUTHORS