Callback

Callbacks allow you to add arbitrary self-contained programs to your training. At specific points during the flow of execution (hooks), the Callback interface allows you to design programs that encapsulate a full set of functionality. It de-couples functionality that does not need to be in the lightning module and can be shared across projects.

Lightning has a callback system to execute them when needed. Callbacks should capture NON-ESSENTIAL logic that is NOT required for your lightning module to run.

A complete list of Callback hooks can be found in Callback.

An overall Lightning system should have:

Trainer for all engineering
LightningModule for all research code.
Callbacks for non-essential code.

Example:

from lightning.pytorch.callbacks import Callback

class MyPrintingCallback(Callback):
    def on_train_start(self, trainer, pl_module):
        print("Training is starting")

    def on_train_end(self, trainer, pl_module):
        print("Training is ending")

trainer = Trainer(callbacks=[MyPrintingCallback()])

We successfully extended functionality without polluting our super clean lightning module research code.

You can do pretty much anything with callbacks.

Built-in Callbacks

Lightning has a few built-in callbacks.

Note

For a richer collection of callbacks, check out our bolts library.

BackboneFinetuning — Finetune a backbone model based on a learning rate user-defined scheduling.
BaseFinetuning — This class implements the base logic for writing your own Finetuning Callback.
BasePredictionWriter — Base class to implement how the predictions should be stored.
BatchSizeFinder — Finds the largest batch size supported by a given model before encountering an out of memory (OOM) error.
Callback — Abstract base class used to build new callbacks.
DeviceStatsMonitor — Automatically monitors and logs device stats during training, validation and testing stage. DeviceStatsMonitor is a special callback as it requires a logger to passed as argument to the Trainer.
EarlyStopping — Monitor a metric and stop training when it stops improving.
GradientAccumulationScheduler — Change gradient accumulation factor according to scheduling.
LambdaCallback — Create a simple callback on the fly using lambda functions.
LearningRateFinder — The LearningRateFinder callback enables the user to do a range test of good initial learning rates, to reduce the amount of guesswork in picking a good starting learning rate.
LearningRateMonitor — Automatically monitor and logs learning rate for learning rate schedulers during training.
ModelCheckpoint — Save the model after every epoch by monitoring a quantity. Every logged metrics are passed to the Logger for the version it gets saved in the same directory as the checkpoint.
ModelPruning — Model pruning Callback, using PyTorch’s prune utilities. This callback is responsible of pruning networks parameters during training.
ModelSummary — Generates a summary of all layers in a LightningModule.
ProgressBar — The base class for progress bars in Lightning. It is a Callback that keeps track of the batch progress in the Trainer. You should implement your highly custom progress bars with this as the base class
RichModelSummary — Generates a summary of all layers in a LightningModule with rich text formatting.
RichProgressBar — Create a progress bar with rich text formatting.
StochasticWeightAveraging — Implements the Stochastic Weight Averaging (SWA) Callback to average a model.
Timer — The Timer callback tracks the time spent in the training, validation, and test loops and interrupts the Trainer if the given time limit for the training loop is reached.
TQDMProgressBar — This is the default progress bar used by Lightning. It prints to stdout using the tqdm package and shows up to four different bars:
WeightAveraging — A callback that updates an averaged model for Stochastic Weight Averaging (SWA) or Exponential Moving Average (EMA) after each training step.

Save Callback state

Some callbacks require internal state in order to function properly. You can optionally choose to persist your callback's state as part of model checkpoint files using state_dict and load_state_dict. Note that the returned state must be able to be pickled.

When your callback is meant to be used only as a singleton callback then implementing the above two hooks is enough to persist state effectively. However, if passing multiple instances of the callback to the Trainer is supported, then the callback must define a state_key property in order for Lightning to be able to distinguish the different states when loading the callback state. This concept is best illustrated by the following example.

class Counter(Callback):
    def __init__(self, what="epochs", verbose=True):
        self.what = what
        self.verbose = verbose
        self.state = {"epochs": 0, "batches": 0}

    @property
    def state_key(self) -> str:
        # note: we do not include `verbose` here on purpose
        return f"Counter[what={self.what}]"

    def on_train_epoch_end(self, *args, **kwargs):
        if self.what == "epochs":
            self.state["epochs"] += 1

    def on_train_batch_end(self, *args, **kwargs):
        if self.what == "batches":
            self.state["batches"] += 1

    def load_state_dict(self, state_dict):
        self.state.update(state_dict)

    def state_dict(self):
        return self.state.copy()

# two callbacks of the same type are being used
trainer = Trainer(callbacks=[Counter(what="epochs"), Counter(what="batches")])

A Lightning checkpoint from this Trainer with the two stateful callbacks will include the following information:

{
    "state_dict": ...,
    "callbacks": {
        "Counter{'what': 'batches'}": {"batches": 32, "epochs": 0},
        "Counter{'what': 'epochs'}": {"batches": 0, "epochs": 2},
        ...
    }
}

The implementation of a state_key is essential here. If it were missing, Lightning would not be able to disambiguate the state for these two callbacks, and state_key by default only defines the class name as the key, e.g., here Counter.

Best Practices

The following are best practices when using/designing callbacks.

