Creates loggable quantites for classes of type Loggable.


Logs HOOMD-blue operation data and custom quantities.


Enum that marks all accepted logger types.


class hoomd.logging.Logger(flags=None, only_default=True)

Logs HOOMD-blue operation data and custom quantities.

The Logger class provides an intermediatary between a back end such as the hoomd.write.Table and many of HOOMD-blue’s object (as most objects are loggable). The Logger class makes use of namespaces which denote where a logged quantity fits in. For example internally all loggable quantities are ordered by the module and class them come from. For instance, the hoomd.md.pair.LJ class has a namespace ('md', 'pair', 'LJ'). This applies to all loggable internal objects in HOOMD-blue. This ensures that logged quantities remain unambigious. To add a loggable object’s quantities two methods exist Logger.add and the += operator. Here we show an example using the += operator.


logger = hoomd.logging.Logger()
lj = md.pair.lj(nlist)
# Log all default quantites of the lj object
logger += lj
logger = hoomd.logging.Logger(flags=['scalar'])
# Log all default scalar quantites of the lj object
logger += lj

The Logger class also supports user specified quantities using namespaces as well.


logger = hoomd.logging.Logger()
# Add quantity to ('custom', 'name') namespace
logger[('custom', 'name')] = (lambda: 42, 'scalar')
# Add quantity to ('custom_name',) namespace
logger[('custom_name',)] = (lambda: 43, 'scalar')

Logger objects support two ways of discriminating what loggable quantities they will accept: flags and only_default (the constructor arguements). Both of these are static meaning that once instantiated a Logger object will not change the values of these two properties. flags determines what if any types of loggable quantities (see hoomd.logging.TypeFlags) are appropriate for a given Logger object. This helps logging back ends determine if a Logger object is compatible. The only_default flag is mainly a convenience by allowing quantities not commonly logged (but available) to be passed over unless explicitly asked for. You can override the only_default flag by explicitly listing the quantities you want in Logger.add, but the same is not true with regards to flags.


The logger provides a way for users to create their own logger back ends if they wish. In making a custom logger back end, understanding the intermediate representation is key. To get an introduction see hoomd.logging.Logger.log. To understand the various flags available to specify logged quantities, see hoomd.logging.TypeFlags. To integrate with hoomd.Operations the back end should be a subclass of hoomd.custom.Action and used with hoomd.writer.CustomWriter.

  • flags (list of str, optional) – A list of string flags (list of flags can be found in hoomd.logging.TypeFlags). These are the only types of loggable quantities that can be logged by this logger. Defaults to allowing every type.

  • only_default (bool, optional) – Whether to log only quantities that are logged by “default”, defaults to True. This mostly means that performance centric loggable quantities will be passed over when logging when false.


Add quantities from object or list of objects to logger.

Adds all quantities compatible with given flags and default value.


logger += lj
logger += [lj, harmonic_bonds]

Remove log entries for a list of quantities or objects.


logger -= ('md', 'pair', 'lj')
logger -= [('md', 'pair', 'lj', 'energy'),
           ('md', 'pair', 'lj', 'forces')]
logger -= lj
logger -= [lj, harmonic_bonds]
__setitem__(namespace, value)

Allows user specified loggable quantities.

  • namespace (tuple[str,] or str) – key or nested key to determine where to store logged quantity.

  • value (tuple[Callable, str] or tuple[object, str, str]) – Either a tuple with a callable and the hoomd.logging.TypeFlags object or associated string or a object with a method/property name and flag. If using a method it should not take arguments or have defaults for all arguments.

add(obj, quantities=None)

Add loggables from obj to logger. Returns the used namespaces.

  • obj (object of class of type Loggable) – class of type loggable to add loggable quantities from.

  • quantities (Sequence[str]) – list of str names of quantities to log.


A list of namespaces that were

added to the logger.

Return type


property flags

The enum representing the acceptable flags for the Logger object.




Get a nested dictionary of the current values for logged quantities.

The nested dictionary consist of one level for each element of a namespace. The logged value and flag for the namespace ('example', 'namespace') would be accessible in the returned dictionary via logger.log()['example']['namespace'].


A nested dictionary of the current logged

quantities. The end values are (value, flag) pairs which hold the value along with its associated hoomd.logging.TypeFlags flag represented as a string (to get the hoomd.logging.TypeFlags enum value use TypeFlags[flag].

Return type


property only_default

Whether the logger object should only grab default loggable quantites.



remove(obj=None, quantities=None)

Remove specified quantities from the logger.

  • obj (object of class of type Loggable, optional) – Object to remove quantities from. If quantities is None, obj must be set. If obj is set and quantities is None, all logged quanties from obj will be removed from the logger.

  • quantities (Sequence[tuple]) – a sequence of namespaces to remove from the logger. If specified with obj only remove quantities listed that are exposed from obj. If obj is None, then quantities must be given.

property string_flags

A list of the string names of the allowed flags for logging.


list of str

class hoomd.logging.TypeFlags(value)

Enum that marks all accepted logger types.

This class does not need to be used by users directly. We directly convert from strings to the enum wherever necessary in the API. This class is documented to show users what types of quantities can be logged, and what flags to use for limiting what data is logged, user specified logged quantites, and custom actions (hoomd.custom.Action).


scalar: float or int objects (i.e. numbers)

sequence: sequence (e.g. list, tuple, numpy.ndarray) of numbers of the same type.

string: a single Python str object

strings: a sequence of Python str objects

object: any Python object outside a sequence, string, or scalar.

angle: per-angle quantity

bond: per-bond quantity

constraint: per-constraint quantity

dihedral: per-dihedral quantity

improper: per-improper quantity

pair: per-pair quantity

particle: per-particle quantity

state: internal flag for specifying object’s internal state

ALL: a combination of all other flags

NONE: represents no flag

ALL = 8191
NONE = 0
angle = 32
classmethod any(flags=None)

Return a TypeFlags enum representing any of the given flags.

  • flags (list[str] or list[TypeFlags]) – A list of str or

  • objects that should be represented by the returned (TypeFlags) –

  • object. (TypeFlags) –


the TypeFlags object that represents any of the given flags.

Return type


bond = 64
constraint = 128
dihedral = 256
improper = 512
object = 16
pair = 1024
particle = 2048
scalar = 1
sequence = 2
state = 4096
string = 4
strings = 8
hoomd.logging.log(func=None, *, is_property=True, flag='scalar', default=True)

Creates loggable quantites for classes of type Loggable.

For users this should be used with hoomd.custom.Action for exposing loggable quantities from a custom action.

  • func (method) – class method to make loggable. If using non-default arguments, func should not be set.

  • is_property (bool, optional) – Whether to make the method a property, defaults to True. Argument position only

  • flag (str, optional) – The string represention of the type of loggable quantity, defaults to ‘scalar’. See hoomd.logging.TypeFlags for available types. Argument position only

  • default (bool, optional) – Whether the quantity should be logged by default, defaults to True. This is orthogonal to the loggable quantity’s type. An example would be performance orientated loggable quantities. Many users may not want to log such quantities even when logging other quantities of that type. The default flag allows for these to be pass over by hoomd.logging.Logger objects by default.


The namespace (where the loggable object is stored in the hoomd.logging.Logger object’s nested dictionary, is determined by the module/script and class name the loggable class comes from. In creating subclasses of hoomd.custom.Action, for instance, if the module the subclass is defined in is user.custom.action and the class name is Foo then the namespace used will be ('user', 'custom', 'action', 'Foo'). This helps to prevent naming conflicts, and automate the logging specification for developers and users.