hoomd.hdf5

Overview

hoomd.hdf5.File
hoomd.hdf5.log

Details

Commands that require the h5py package at runtime.

All commands that are part of this module require the h5py package a python API for hdf5. In addition, this module is an opt-in. As a consequence you’ll need to import it via import hoomd.hdf5 before you can use any command.

class hoomd.hdf5.File(*args, **kwargs)

Thin wrapper of the h5py.File class.

This class ensures, that opening and close operations within a context manager are only executed on the root MPI rank.

Note

This class can be used like the h5py.File class, but the user has to make sure that all operations are only executed on the root rank.

class hoomd.hdf5.log(h5file, period, quantities=[], matrix_quantities=[], phase=0)

Log a number of calculated quantities or matrices to a hdf5 file.

Parameters:
  • h5file (hoomd.hdf5.File) – Instance describing the opened h5file.
  • period (int) – Quantities are logged every period time steps
  • quantities (list) – Quantities to log.
  • matrix_quantities (list) – Matrix quantities to log.
  • overwrite (bool) – When False (the default) the existing log will be append. When True the file will be overwritten.
  • phase (int) – When -1, start on the current time step. When >= 0 execute on steps where (step +phase) % period == 0.

For details on the loggable quantities refer hoomd.analyze.log for details.

The non-matrix quantities are combined in an array ‘quantities’ in the hdf5 file. The attributes list all the names of the logged quantities and their position in the file.

Matrix quantities are logged as a separate data set each in the file. The name of the data set corresponds to the name of the quantity. The first dimension of the data set is counting the logged time step. The other dimension correspond to the dimensions of the logged matrix.

Note

The number and order of non-matrix quantities cannot change compared to data which is already stored in the hdf5 file. As a result, if you append to a file make sure you are logging the same values as before. In addition, also during a run with multiple hoomd.run() commands the logged values can not change.

Note

The dimensions of logged matrix quantities cannot change compared to a matrix with same name stored in the file. This applies for appending files as well as during a single simulation run.

Examples:

with hoomd.hdf5.File("log.h5", "w") as h5file:
   #general setup

   log = hoomd.hdf5.log(filename='log.h5', quantities=['my_quantity', 'cosm'], matrix_quantities = ['random_matrix'], period=100)
   log.register_callback('my_quantity', lambda timestep: timestep**2)
   log.register_callback('cosm', lambda timestep: math.cos(logger.query('my_quantity')))
   def random_matrix(timestep):
      return numpy.random.rand(23, 56)
   log.register_callback('random_matrix', random_matrix, True)
   #more setup
   run(200)
disable()

Disable the logger.

Examples:

logger.disable()

Executing the disable command will remove the logger from the system. Any hoomd.run() command executed after disabling the logger will not use that logger during the simulation. A disabled logger can be re-enabled with enable().

enable()

Enables the logger

Examples:

logger.enable()

See disable().

query(quantity, force_matrix=False)
Get the last logged value of a quantity which has been written to the file. If quantity is registered as a non-matrix quantity, its value is returned. If it is not registered as a non-matrix quantity, it is assumed to be a matrix quantity. If a quantity exists as non-matrix and matrix quantity with the same name, force_matrix can be used to obtain the matrix value.
Parameters:
  • quantity (str) – name of the quantity to query
  • force_matrix (bool) – the name of the quantity is

Note

Matrix quantities are not efficiently cached by the class, so calling this function multiple time, may not be efficient.

register_callback(name, callback, matrix=False)

Register a callback to produce a logged quantity.

Parameters:
  • name (str) – Name of the quantity
  • callback (callable) – A python callable object (i.e. a lambda, function, or class that implements __call__)
  • matrix (bool) – Is the callback a computing a matrix and thus returning a numpy array instead of a single float?

The callback method must take a single argument, the current timestep, and return a single floating point value to be logged. If the callback returns a matrix quantity the return value must be a numpy array constant dimensions of each call.

Note

One callback can query the value of another, but logged quantities are evaluated in order from left to right.

Examples:

log = hoomd.hdf5.log(filename='log.h5', quantities=['my_quantity', 'cosm'], matrix_quantities = ['random_matrix'], period=100)
log.register_callback('my_quantity', lambda timestep: timestep**2)
log.register_callback('cosm', lambda timestep: math.cos(logger.query('my_quantity')))
def random_matrix(timestep):
    return numpy.random.rand(23, 56)
log.register_callback('random_matrix', random_matrix, True)
set_params(quantities=None, matrix_quantities=None)

Change the parameters of the log.

Warning

Do not change the number or order of logged non-matrix quantities compared to values stored in the file.