SR-Forge

Trainers

Trainers — orchestrate the epoch loop over training and validation runners.

A :class:Trainer owns the lifecycle: epoch loop, validation, LR scheduling, early stopping. Like a :class:~srforge.training.runners.EpochRunner, it exposes its lifecycle stages as :class:HookPoint attributes (on_training_began, on_trainer_epoch_finished).

Hooks attached via Trainer(hooks=[…]) bind only to the Trainer itself — they fire from the Trainer's own HookPoints and nowhere else. If you want a hook to fire from a runner too, pass it to that runner's hooks=[...] directly. Hook instances are plain objects, so the same instance can appear in multiple lists.

Trainer

Bases: ABC

Base trainer.

Subclasses declare lifecycle stages as :class:HookPoint-typed class attributes. The base class harvests them at subclass-creation time so __init__ can materialise one HookPoint per name on each instance.

train(epochs: int, training_loader, validation_loader) abstractmethod

Run the training loop.

PyTorchTrainer

Bases: Trainer

Orchestrates the training loop over training and validation runners.

The trainer owns the loss criteria and passes them to the runners at call time via runner.run_epoch(criterion=...). It also manages the LR scheduler, early stopping, and checkpoint restoration.

Parameters:

Name	Type	Description	Default
model	Model	The model to train. Must be an :class:~srforge.models.Model (or SequentialModel / GANModel) — checkpointing needs the name and sub-module structure a plain torch.nn.Module does not carry. :class:~srforge.models.Model provides additional Entry-based routing.	required
training_epoch_runner	EpochRunner	Runner that executes one training epoch (typically :class:~srforge.training.runners.TrainingEpochRunner).	required
validation_epoch_runner	EpochRunner	Runner that executes one validation epoch (typically :class:~srforge.training.runners.ValidationEpochRunner).	required
training_criterion	Union[Metric, LossScheduler]	Metric or :class:LossScheduler used during the training phase. Passed to the training runner each epoch.	required
validation_criterion	Union[Metric, LossScheduler]	Metric or :class:LossScheduler used during the validation phase. Passed to the validation runner each epoch.	required
lr_scheduler	Optional[LRSchedule]	A single torch.optim.lr_scheduler or a :class:~srforge.training.schedule.SchedulerGroup (use the group when a runner owns several optimizers, e.g. a GAN's optimizer_G / optimizer_D). Stepped once per epoch after both runners finish. None means constant learning rate. Whatever is passed is wrapped in a :class:~srforge.training.schedule.SchedulerGroup bound to the training runner's optimizers, so self.lr_scheduler and ctx.lr_scheduler are always a group.	None
stop_condition	Optional[StopCondition]	A :class:~srforge.training.stop.StopCondition checked after each epoch. None means :class:~srforge.training.stop.NoCondition — train for all epochs. The default is built per Trainer rather than shared at import time, so stateful conditions (e.g. :class:~srforge.training.stop.ValidationLossDidNotImprove, which accumulates losses) can never leak state between trainers in one process.	None
hooks	Optional[List]	Optional list of :class:~srforge.training.hooks.Hook instances. Hooks attached here fire only from the Trainer's own HookPoints (on_training_began, on_trainer_epoch_finished). To attach a hook to a runner, pass it to that runner's hooks=[...] directly.	None
output_directory	Optional[str]	Where checkpoints and other run files go, passed to hooks as ctx.output_directory. None (the default) uses the directory :func:srforge.init set and created — set it here only for a script that does not call init().	None

restore(checkpoint: CheckpointState | None) -> None

Apply a checkpoint to this trainer.

Sets initial_epoch and best_losses. Runner state (optimizers, scalers) is restored via resume_from_checkpoint before this method is called.

Parameters:

Name	Type	Description	Default
checkpoint	CheckpointState | None	A :class:~srforge.utils.checkpoint.CheckpointState returned by :func:~srforge.utils.checkpoint.resume_from_checkpoint, or None.	required

sanity_check(training_loader: data.DataLoader, validation_loader: data.DataLoader) -> None

Run one batch through training and validation to catch errors early.

Bypasses :meth:run_epoch (so no HookPoints fire) and runs a manual forward + loss pass on each runner.

Parameters:

Name	Type	Description	Default
training_loader	DataLoader	Training data loader.	required
validation_loader	DataLoader	Validation data loader.	required