Logger

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 the += operator to add all matching loggable quantities provided by an object to the Logger.

Logger provides two ways to limit what loggable quantities it will accept: categories and only_default (the constructor arguments). 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. The only_default flag prevents rarely-used quantities from being added to the logger when using`Logger.__iadd__` and Logger.add when not explicitly requested.

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 [str ], LoggerCategories, optional) – Either a list of string categories (list of categories can be found in LoggerCategories) or a LoggerCategories instance with the desired flags set. These are the only types of loggable quantities that can be logged by this logger. Defaults to allowing every type LoggerCategories.ALL.

  • 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.

Examples:

There are various ways to create a logger with different available loggables. Create a Logger with no options to allow all categories.

logger = hoomd.logging.Logger()

Use a list of strings to log a subset of categories:

logger = hoomd.logging.Logger(categories=["string", "strings"])
__eq__(other)

Check for equality.

__iadd__(obj)

Add quantities from an object or list of objects.

Adds all quantities compatible with given categories and default value.

Example:

logger += lj
__isub__(value)

Remove log entries for a list of quantities or objects.

Example:

logger -= lj
__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.

Example:

logger[("custom", "name")] = (lambda: 42, "scalar")
add(obj, quantities=None, user_name=None)

Add loggables.

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]]

Example:

logger.add(obj=lj, quantities=["energy"])
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

Example:

values_to_log = logger.log()
property only_default

Whether the logger object should only add 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.

Example:

logger.remove(obj=lj, quantities=["energy"])
property string_categories

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

Type:

list[str]