hoomd.logging¶
Overview
Creates loggable quantities for classes of type Loggable. |
|
Logs HOOMD-blue operation data and custom quantities. |
|
Enum that marks all accepted logger types. |
Details
-
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 back end such as thehoomd.write.Table
and many of HOOMD-blue’s object (as most objects are loggable). TheLogger
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, thehoomd.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 existLogger.add
and the+=
operator. Here we show an example using the+=
operator.Example
logger = hoomd.logging.Logger() lj = md.pair.lj(nlist) # 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
andonly_default
(the constructor arguments). Both of these are static meaning that once instantiated aLogger
object will not change the values of these two properties.categories
determines what if any types of loggable quantities (seehoomd.logging.LoggerCategories
) are appropriate for a givenLogger
object. This helps logging back ends determine if aLogger
object is compatible. Theonly_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 theonly_default
flag by explicitly listing the quantities you want inLogger.add
, but the same is not true with regards tocategories
.Note
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 categories available to specify logged quantities, seehoomd.logging.LoggerCategories
. To integrate withhoomd.Operations
the back end should be a subclass ofhoomd.custom.Action
and used withhoomd.writer.CustomWriter
.Note
When logging multiple instances of the same class
Logger.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
ofstr
, optional) – A list of string categories (list of categories can be found inhoomd.logging.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 toTrue
. This mostly means that performance centric loggable quantities will be passed over when logging when false.
-
__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
hoomd.logging.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 theLogger
and anyWriter
which outputs its data.
- Returns
- A list of namespaces that were
added to the logger.
- Return type
-
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
hoomd.logging.LoggerCategories
category represented as a string (to get thehoomd.logging.LoggerCategories
enum value useLoggerCategories[category]
.
- Return type
-
property
only_default
¶ Whether the logger object should only grab 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 quanties 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 inLogger.add
.
-
class
hoomd.logging.
LoggerCategories
(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 categories to use for limiting what data is logged, user specified logged quantities, and custom actions (
hoomd.custom.Action
).- Flags:
scalar:
float
orint
objects (i.e. numbers)sequence: sequence (e.g.
list
,tuple
,numpy.ndarray
) of numbers of the same type.string: a single Python
str
objectstrings: a sequence of Python
str
objectsobject: 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 category for specifying object’s internal state
ALL: a combination of all other categories
NONE: represents no category
-
ALL
= 8191¶
-
NONE
= 0¶
-
angle
= 32¶
-
classmethod
any
(categories=None)¶ Return a LoggerCategories enum representing any of the given categories.
- Parameters
categories (list[str] or list[
LoggerCategories
]) – A list ofstr
orobjects that should be represented by the returned (LoggerCategories) –
object. (LoggerCategories) –
- Returns
the
LoggerCategories
object that represents any of the given categories.- 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, category='scalar', default=True)¶ Creates loggable quantities for classes of type Loggable.
For users this should be used with
hoomd.custom.Action
for exposing 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. Argument keyword onlycategory (
str
, optional) – The string represention of the type of loggable quantity, defaults to ‘scalar’. Seehoomd.logging.LoggerCategories
for available types. Argument keyword onlydefault (
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 category allows for these to be pass over byhoomd.logging.Logger
objects by default. Argument keyword only.
Note
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 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 automate the logging specification for developers and users.