OptimResult

Contents

OptimResult#

class liesel.optim.OptimResult(history, position_final, position_min_monitor, n_epochs, min_monitor_epoch, monitor_source, patience, duration, nan_debug=None, checkpoint=None, status='max_epochs')[source]#

Bases: object

Result returned by an optimizer run.

OptimResult bundles the processed history, the terminal and minimum-monitor positions, and small metadata about the run. Choose explicitly between position_final and position_min_monitor when using fitted parameters. Accessing an unavailable position or one containing NaN or infinity raises RuntimeError. History, status, and diagnostics remain available. It also provides plotting methods for losses and saved parameter histories.

Parameters:

  • history (OptimHistory) – Processed optimizer history.

  • position_final (Position (dict[str, Any])) – Actual terminal position, including an interrupted partial epoch.

  • position_min_monitor (Position (dict[str, Any]) | None) – Position with the smallest finite monitoring loss, or None if no finite monitoring loss was recorded. For exact validation and full-training monitors, this is the post-update position used for that loss evaluation. For an EMA, it is the associated parameter snapshot, not a position whose exact loss equals the EMA.

  • n_epochs (int) – Number of completed epochs included in the processed history.

  • min_monitor_epoch (int | None) – Epoch at which the smallest finite monitoring loss was recorded, or None if no finite monitoring loss was recorded.

  • monitor_source (Literal['train_ema', 'validation', 'train_full_data']) – Configured monitoring source: "train_ema", "validation", or "train_full_data".

  • patience (int) – Patience configured for early stopping, measured in epochs.

  • duration (float) – Cumulative active runtime in seconds, including checkpoint writes and excluding time paused between calls.

  • nan_debug (OptimNaNDebugInfo | None, default: None) – Reproduction data for the first captured NaN when engine NaN debugging was enabled, otherwise None.

  • checkpoint (OptimCheckpoint | None, default: None) – Explicit resumable state. None on NaN failure. History arrays are shared with this result; continuation leaves earlier results unchanged.

  • status (Literal['paused', 'max_epochs', 'early_stopping', 'nan'], default: 'max_epochs') – Why fitting returned: "paused", "max_epochs", "early_stopping", or "nan". Stopping conditions take precedence over a pause boundary.

Examples

>>> import jax.numpy as jnp
>>> from liesel.optim import OptimResult
>>> from liesel.optim import OptimHistory
>>> from liesel.optim.types import Position
>>> history = OptimHistory.from_epochs(epochs=2, position=None)
>>> position_final = Position({"theta": jnp.array(2.0)})
>>> position_min_monitor = Position({"theta": jnp.array(1.0)})
>>> result = OptimResult(
...     history=history,
...     position_final=position_final,
...     position_min_monitor=position_min_monitor,
...     n_epochs=2,
...     min_monitor_epoch=0,
...     monitor_source="validation",
...     patience=1,
...     duration=0.25,
... )
>>> result
OptimResult(n_epochs=2, ..., duration=0.2s)

Methods

plot_loss([legend, title, window])

Plots the epoch-mean training loss and configured monitoring loss.

plot_loss_overview([window])

Plot the full loss history above a recent convergence window.

plot_params([position, legend, title, ...])

Plots saved parameter histories.

Attributes

checkpoint

Explicit resumable state.

nan_debug

Reproduction data for the first captured NaN when engine NaN debugging was enabled, otherwise None.

position_final

Terminal parameters, including a finite interrupted partial epoch.

position_min_monitor

Parameters saved at the smallest finite monitoring loss.

status

"paused", "max_epochs", "early_stopping", or "nan".

history

Processed optimizer history.

n_epochs

Number of completed epochs included in the processed history.

min_monitor_epoch

Epoch at which the smallest finite monitoring loss was recorded, or None if no finite monitoring loss was recorded.

monitor_source

"train_ema", "validation", or "train_full_data".

patience

Patience configured for early stopping, measured in epochs.

duration

Cumulative active runtime in seconds, including checkpoint writes and excluding time paused between calls.
Contents