hoomd.logging¶
Overview
Enum that marks all accepted logger types. |
|
Logs HOOMD-blue operation data and custom quantities. |
|
Creates loggable quantities for classes of type Loggable. |
|
Modify a class's namespace to a manually assigned one. |
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.
- class hoomd.logging.LoggerCategories(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Enum that marks all accepted logger types.
The attribute names of
LoggerCategories
are valid strings for the category argument ofLogger
constructor and thelog
method.- sequence¶
Sequence (e.g.
list
,tuple
,numpy.ndarray
) of numbers of the same type.
- 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
] orlist
[LoggerCategories
]) – A list ofstr
orLoggerCategories
objects that should be represented by the returnedLoggerCategories
object.- Returns:
the
LoggerCategories
object that represents any of the given categories.- Return type:
- 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 ashoomd.write.GSD
orhoomd.write.Table
and loggable objects. TheLogger
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, thehoomd.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 theLogger
.Logger
provides two ways to limit what loggable quantities it will accept:categories
andonly_default
(the constructor arguments). Once instantiated, aLogger
object will not change the values of these two properties.categories
determines what types of loggable quantities (seeLoggerCategories
) are appropriate for a givenLogger
object. Theonly_default
flag prevents rarely-used quantities from being added to the logger when using`Logger.__iadd__` andLogger.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 ofhoomd.custom.Action
and used withhoomd.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}
wherenum
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 inLoggerCategories
) or aLoggerCategories
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 typeLoggerCategories.ALL
.only_default (
bool
, optional) – Whether to log only quantities that are logged by default. Defaults toTrue
. 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 theLogger
and anyWriter
which outputs its data.
- Returns:
A list of namespaces added to the logger.
- Return type:
Example:
logger.add(obj=lj, quantities=['energy'])
- 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 vialogger.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 theLoggerCategories
enum value useLoggerCategories[category]
).- Return type:
Example:
values_to_log = logger.log()
- property only_default¶
Whether the logger object should only add default loggable quantities.
- Type:
- 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. Ifquantities
is None,obj
must be set. Ifobj
is set andquantities
is None, all logged quantities fromobj
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 fromobj
. Ifobj
is None, thenquantities
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 inadd
.
Example:
logger.remove(obj=lj, quantities=['energy'])
- 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
withhoomd.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’. SeeLoggerCategories
for available types. Keyword only argument.default (
bool
, optional) – Whether the quantity should be logged by default. Defaults to True. 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 ofhoomd.custom.Action
, for instance, if the module the subclass is defined in isuser.custom.action
and the class name isFoo
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:
class LogExample(metaclass=hoomd.logging.Loggable): @log() def loggable(self): return 1.5
Note
The metaclass specification is not necessary for subclasses of HOOMD classes as they already use this metaclass.
See also
Tutorial: Custom Actions in Python
- hoomd.logging.modify_namespace(cls, namespace=None)¶
Modify a class’s namespace to a manually assigned one.
- Parameters:
Warning
This will only persist for the current class. All subclasses will have the standard namespace assignment.