OptimHistory

class liesel.optim.OptimHistory(loss_train, loss_monitor, position)

Bases: object

Stores loss values and optional position histories for optimizer runs.

OptimHistory is allocated before an optimization starts. Loss arrays are initialized with jnp.inf. Position histories, when requested, are initialized with zeros and updated epoch by epoch by OptimEngine.

Parameters:

• loss_train (Array) – Equal-weight mean of the pre-update losses within each completed epoch, with shape (epochs,). The first active optimizer supplies each batch value; a batch with no active optimizer is evaluated once at the unchanged position. Because parameters may change between batches, this summarizes the optimization trajectory; it is not a full-data loss evaluated at the epoch’s final position.

• loss_monitor (Array) – Epoch-level series used for stopping and identifying the minimum-monitor position, with shape (epochs,). Depending on the source, this is a training EMA, complete validation loss, or complete training loss. Exact losses use the post-update epoch position. An EMA snapshot summarizes several positions, so its associated parameter snapshot is not an exact loss-position pair.

• position (Position (dict[str, Any]) | None) – Optional parameter position history. Each array has a leading epoch dimension.

Examples

>>> import jax.numpy as jnp
>>> from liesel.optim import OptimHistory
>>> from liesel.optim.types import Position
>>> position = Position({"theta": jnp.array([1.0, 2.0])})
>>> history = OptimHistory.from_epochs(epochs=3, position=position)
>>> history.loss_train.shape
(3,)
>>> history.position["theta"].shape
(3, 2)
>>> history
OptimHistory(len=3)

Methods

from_epochs(epochs, position[, loss_dtype])	Allocates an empty optimizer history for a fixed number of epochs.
init_position_history(position, epochs)	Allocates zero-filled arrays for a position history.
loss_df()	Converts training and monitoring losses into a pandas.DataFrame.
position_df([subset])	Converts the saved parameter position history into a data frame.
update_position_history(i, position_history, ...)	Writes a position into a position history at one epoch index.

Attributes

loss_train	Equal-weight mean of the pre-update losses within each completed epoch, with shape (epochs,).
loss_monitor	Epoch-level series used for stopping and identifying the minimum-monitor position, with shape (epochs,).
position	Optional parameter position history.