pypesto.history

History

Objetive function call history. The history tracks and stores function evaluations performed by e.g. the optimizer and other routines, allowing to e.g. recover results from failed runs, fill in further details, and evaluate performance.

class pypesto.history.CountHistory(options: HistoryOptions | Dict | None = None)[source]

Bases: CountHistoryBase

History that can only count, other functions cannot be invoked.

get_fval_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

get_time_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

get_x_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[ndarray] | ndarray[source]

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

class pypesto.history.CountHistoryBase(options: HistoryOptions | Dict | None = None)[source]

Bases: HistoryBase

Abstract class tracking counts of function evaluations.

Needs a separate implementation of trace.

__init__(options: HistoryOptions | Dict | None = None)[source]

property n_fval: int: Return number of function evaluations.

property n_grad: int: Return number of gradient evaluations.

property n_hess: int: Return number of Hessian evaluations.

property n_res: int: Return number of residual evaluations.

property n_sres: int: Return number or residual sensitivity evaluations.

property start_time: float: Return start time.

update(x: ndarray, sensi_orders: Tuple[int, ...], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]

Update history after a function evaluation.

Parameters:

x – The parameter vector.
sensi_orders – The sensitivity orders computed.
mode – The objective function mode computed (function value or residuals).
result – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

class pypesto.history.CsvHistory(file: str, x_names: Sequence[str] | None = None, options: HistoryOptions | Dict | None = None, load_from_file: bool = False)[source]

Bases: CountHistoryBase

Stores a representation of the history in a CSV file.

Parameters:

file – CSV file name.
x_names – Parameter names.
options – History options.
load_from_file – If True, history will be initialized from data in the specified file

__init__(file: str, x_names: Sequence[str] | None = None, options: HistoryOptions | Dict | None = None, load_from_file: bool = False)[source]

finalize(message: str | None = None, exitflag: str | None = None)[source]: See HistoryBase docstring.

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

update(x: ndarray, sensi_orders: Tuple[int, ...], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]: See History docstring.

exception pypesto.history.CsvHistoryTemplateError(storage_file: str)[source]

Bases: ValueError

Error raised when no template is given for CSV history.

__init__(storage_file: str)[source]

class pypesto.history.Hdf5History(id: str, file: str, options: HistoryOptions | Dict | None = None)[source]

Bases: HistoryBase

Stores a representation of the history in an HDF5 file.

Parameters:

id – Id of the history
file – HDF5 file name.
options – History options.

__init__(id: str, file: str, options: HistoryOptions | Dict | None = None)[source]

property exitflag

finalize(*args, **kwargs)[source]

Finalize history. Called after a run. Default: Do nothing.

Parameters:

message – Optimizer message to be saved.
exitflag – Optimizer exitflag to be saved.

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

static load(id: str, file: str, options: HistoryOptions | Dict | None = None) → Hdf5History[source]: Load the History object from memory.

property message

property n_fval: Return number of function evaluations.

property n_grad: Return number of gradient evaluations.

property n_hess: Return number of Hessian evaluations.

property n_res: Return number of residual evaluations.

property n_sres: Return number or residual sensitivity evaluations.

recover_options(file: str)[source]

Recover options when loading the hdf5 history from memory.

Done by testing which entries were recorded.

property start_time: Return start time.

property trace_save_iter

update(*args, **kwargs)[source]

Update history after a function evaluation.

Parameters:

x – The parameter vector.
sensi_orders – The sensitivity orders computed.
mode – The objective function mode computed (function value or residuals).
result – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

class pypesto.history.HistoryBase(options: HistoryOptions | None = None)[source]

Bases: ABC

Abstract base class for histories.

ALL_KEYS = ('x', 'fval', 'grad', 'hess', 'res', 'sres', 'time')

RESULT_KEYS = ('fval', 'grad', 'hess', 'res', 'sres')

__init__(options: HistoryOptions | None = None)[source]

finalize(message: str | None = None, exitflag: str | None = None) → None[source]

Finalize history. Called after a run. Default: Do nothing.

Parameters:

message – Optimizer message to be saved.
exitflag – Optimizer exitflag to be saved.

get_chi2_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Chi2 values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

abstract get_fval_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Chi2 sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

abstract get_time_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

get_trimmed_indices() → ndarray[source]: Get indices for a monotonically decreasing history.

abstract get_x_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[ndarray] | ndarray[source]

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

implements_trace() → bool[source]: Check whether the history has a trace that can be queried.

abstract property n_fval: int: Return number of function evaluations.

abstract property n_grad: int: Return number of gradient evaluations.

abstract property n_hess: int: Return number of Hessian evaluations.

abstract property n_res: int: Return number of residual evaluations.

abstract property n_sres: int: Return number or residual sensitivity evaluations.

abstract property start_time: float: Return start time.

abstract update(x: ndarray, sensi_orders: Tuple[int, ...], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]

Update history after a function evaluation.

Parameters:

x – The parameter vector.
sensi_orders – The sensitivity orders computed.
mode – The objective function mode computed (function value or residuals).
result – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

