• full name: tenpy.tools.hdf5_io

  • parent module: tenpy.tools

  • type: module


Inheritance diagram of tenpy.tools.hdf5_io


Interface specification for a class to be exportable to our HDF5 format.


Placeholder for a dataset/group to be ignored during both loading and saving.

Hdf5Loader(h5group[, ignore_unknown, exclude])

Class to load and import object from a HDF5 file.

Hdf5Saver(h5group[, format_selection])

Class to save simple enough objects into a HDF5 file.



This exception is raised when something went wrong during export to hdf5.


Common base class for errors regarding our HDF5 format.


This exception is raised when something went wrong during import from hdf5.


find_global(module, qualified_name)

Get the object of the qualified_name in a given python module.


Load data from file with given filename.

load_from_hdf5(h5group[, path, ...])

Load an object from hdf5 file or group.

save(data, filename[, mode])

Save data to file with given filename.

save_to_hdf5(h5group, obj[, path])

Save an object obj into a hdf5 file or group.


Determine if name is a valid HDF5 path component.

Module description

Tools to save and load data (from TeNPy) to disk.


This module is maintained in the repository https://github.com/tenpy/hdf5_io.git

See Saving to disk: input/output for a motivation and specification of the HDF5 format implemented below. .. online at https://tenpy.readthedocs.io/en/latest/intro/input_output.html

The functions save() and load() are convenience functions for saving and loading quite general python objects (like dictionaries) to/from files, guessing the file type (and hence protocol for reading/writing) from the file ending.

On top of that, this function provides support for saving python objects to [HDF5] files with the Hdf5Saver and Hdf5Loader classes and the wrapper functions save_to_hdf5(), load_from_hdf5().


To use the export/import features to HDF5, you need to install the h5py python package (and hence some version of the HDF5 library).


Like loading a pickle file, loading data from a manipulated HDF5 file with the functions provided below has the potential to cause arbitrary code execution. Only load data from trusted sources!

Global module constants used for our HDF5 format

Names of HDF5 attributes:

tenpy.tools.hdf5_io.ATTR_TYPE = 'type'

Attribute name for type of the saved object, should be one of the REPR_*

tenpy.tools.hdf5_io.ATTR_CLASS = 'class'

Attribute name for the class name of an HDF5Exportable

tenpy.tools.hdf5_io.ATTR_MODULE = 'module'

Attribute name for the module where ATTR_CLASS can be retrieved

tenpy.tools.hdf5_io.ATTR_LEN = 'len'

Attribute name for the length of iterables, e.g, list, tuple

tenpy.tools.hdf5_io.ATTR_FORMAT = 'format'

indicates the ATTR_TYPE format used by Hdf5Exportable

Names for the ATTR_TYPE attribute:

tenpy.tools.hdf5_io.REPR_HDF5EXPORTABLE = 'instance'

saved object is instance of a user-defined class following the Hdf5Exportable style.

tenpy.tools.hdf5_io.REPR_ARRAY = 'array'

saved object represents a (numpy) array

tenpy.tools.hdf5_io.REPR_MASKED_ARRAY = 'masked_array'

saved object represents a masked (numpy) array

tenpy.tools.hdf5_io.REPR_INT = 'int'

saved object represents a (python) int

tenpy.tools.hdf5_io.REPR_INT_AS_STR = 'int_as_str'

saved object represents int > 2^64 as (base-10) string

tenpy.tools.hdf5_io.REPR_FLOAT = 'float'

saved object represents a (python) float

tenpy.tools.hdf5_io.REPR_STR = 'str'

saved object represents a (python unicode) string

tenpy.tools.hdf5_io.REPR_BYTES = 'bytes'

saved object represents a string of bytes without any encoding

tenpy.tools.hdf5_io.REPR_COMPLEX = 'complex'

saved object represents a complex number

tenpy.tools.hdf5_io.REPR_INT64 = 'np.int64'

saved object represents a np.int64

tenpy.tools.hdf5_io.REPR_FLOAT64 = 'np.float64'

saved object represents a np.float64

tenpy.tools.hdf5_io.REPR_INT32 = 'np.int32'

saved object represents a np.int32

tenpy.tools.hdf5_io.REPR_FLOAT32 = 'np.float32'

saved object represents a np.float32

tenpy.tools.hdf5_io.REPR_BOOL = 'bool'

saved object represents a boolean

tenpy.tools.hdf5_io.REPR_NONE = 'None'

saved object is None

tenpy.tools.hdf5_io.REPR_RANGE = 'range'

saved object is a range

tenpy.tools.hdf5_io.REPR_LIST = 'list'

saved object represents a list

tenpy.tools.hdf5_io.REPR_TUPLE = 'tuple'

saved object represents a tuple

tenpy.tools.hdf5_io.REPR_SET = 'set'

saved object represents a set

tenpy.tools.hdf5_io.REPR_DICT_GENERAL = 'dict'

saved object represents a dict with complicated keys

tenpy.tools.hdf5_io.REPR_DICT_SIMPLE = 'simple_dict'

saved object represents a dict with simple keys

tenpy.tools.hdf5_io.REPR_DTYPE = 'dtype'

saved object represents a np.dtype

tenpy.tools.hdf5_io.REPR_IGNORED = 'ignore'

ignore the object/dataset during loading and saving

tenpy.tools.hdf5_io.TYPES_FOR_HDF5_DATASETS = ((<class 'numpy.ndarray'>, 'array'), (<class 'int'>, 'int'), (<class 'float'>, 'float'), (<class 'str'>, 'str'), (<class 'bytes'>, 'bytes'), (<class 'complex'>, 'complex'), (<class 'numpy.int64'>, 'np.int64'), (<class 'numpy.float64'>, 'np.float64'), (<class 'numpy.complex128'>, 'np.complex128'), (<class 'numpy.int32'>, 'np.int32'), (<class 'numpy.float32'>, 'np.float32'), (<class 'numpy.complex64'>, 'np.complex64'), (<class 'numpy.bool'>, 'bool'), (<class 'bool'>, 'bool'))

tuple of (type, type_repr) which h5py can save as datasets; one entry for each type.