hoomd.logging¶

Overview

`log`	Creates loggable quantities for classes of type Loggable.
`modify_namespace`	Modify a class's namespace to a manually assigned one.
`Logger`	Logs HOOMD-blue operation data and custom quantities.
`LoggerCategories`	Enum that marks all accepted logger types.

Details

Logging infrastructure.

Use the Logger class to collect loggable quantities (e.g. kinetic temperature, pressure, per-particle energy) during the simulation run. Pass the Logger to a backend such as hoomd.write.GSD or hoomd.write.Table to write the logged values to a file.

See also

Tutorial: Logging

Tutorial: Custom Actions in Python

class hoomd.logging.LoggerCategories(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

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 categories to use for limiting what data is logged, user specified logged quantities, and custom actions (hoomd.custom.Action).

scalar¶: float or int object.

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.

ALL¶: A combination of all other categories.

NONE¶: Represents no category.

classmethod any(categories=None)¶

Return a LoggerCategories enum representing any of the categories.

Parameters: categories (list [str ] or list [LoggerCategories]) – A list of str or LoggerCategories objects that should be represented by the returned LoggerCategories object.
Returns: the LoggerCategories object that represents any of the given categories.
Return type: LoggerCategories

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

Logs HOOMD-blue operation data and custom quantities.

The Logger class provides an intermediary between a backend such as hoomd.write.GSD or hoomd.write.Table and loggable objects. The Logger class makes use of namespaces which organize logged quantities. For example internally all loggable quantities are ordered by the module and class they come from. For instance, the hoomd.md.pair.LJ class has a namespace ('md', 'pair', 'LJ'). This ensures that logged quantities remain unambiguous. Use add or the += operator to add loggable objects to the Logger.

Example

logger = hoomd.logging.Logger()
lj = md.pair.lj(neighbor_list)
# Log all default quantities of the lj object
logger += lj
logger = hoomd.logging.Logger(categories=['scalar'])
# Log all default scalar quantities of the lj object
logger += lj

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

Example

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: categories and only_default (the constructor arguments). Both of these are static, meaning that once instantiated, a Logger object will not change the values of these two properties. categories determines what types of loggable quantities (see LoggerCategories) are appropriate for a given Logger object. This helps logging backends determine if a Logger object is compatible. The only_default flag prevents rarely-used quantities (e.g. the number of neighborlist builds) from being added to the logger when using`Logger.__iadd__` and Logger.add without specifying them explicitly. In Logger.add, you can override the only_default flag by explicitly listing the quantities you want to add. On the other hand, categories is rigidly obeyed as it is a promise to logging backends.

Note

The logger provides a way for users to create their own logger back ends. See log for details on the intermediate representation. LoggerCategories defines the various categories available to specify logged quantities. Custom backends should be a subclass of hoomd.custom.Action and used with hoomd.write.CustomWriter.

Note

When logging multiple instances of the same class add provides a means of specifying the class level of the namespace (e.g. 'LJ in ('md', 'pair', 'LJ')). The default behavior (without specifying a user name) is to just append _{num} where num is the smallest positive integer which makes the full namespace unique. This appending will also occur for user specified names that are reused.

Parameters

categories (list of str, optional) – A list of string categories (list of categories can be found in LoggerCategories). 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. Non-default quantities are typically measures of operation performance rather than information about simulation state.

__eq__(other)¶: Check for equality.

__iadd__(obj)¶

Add quantities from object or list of objects to logger.

Adds all quantities compatible with given categories and default value.

Examples

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

__isub__(value)¶

Remove log entries for a list of quantities or objects.

Examples

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.

Parameters

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 LoggerCategories object or associated string or a object with a method/property name and category. If using a method it should not take arguments or have defaults for all arguments.

add(obj, quantities=None, user_name=None)¶

Add loggables from obj to logger.

Parameters

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.
user_name (str, optional) – A string to replace the class name in the loggable quantities namespace. This allows for easier differentiation in the output of the Logger and any Writer which outputs its data.

Returns

A list of namespaces added to the logger.

Return type

list[tuple[str]]

property categories¶

The enum representing the acceptable categories for the Logger object.

Type: LoggerCategories

log()¶

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 category for the namespace ('example', 'namespace') would be accessible in the returned dictionary via logger.log()['example']['namespace'].

Returns: A nested dictionary of the current logged quantities. The end values are (value, category) pairs which hold the value along with its associated LoggerCategories category represented as a string (to get the LoggerCategories enum value use LoggerCategories[category].
Return type: dict

property only_default¶

Whether the logger object should only grab default loggable quantities.

Type: bool

remove(obj=None, quantities=None, user_name=None)¶

Remove specified quantities from the logger.

Parameters

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 quantities 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.
user_name (str) – A user name to specify the final entry in the namespace of the object. This must be used in user_name was specified in add.

property string_categories¶

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

Type: list of str

hoomd.logging.log(func=None, *, is_property=True, category='scalar', default=True, requires_run=False)¶

Creates loggable quantities for classes of type Loggable.

Use log with hoomd.custom.Action to expose loggable quantities from a custom action.

Parameters

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. Keyword only argument.
category (str, optional) – The string represention of the type of loggable quantity, defaults to ‘scalar’. See LoggerCategories for available types. Keyword only argument.
default (bool, optional) – Whether the quantity should be logged by default. Defaults to True. This is orthogonal to the loggable quantity’s type. Many users may not want to log such quantities even when logging other quantities of that type. An example would be performance orientated loggable quantities, like the number of neighborlist builds. The default argument allows for these to be skipped by Logger objects by default. Keyword only argument.
requires_run (bool, optional) – Whether this property requires the simulation to run before being accessible.

Note

The namespace (where the loggable object is stored in the 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 automates the logging specification for developers and users.

Example:

# Metaclass specification is not necessary for
# subclasses of HOOMD classes as they already use this
# metaclass.
class LogExample(metaclass=hoomd.logging.Loggable)
    @log(category="string")
    def loggable(self):
        return "log_me"

    @log(is_property=False, default=False)
    def not_property(self, a=4):
        return 2 ** a