class pypesto.history.HistoryOptions(trace_record: bool = False, trace_record_grad: bool = True, trace_record_hess: bool = True, trace_record_res: bool = True, trace_record_sres: bool = True, trace_save_iter: int = 10, storage_file: str | None = None)[source]

Bases: dict

Options for what values to record.

In addition implements a factory pattern to generate history objects.

Parameters:

trace_record – Flag indicating whether to record the trace of function calls. The trace_record_* flags only become effective if trace_record is True.
trace_record_grad – Flag indicating whether to record the gradient in the trace.
trace_record_hess – Flag indicating whether to record the Hessian in the trace.
trace_record_res – Flag indicating whether to record the residual in the trace.
trace_record_sres – Flag indicating whether to record the residual sensitivities in the trace.
trace_save_iter – After how many iterations to store the trace.
storage_file – File to save the history to. Can be any of None, a “{filename}.csv”, or a “{filename}.hdf5” file. Depending on the values, the create_history method creates the appropriate object. Occurrences of “{id}” in the file name are replaced by the id upon creation of a history, if applicable.

__init__(trace_record: bool = False, trace_record_grad: bool = True, trace_record_hess: bool = True, trace_record_res: bool = True, trace_record_sres: bool = True, trace_save_iter: int = 10, storage_file: str | None = None)[source]

static assert_instance(maybe_options: HistoryOptions | Dict) → HistoryOptions[source]

Return a valid options object.

Parameters:: maybe_options (HistoryOptions or dict) –

exception pypesto.history.HistoryTypeError(history_type: str)[source]

Bases: ValueError

Error raised when an unsupported history type is requested.

__init__(history_type: str)[source]

class pypesto.history.MemoryHistory(options: HistoryOptions | Dict | None = None)[source]

Bases: CountHistoryBase

Class for optimization history stored in memory.

Tracks number of function evaluations and keeps an in-memory trace of function evaluations.

Parameters:: options (pypesto.history.options.HistoryOptions) – History options.

__init__(options: HistoryOptions | Dict | None = None)[source]

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

update(x: ndarray, sensi_orders: Tuple[int, ...], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]: See History docstring.

class pypesto.history.NoHistory(options: HistoryOptions | None = None)[source]

Bases: HistoryBase

Dummy history that does not do anything.

Can be used whenever a history object is needed, but no history is desired. Can be created, but not queried.

get_fval_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Return function values.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return gradients.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Return hessians.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residuals.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

Residual sensitivities.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

get_time_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[float] | float[source]

Cumulative execution times.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

get_x_trace(ix: int | Sequence[int] | None = None, trim: bool = False) → Sequence[ndarray] | ndarray[source]

Return parameters.

Takes as parameter an index or indices and returns corresponding trace values. If only a single value is requested, the list is flattened.

property n_fval: int: Return number of function evaluations.

property n_grad: int: Return number of gradient evaluations.

property n_hess: int: Return number of Hessian evaluations.

property n_res: int: Return number of residual evaluations.

property n_sres: int: Return number or residual sensitivity evaluations.

property start_time: float: Return start time.

update(x: ndarray, sensi_orders: Tuple[int, ...], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]

Update history after a function evaluation.

Parameters:

x – The parameter vector.
sensi_orders – The sensitivity orders computed.
mode – The objective function mode computed (function value or residuals).
result – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

class pypesto.history.OptimizerHistory(history: HistoryBase, x0: ndarray, lb: ndarray, ub: ndarray, generate_from_history: bool = False)[source]

Bases: object

Optimizer objective call history.

Container around a History object, additionally keeping track of optimal values.

fval0, fval_min: Initial and best function value found.

x0, x_min: Initial and best parameters found.

grad_min: gradient for best parameters

hess_min: hessian (approximation) for best parameters

res_min: residuals for best parameters

sres_min: residual sensitivities for best parameters

Parameters:

history – History object to attach to this container. This history object implements the storage of the actual history.
x0 – Initial values for optimization.
lb – Lower and upper bound. Used for checking validity of optimal points.
ub – Lower and upper bound. Used for checking validity of optimal points.
generate_from_history – If set to true, this function will try to fill attributes of this function based on the provided history.

MIN_KEYS = ('x', 'fval', 'grad', 'hess', 'res', 'sres')

__init__(history: HistoryBase, x0: ndarray, lb: ndarray, ub: ndarray, generate_from_history: bool = False) → None[source]

finalize(message: str | None = None, exitflag: int | None = None)[source]

Finalize history.

Parameters:

message – Optimizer message to be saved.
exitflag – Optimizer exitflag to be saved.

update(x: ndarray, sensi_orders: Tuple[int], mode: Literal['mode_fun', 'mode_res'], result: Dict[str, float | ndarray]) → None[source]: Update history and best found value.

pypesto.history.create_history(id: str, x_names: Sequence[str], options: HistoryOptions) → HistoryBase[source]

Create a HistoryBase object; Factory method.

Parameters:

id – Identifier for the history.
x_names – Parameter names.
options – History options.

Returns:

A history object corresponding to the inputs.

Return type:

history