ModelCheckpoint

class pyqit.core.callbacks.ModelCheckpoint(dirpath: str | None = None, filename: str = 'best', monitor: str | None = None, mode: str = 'min', save_best: bool = True, save_last: bool = False, every_n_epochs: int | None = None, save_on_improve: bool = False, restore_best: bool | None = None, resume_from: str | None = None)

Bases: BaseCallback

Save checkpoints, restore the best epoch’s weights, or resume from one.

Three files can be written, independently: the best epoch (save_best), the final epoch (save_last), and a periodic snapshot (every_n_epochs). Each holds the weights, the optimizer’s state and the history up to that epoch, so any of them resumes the run. The policy is backend-neutral; only serialization forks – a .ckpt on torch, an .npz on pennylane. Weights are keyed by model.weights keys on both.

Parameters:

• dirpath (str, optional) – Directory to write into. Defaults to "checkpoints".

• filename (str, default "best") – Stem of the best-epoch file. The other two have fixed stems, last and epoch<n>, so the three never collide.

• monitor (str, optional) – Metric deciding which epoch is best. None picks "val_loss" when a validation split produced a finite value and "train_loss" otherwise, so a run without a validation split still checkpoints.

• mode ({"min", "max"}, default "min") – Whether a lower or higher value of monitor is better.

• save_best (bool, default True) – Write the best epoch’s checkpoint.

• save_last (bool, default False) – Write the final epoch’s checkpoint. Written before any restore, so the file holds the last epoch even when restore_best is on.

• every_n_epochs (int, optional) – Also write a snapshot every N epochs, named by the zero-based epoch index to match best_epoch. With every_n_epochs=5 that is epoch4, epoch9, and so on.

• save_on_improve (bool, default False) – Write the best file on every improvement rather than once after training. Costs extra I/O but survives a crash mid-run. Ignored when save_best is False.

• restore_best (bool, optional) – Load the best weights back into the model when training ends. Defaults to save_best, so asking only for the last epoch does not silently hand back the best one.

• resume_from (str, optional) – A checkpoint written by this callback. Before the first epoch its weights are loaded into the model, its history into the run’s, so training continues from the next epoch within max_epochs, and its optimizer state into the optimizer the loop builds. A file from the other backend restores weights and history only, with a warning, since optimizer state does not transfer.

best_score

Best value of monitor seen.

Type:

float

best_epoch

Zero-based epoch it was seen on, or -1.

Type:

int

best_path, last_path

Paths written, once anything has been.

Type:

str or None

periodic_paths

Paths written by every_n_epochs, in order.

Type:

list of str

Notes

A file from the other backend restores the weights and history and warns that the optimizer starts fresh, since its state does not transfer. Callbacks that track improvement, EarlyStopping and the best epoch here, start their count over on a resumed run. The fitted preprocessing is not in the file; it is the DataModule’s own artifact, saved with DataModule.save when wanted.

Examples

Save the last epoch, then pick the run up from it two epochs later:

>>> import pyqit
>>> from pyqit.core import ModelCheckpoint
>>> saving = ModelCheckpoint(dirpath="ckpts", save_best=False, save_last=True)
>>> pyqit.Trainer(max_epochs=2, callbacks=[saving]).fit(model, dm)
>>> resuming = ModelCheckpoint(save_best=False, resume_from="ckpts/last.npz")
>>> history = pyqit.Trainer(max_epochs=4, callbacks=[resuming]).fit(
...     model, dm
... )

The history’s length is the next epoch, so this trains epochs 2 and 3, and Adam keeps its moment estimates.

classmethod get_test_params()

List constructor kwargs used to parametrize this class in the test suite.

on_epoch_end(state: LoopState) → None

Track the best epoch and write any periodic snapshot.

on_fit_end(state: LoopState) → None

Write the requested files, then restore the best weights.

on_fit_start(state: LoopState) → None

Load resume_from into the model, the history and the optimizer.