1 lightning.training.callbacks

lightning.training.callbacks

Construct the callback set owned by each Lightning trainer.

This module provides config-as-factory wiring for checkpointing, early stopping, learning-rate logging, progress display, model summaries, backbone finetuning, timers, and Optuna pruning. It owns callback compatibility and schedule validation; the trainer factory owns attachment and lifecycle calls.

1.1 Classes

Name Description
TrainerCallbacksConfig Configure one mutually compatible Lightning callback collection.

1.1.1 TrainerCallbacksConfig

lightning.training.callbacks.TrainerCallbacksConfig()

Configure one mutually compatible Lightning callback collection.

:meth:setup_target may adapt checkpoint, early-stopping, and pruning flags for an Optuna trial. The returned callback objects are then owned and invoked by the external Lightning trainer.

1.1.1.1 Attributes

Name Description
target_type Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
use_model_checkpoint Attach a model-checkpoint callback using the fields below.
checkpoint_monitor Logged metric key used to rank checkpoints.
checkpoint_mode Checkpoint ranking direction, conventionally "min" or "max".
checkpoint_dir Checkpoint directory; None resolves through :class:PathConfig.
checkpoint_filename Lightning format template evaluated from epoch, step, and logged metrics.
checkpoint_save_top_k Number of monitor-ranked checkpoints retained by Lightning.
checkpoint_auto_insert_metric_name Let Lightning inject monitor names into the checkpoint filename.
checkpoint_save_last Lightning tri-state policy for maintaining a last.ckpt alias/copy.
checkpoint_every_n_train_steps Optional positive optimizer-step checkpoint cadence.
checkpoint_train_time_interval Optional positive wall-clock cadence accepted by datetime.timedelta.
checkpoint_every_n_epochs Optional positive epoch checkpoint cadence.
checkpoint_save_on_train_epoch_end Optional override for Lightning’s train-epoch-end checkpoint timing.
use_early_stopping Attach an early-stopping callback for the configured monitor.
early_stopping_monitor Logged metric key observed by early stopping.
early_stopping_mode Early-stopping improvement direction, "min" or "max".
early_stopping_patience Validation checks without improvement allowed before stopping.
optimizer_diagnostics Opt-in bounded gradient and optimizer scalars at the unscaled pre-step hook.
use_lr_monitor Attach learning-rate logging when the trainer has a logger.
lr_logging_interval Learning-rate logging cadence passed to Lightning.
use_optuna_pruning Enable Optuna pruning callback for hyperparameter optimisation runs.
use_rich_progress_bar Enable the Rich progress bar; mutually exclusive with TQDM.
use_tqdm_progress_bar Enable the TQDM progress bar; mutually exclusive with Rich.
tqdm_refresh_rate TQDM refresh cadence in training batches.
use_rich_model_summary Attach a Rich model-tree summary callback.
rich_summary_max_depth Maximum module-tree depth rendered by the Rich summary.
use_backbone_finetuning Attach Lightning’s staged backbone-unfreezing callback.
backbone_unfreeze_at_epoch Zero-based epoch at which the callback unfreezes the backbone.
backbone_lambda_func Optional serialized learning-rate lambda consumed by backbone finetuning.
backbone_train_bn Keep backbone batch-normalization layers trainable after unfreezing.
use_timer Attach a Lightning wall-clock timer callback.
timer_duration Optional duration mapping accepted by datetime.timedelta.
timer_interval Timer check cadence passed to Lightning.

1.1.1.2 Methods

Name Description
setup_target Build callbacks and adapt trial-specific ownership flags.
1.1.1.2.1 setup_target
lightning.training.callbacks.TrainerCallbacksConfig.setup_target(
    model_name=None,
    *,
    has_logger=True,
    trial=None,
    optuna_config=None,
)

Build callbacks and adapt trial-specific ownership flags.

1.1.1.2.1.1 Parameters
Name Type Description Default
model_name str | None Optional prefix added to checkpoint filenames. None
has_logger bool Whether a trainer logger exists; LR monitoring is omitted when false. True
trial 'Trial | None' Optional Optuna trial that owns pruning decisions. None
optuna_config 'OptunaConfig | None' Required pruning config when trial enables the pruning callback. None
1.1.1.2.1.2 Returns
Name Type Description
list[Callback] Fresh callback list owned by one external Lightning trainer.
1.1.1.2.1.3 Notes

Trial runs disable checkpointing and early stopping to avoid competing persistence/termination owners. Outside a trial, stale pruning flags are disabled explicitly.

Back to top