Checkpoints

igl.io

Versioned checkpoint save/load for modules and estimators.

One file, one schema: :func:save writes a torch.save payload holding only tensors and JSON-safe primitives, so :func:load reads it with torch.load(..., weights_only=True). The payload carries the resolved :class:igl.IGLConfig, the module state_dict, the preprocessing constants (scaler statistics, scalar input stats, or a fitted :class:igl.whitening.TargetWhitener), estimator extras (params, classes, history, dimension curve), and provenance (package and torch versions, seed, epochs, quick/full profile).

PreprocessingState dataclass

Preprocessing constants for bare-module checkpoints.

Estimator checkpoints derive these from fitted attributes; bare :class:igl.IGLModule saves carry them explicitly.

Profile

Bases: StrEnum

Fit profile recorded in provenance: quick fits must not be silently reused.

Provenance dataclass

User-supplied provenance stamped into the checkpoint.

Attributes:

Name	Type	Description
seed	int | None	Seed used for the fit, if any.
epochs	int | None	Epoch budget of the fit, if recorded.
profile	ProfileLike	Profile.FULL (default) or Profile.QUICK; quick checkpoints are refused by :func:load unless allow_quick.

load(path, *, allow_quick=False, map_location='cpu')

Read a checkpoint written by :func:save.

Parameters:

Name	Type	Description	Default
path	str | Path	Checkpoint file.	required
allow_quick	bool	Load profile="quick" checkpoints; refused by default so a quick fit is never silently mistaken for a full one.	False
map_location	str | device	Device for the loaded tensors.	'cpu'

Returns:

Type	Description
Saveable	The reconstructed module or estimator, ready for inference.

Raises:

Type	Description
IGLSerializationError	On schema mismatch or a refused quick profile.

read_provenance(path)

Read only the provenance block of a checkpoint.

save(obj, path, *, config=None, preprocessing=None, provenance=None)

Write a schema-v1 checkpoint for a module or fitted estimator.

Parameters:

Name	Type	Description	Default
obj	Saveable	A bare :class:igl.IGLModule or a fitted estimator.	required
path	str | Path	Destination file.	required
config	IGLConfig | None	Required for bare modules (a module does not retain its config); forbidden for estimators (theirs is derived).	None
preprocessing	PreprocessingState | None	Optional constants for bare modules; forbidden for estimators.	None
provenance	Provenance | None	Optional provenance; versions and timestamp are stamped automatically.	None

Raises:

Type	Description
IGLSerializationError	For unfitted estimators or a bare module without config.
IGLConfigError	When estimator-derived fields are passed explicitly.

igl.save(obj, path, *, config=None, preprocessing=None, provenance=None)

Write a schema-v1 checkpoint for a module or fitted estimator.

Parameters:

Name	Type	Description	Default
obj	Saveable	A bare :class:igl.IGLModule or a fitted estimator.	required
path	str | Path	Destination file.	required
config	IGLConfig | None	Required for bare modules (a module does not retain its config); forbidden for estimators (theirs is derived).	None
preprocessing	PreprocessingState | None	Optional constants for bare modules; forbidden for estimators.	None
provenance	Provenance | None	Optional provenance; versions and timestamp are stamped automatically.	None

Raises:

Type	Description
IGLSerializationError	For unfitted estimators or a bare module without config.
IGLConfigError	When estimator-derived fields are passed explicitly.

igl.load(path, *, allow_quick=False, map_location='cpu')

Read a checkpoint written by :func:save.

Parameters:

Name	Type	Description	Default
path	str | Path	Checkpoint file.	required
allow_quick	bool	Load profile="quick" checkpoints; refused by default so a quick fit is never silently mistaken for a full one.	False
map_location	str | device	Device for the loaded tensors.	'cpu'

Returns:

Type	Description
Saveable	The reconstructed module or estimator, ready for inference.

Raises:

Type	Description
IGLSerializationError	On schema mismatch or a refused quick profile.

igl.read_provenance(path)

Read only the provenance block of a checkpoint.

igl.io.Provenance dataclass

User-supplied provenance stamped into the checkpoint.

Attributes:

Name	Type	Description
seed	int | None	Seed used for the fit, if any.
epochs	int | None	Epoch budget of the fit, if recorded.
profile	ProfileLike	Profile.FULL (default) or Profile.QUICK; quick checkpoints are refused by :func:load unless allow_quick.

igl.io.PreprocessingState dataclass

Preprocessing constants for bare-module checkpoints.

Estimator checkpoints derive these from fitted attributes; bare :class:igl.IGLModule saves carry them explicitly.