Usage¶

Pending

Focus on command line usage, probably

Probably worth mentioning aspects of API usage too, though.

API¶

API intro. Two functions, three constants classes. API functions work directly on files on disk; no options for in-memory-only (de)compression as yet

Functions

h5cube.cube_to_h5(cubepath, *, ...)¶

[Docstring]

h5cube.h5_to_cube(h5path, *, delsrc=False, prec=5)¶

[Docstring]

Less error/syntax checking here since presumably the data was parsed for validity when the .h5cube file was created.

Constants Classes

class h5cube.H5¶

Names of .h5cube datasets and informational constants

Array shapes and types are those of the data stored in .h5cube files.

COMMENT1 = 'COMMENT1'¶

First comment line

COMMENT2 = 'COMMENT2'¶

Second comment line

DSET_IDS = 'DSET_IDS'¶

If NATOMS is negative, a length-NUM_DSETS vector of int. Else, an empty float np.array

GEOM = 'GEOM'¶

System geometry. 3N x 5 float. Each line contains the atomic number \(\mathsf{[0]}\), atomic charge \(\mathsf{[1]}\) (typically – always? – equal to the atomic number), and position \(\mathsf{[2:]}\) of each atom

LOGDATA = 'LOGDATA'¶

Base-10 logarithms of the absolute values of the volumetric data points (\(0.0\) for zero values). Dimension is identical to that of SIGNS.

NATOMS = 'NATOMS'¶

Number of atoms. Scalar int. Negative if dataset ID values are present.

NUM_DSETS = 'NUM_DSETS'¶

If NATOMS is negative, contains a scalar int with the length of DSET_IDS.

ORIGIN = 'ORIGIN'¶

Geometry origin vector. Length-3 float.

SIGNS = 'SIGNS'¶

Algebraic signs of the volumetric data points (\(0.0\) for zero values). For non-orbital CUBE files, XAXIS[0] x YAXIS[0] x ZAXIS[0] array of float. For orbital CUBEs, XAXIS[0] x YAXIS[0] x ZAXIS[0] x NUM_DSETS array of float.

VAL_NOT_ORBFILE = 0¶

Value to be stored in NUM_DSETS when compressing non-orbital CUBE files.

XAXIS = 'XAXIS'¶

x-axis voxel dimension \(\mathsf{[0]}\) and vector \(\mathsf{[1\!:]}\). Length-4 float.

YAXIS = 'YAXIS'¶

y-axis voxel dimension \(\mathsf{[0]}\) and vector \(\mathsf{[1\!:]}\). Length-4 float.

ZAXIS = 'ZAXIS'¶

z-axis voxel dimension \(\mathsf{[0]}\) and vector \(\mathsf{[1\!:]}\). Length-4 float.

class h5cube.DEF¶

Default values for (de)compression option parameters.

No default is given for the signed parameter to cube_to_h5() since it is irrelevant when THRESH is False.

Similarly, since minmax and isofactor are irrelevant when THRESH is False, their default None values are specified directly in the cube_to_h5() signature.

CLIPZERO = False¶

Default is to clip small values to the thresholding limit with the smallest magnitude, as opposed to coercing to zero.

Todo

Add link to User’s Guide explanation of value vs zero clipping

COMP = 9¶

Default gzip compression level.

DEL = False¶

Default is not to delete source file in both compression and decompression.

PREC = 5¶

Default output precision in decompressed CUBE file.

THRESH = False¶

Default is not to threshold the CUBE data when compressing.

TRUNC = 5¶

Default volumetric data truncation length during compression.

Todo

Add link to User’s Guide explanation of truncation when done.

class h5cube.EXIT¶

Exit codes for command line invocations.

CMDLINE = 2¶

Exit with invalid command line parameters

FILEREAD = 4¶

Exit with error due to failed file read

FILEWRITE = 8¶

Exit with error due to failed file write

GENERIC = 1¶

Catch-all exit with error

OK = 0¶

Exit success

Gaussian CUBE File Format¶

Layout of CUBE format

h5cube File Specification¶

h5py dataset names, types, and array sizes (where relevant) for the stored data in h5cube files

Dependencies¶

h5py and numpy required for core functionality

Once implemented, tqdm optional for status bars

References¶

Refs list...

TODO List¶

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/h5cube/checkouts/v.doc/h5cube/h5cube.py:docstring of h5cube.DEF.CLIPZERO, line 4.)

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/h5cube/checkouts/v.doc/h5cube/h5cube.py:docstring of h5cube.DEF.TRUNC, line 3.)