composer.core.engine#

Engine is a coordinator for running algorithms and resolving ordering conflicts among them for composition.

The order in which algorithms are run matters significantly during composition. For example, SelectiveBackprop algorithm runs on the AFTER_DATALOADER event and must run before any data augmentations. Engine runs re-ordering passes to resolve such ordering issues or conflicts.

Note

  • An instance of Engine is automatically constructed by the Trainer constructor. A user need not instantiate Engine class.

  • The design of Engine is subject to change in future releases to accommodate more complexity as we investigate composition of algorithms.

Currently, the following passes are registered:

  • LIFO order for events

    For the events that follow the before_* (e.g., BEFORE_LOSS) and after_* (e.g., AFTER_LOSS) pattern, the ordering of algorithms is reversed for the after_* events. For example, four given algorithms A, B, C and D will run in ABCD ordering on the before_* event while DCBA ordering on the after_* event.

    This allows algorithms to โ€œclean upโ€ their changes. For example, LabelSmoothing will smooth the labels upon on BEFORE_LOSS event and then restore the original unsmoothed labels on AFTER_LOSS event.

  • Run Selective Backprop first

    SelectiveBackprop runs after the dataloader returns the batch, and executes an extra forward pass to rank and prune the examples in the batch by loss. To ensure a clean estimate of loss, SelectiveBackprop should run before any other data augmentations (e.g., MixUp) on the AFTER_DATALOADER event.

Trace#

Traces record whether an algorithm ran at a particular step and event combination and also the order of such executions. These are logged with the key <algorithm_name>/<event>.

For example, the algorithm LayerFreezing, which runs at the end of every epoch on EPOCH_END, will emit a series of traces:

[STEP=0][layer_freezing/INIT=0]
[STEP=1][layer_freezing/EPOCH_START=0]
[STEP=1][layer_freezing/BATCH_START=0]
...
[STEP=2][layer_freezing/BATCH_START=0]
...
[STEP=3][layer_freezing/BATCH_START=0]
...
[STEP=3][layer_freezing/EPOCH_END=1]  # <-- layer freezing ran on step 3 here!

Classes

Engine

Coordinator for running algorithms and resolving ordering conflicts among them for composition.

Trace

Record of an algorithm's execution.

Attributes

class composer.core.engine.Engine(state, logger)[source]#

Coordinator for running algorithms and resolving ordering conflicts among them for composition.

Parameters

  • state (State) โ€“ The initial State of the trainer. state will be modified in-place.

  • logger (Logger) โ€“ A Logger instance to be used for logging algorithm and callback specific metrics.

close()[source]#

Shutdown the enginge.

As part of the shutdown procedure, close() and post_close() is invoked for each callback. Note that post_close() is invoked only for callbacks that did not raise an exception during close().

This method does not re-raise any exceptions from close() and post_close(). Instead, these exceptions are logged as errors.

run_event(event)[source]#

Runs the sequence of algorithms and callbacks (see Callback).

Filters algorithms by calling each oneโ€™s match() method, internally checks for conflicting algorithms, then runs each algorithmโ€™s apply() method to make in-place changes to the state.

The default order of execution for algorithms is determined by the provided list. However, Engine makes changes to this order internally to resolve ordering conflicts.

Returns Traces of the execution, a dictionary with keys formatted as <algorithm_name>/<event> (e.g., Blurpool/INIT), and values are an instance of Trace.

Callbacks are always run after algorithms and do not return a trace.

This method can be called with either the Event enum member values or a string of the event name.

Examples

>>> engine = Engine(state, logger)
>>> engine.run_event(Event.BEFORE_LOSS)
OrderedDict()
>>> # calling with a string of the event name also works
>>> engine.run_event('before_loss')
OrderedDict()
Parameters

event (Event or str) โ€“ The current Event. It can be the enum member values or a string with the event value.

Returns

traces (Traces) โ€“ Ordered dictionary of trace for each algorithm.

class composer.core.engine.Trace(exit_code=None, order=None, run=False)[source]#

Record of an algorithmโ€™s execution.

exit_code#

Optional return value from an algorithm. Default: None.

Type

int or None

order#

Order in which the algorithm was executed in the list of algorithms. None means algorithm was not run.

Type

int or None

run#

Whether the algorithm was run. Default: False

Type

bool

composer.core.engine.Traces#

The default traces of an entire run is an OrderedDict. The keys are of format <algorithm_name>/<event> (e.g., Blurpool/INIT) and values are an instance of Trace.

alias of Dict[str, Trace]