Callbacks should be isolated in their functionality.
Your callback should not rely on the behavior of other callbacks in order to work properly.
Do not manually call methods from the callback.
Directly calling methods (eg. on_validation_end) is strongly discouraged.
Whenever possible, your callbacks should not depend on the order in which they are executed.

Entry Points

Lightning supports registering Trainer callbacks directly through Entry Points. Entry points allow an arbitrary package to include callbacks that the Lightning Trainer can automatically use, without you having to add them to the Trainer manually. This is useful in production environments where it is common to provide specialized monitoring and logging callbacks globally for every application.

Here is a callback factory function that returns two special callbacks:

def my_custom_callbacks_factory():
    return [MyCallback1(), MyCallback2()]

If we make this factories.py file into an installable package, we can define an entry point for this factory function. Here is a minimal example of the setup.py file for the package my-package:

from setuptools import setup

setup(
    name="my-package",
    version="0.0.1",
    install_requires=["lightning"],
    entry_points={
        "lightning.pytorch.callbacks_factory": [
            # The format here must be [any name]=[module path]:[function name]
            "monitor_callbacks=factories:my_custom_callbacks_factory"
        ]
    },
)

The group name for the entry points is lightning.pytorch.callbacks_factory and it contains a list of strings that specify where to find the function within the package.

Now, if you pip install -e . this package, it will register the my_custom_callbacks_factory function and Lightning will automatically call it to collect the callbacks whenever you run the Trainer!

To unregister the factory, simply uninstall the package with pip uninstall "my-package".

Callback API

Here is the full API of methods available in the Callback base class.

The Callback class is the base for all the callbacks in Lightning just like the LightningModule is the base for all models. It defines a public interface that each callback implementation must follow, the key ones are:

Properties

state_key

lightning.pytorch.callbacks.Callback.state_key

Hooks

setup

lightning.pytorch.callbacks.Callback.setup

teardown

lightning.pytorch.callbacks.Callback.teardown

on_fit_start

lightning.pytorch.callbacks.Callback.on_fit_start

on_fit_end

lightning.pytorch.callbacks.Callback.on_fit_end

on_sanity_check_start

lightning.pytorch.callbacks.Callback.on_sanity_check_start

on_sanity_check_end

lightning.pytorch.callbacks.Callback.on_sanity_check_end

on_train_batch_start

lightning.pytorch.callbacks.Callback.on_train_batch_start

on_train_batch_end

lightning.pytorch.callbacks.Callback.on_train_batch_end

on_train_epoch_start

lightning.pytorch.callbacks.Callback.on_train_epoch_start

on_train_epoch_end

lightning.pytorch.callbacks.Callback.on_train_epoch_end

on_validation_epoch_start

lightning.pytorch.callbacks.Callback.on_validation_epoch_start

on_validation_epoch_end

lightning.pytorch.callbacks.Callback.on_validation_epoch_end

on_test_epoch_start

lightning.pytorch.callbacks.Callback.on_test_epoch_start

on_test_epoch_end

lightning.pytorch.callbacks.Callback.on_test_epoch_end

on_predict_epoch_start

lightning.pytorch.callbacks.Callback.on_predict_epoch_start

on_predict_epoch_end

lightning.pytorch.callbacks.Callback.on_predict_epoch_end

on_validation_batch_start

lightning.pytorch.callbacks.Callback.on_validation_batch_start

on_validation_batch_end

lightning.pytorch.callbacks.Callback.on_validation_batch_end

on_test_batch_start

lightning.pytorch.callbacks.Callback.on_test_batch_start

on_test_batch_end

lightning.pytorch.callbacks.Callback.on_test_batch_end

on_predict_batch_start

lightning.pytorch.callbacks.Callback.on_predict_batch_start

on_predict_batch_end

lightning.pytorch.callbacks.Callback.on_predict_batch_end

on_train_start

lightning.pytorch.callbacks.Callback.on_train_start

on_train_end

lightning.pytorch.callbacks.Callback.on_train_end

on_validation_start

lightning.pytorch.callbacks.Callback.on_validation_start

on_validation_end

lightning.pytorch.callbacks.Callback.on_validation_end

on_test_start

lightning.pytorch.callbacks.Callback.on_test_start

on_test_end

lightning.pytorch.callbacks.Callback.on_test_end

on_predict_start

lightning.pytorch.callbacks.Callback.on_predict_start

on_predict_end

lightning.pytorch.callbacks.Callback.on_predict_end

on_exception

lightning.pytorch.callbacks.Callback.on_exception

state_dict

lightning.pytorch.callbacks.Callback.state_dict

on_save_checkpoint

lightning.pytorch.callbacks.Callback.on_save_checkpoint

load_state_dict

lightning.pytorch.callbacks.Callback.load_state_dict

on_load_checkpoint

lightning.pytorch.callbacks.Callback.on_load_checkpoint

on_before_backward

lightning.pytorch.callbacks.Callback.on_before_backward

on_after_backward

lightning.pytorch.callbacks.Callback.on_after_backward

on_before_optimizer_step

lightning.pytorch.callbacks.Callback.on_before_optimizer_step

on_before_zero_grad

lightning.pytorch.callbacks.Callback.on_before_zero_grad

Was this page helpful?