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[source]

Bases: CountHistoryBase

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

get_fval_trace(ix=None, trim=False)[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 type:

Union[Sequence[float], float]

Parameters:
get_grad_trace(ix=None, trim=False)[source]

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 type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_hess_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_res_trace(ix=None, trim=False)[source]

Residuals.

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

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_sres_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_time_trace(ix=None, trim=False)[source]

Cumulative execution times [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_x_trace(ix=None, trim=False)[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.

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
class pypesto.history.CountHistoryBase[source]

Bases: HistoryBase

Abstract class tracking counts of function evaluations.

Needs a separate implementation of trace.

__init__(options=None)[source]
Parameters:

options (HistoryOptions | dict) –

property exitflag: str

Return exitflag.

finalize(message=None, exitflag=None)[source]

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

Parameters:

  • message (str) – Optimizer message to be saved.

  • exitflag (str) – Optimizer exitflag to be saved.

Return type:

None

property message: str

Return message.

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, sensi_orders, mode, result)[source]

Update history after a function evaluation.

Parameters:

  • x (ndarray) – The parameter vector.

  • sensi_orders (tuple[int, ...]) – The sensitivity orders computed.

  • mode (Literal['mode_fun', 'mode_res']) – The objective function mode computed (function value or residuals).

  • result (dict[str, Union[float, ndarray]]) – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

Return type:

None

class pypesto.history.CsvAmiciHistory[source]

Bases: CsvHistory

Stores history extended by AMICI-specific time traces in a CSV file.

Stores AMICI-specific traces of total simulation time, pre-equilibration time and post-equilibration time.

Parameters:

  • file (str) – CSV file name.

  • x_names (Sequence[str]) – Parameter names.

  • options (Union[HistoryOptions, dict]) – History options.

  • load_from_file (bool) – If True, history will be initialized from data in the specified file.

__init__(file, x_names=None, options=None, load_from_file=False)[source]
Parameters:
get_cpu_time_total_trace(ix=None, trim=False)[source]

Cumulative simulation CPU time [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_posteq_timeB_trace(ix=None, trim=False)[source]

Cumulative post-equilibration time of the backward problem [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_posteq_time_trace(ix=None, trim=False)[source]

Cumulative post-equilibration time [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_preeq_timeB_trace(ix=None, trim=False)[source]

Cumulative pre-equilibration time of the backward problem [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_preeq_time_trace(ix=None, trim=False)[source]

Cumulative pre-equilibration time [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
class pypesto.history.CsvHistory[source]

Bases: CountHistoryBase

Stores a representation of the history in a CSV file.

Parameters:

  • file (str) – CSV file name.

  • x_names (Sequence[str]) – Parameter names.

  • options (Union[HistoryOptions, dict]) – History options.

  • load_from_file (bool) – If True, history will be initialized from data in the specified file.

__init__(file, x_names=None, options=None, load_from_file=False)[source]
Parameters:
finalize(message=None, exitflag=None)[source]

See HistoryBase.finalize().

Parameters:

  • message (str) –

  • exitflag (str) –

get_fval_trace(ix, trim=False)[source]

See HistoryBase.get_fval_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_grad_trace(ix=None, trim=False)[source]

See HistoryBase.get_grad_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_hess_trace(ix=None, trim=False)[source]

See HistoryBase.get_hess_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_res_trace(ix=None, trim=False)[source]

See HistoryBase.get_res_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_sres_trace(ix=None, trim=False)[source]

See HistoryBase.get_sres_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_time_trace(ix=None, trim=False)[source]

See HistoryBase.get_time_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_x_trace(ix=None, trim=False)[source]

See HistoryBase.get_x_trace().

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
update(x, sensi_orders, mode, result)[source]

See HistoryBase.update().

Return type:

None

Parameters:
exception pypesto.history.CsvHistoryTemplateError[source]

Bases: ValueError

Error raised when no template is given for CSV history.

__init__(storage_file)[source]
Parameters:

storage_file (str) –

class pypesto.history.Hdf5AmiciHistory[source]

Bases: Hdf5History

Stores history extended by AMICI-specific time traces in an HDF5 file.

Stores AMICI-specific traces of total simulation time, pre-equilibration time and post-equilibration time.

Parameters:
__init__(id, file, options=None)[source]
Parameters:
get_cpu_time_total_trace(ix=None, trim=False)[source]

Cumulative simulation CPU time [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_posteq_timeB_trace(ix=None, trim=False)[source]

Cumulative post-equilibration time of the backward problem [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_posteq_time_trace(ix=None, trim=False)[source]

Cumulative post-equilibration time [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_preeq_timeB_trace(ix=None, trim=False)[source]

Cumulative pre-equilibration time of the backward problem, [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_preeq_time_trace(ix=None, trim=False)[source]

Cumulative pre-equilibration time, [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
class pypesto.history.Hdf5History[source]

Bases: HistoryBase

Stores a representation of the history in an HDF5 file.

Parameters:
__init__(id, file, options=None)[source]
Parameters:
property exitflag: str

Optimizer exitflag in case of finished optimization.

finalize(message=None, exitflag=None)[source]

See HistoryBase.finalize.

Return type:

None

Parameters:

  • message (str) –

  • exitflag (str) –

static from_history(other, file, id_, overwrite=False)[source]

Write some History to HDF5.

Parameters:

  • other (HistoryBase) – History to be copied to HDF5.

  • file (Union[str, Path]) – HDF5 file to write to (append or create).

  • id – ID of the history.

  • overwrite (bool) – Whether to overwrite an existing history with the same id. Defaults to False.

  • id_ (str) –

Return type:

Hdf5History

Returns:

The newly created Hdf5History.

get_fval_trace(ix=None, trim=False)[source]

See HistoryBase.get_fval_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_grad_trace(ix=None, trim=False)[source]

See HistoryBase.get_grad_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_hess_trace(ix=None, trim=False)[source]

See HistoryBase.get_hess_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_res_trace(ix=None, trim=False)[source]

See HistoryBase.get_res_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_sres_trace(ix=None, trim=False)[source]

See HistoryBase.get_sres_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_time_trace(ix=None, trim=False)[source]

See HistoryBase.get_time_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_x_trace(ix=None, trim=False)[source]

See HistoryBase.get_x_trace().

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
static load(id, file, options=None)[source]

Load the History object from memory.

Return type:

Hdf5History

Parameters:
property message: str

Optimizer message in case of finished optimization.

property n_fval: int

See HistoryBase.n_fval().

property n_grad: int

See HistoryBase.n_grad().

property n_hess: int

See HistoryBase.n_hess().

property n_res: int

See HistoryBase.n_res().

property n_sres: int

See HistoryBase.n_sres().

recover_options(file)[source]

Recover options when loading the hdf5 history from memory.

Done by testing which entries were recorded.

Parameters:

file (str | Path) –

property start_time: float

See HistoryBase.start_time().

property trace_save_iter: int

After how many iterations to store the trace.

update(x, sensi_orders, mode, result)[source]

See HistoryBase.update().

Return type:

None

Parameters:
class pypesto.history.HistoryBase[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=None)[source]
Parameters:

options (HistoryOptions | None) –

abstract property exitflag: str

Return exitflag.

finalize(message=None, exitflag=None)[source]

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

Parameters:

  • message (Optional[str]) – Optimizer message to be saved.

  • exitflag (Optional[str]) – Optimizer exitflag to be saved.

Return type:

None

get_chi2_trace(ix=None, trim=False)[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.

Return type:

Union[Sequence[float], float]

Parameters:
abstract get_fval_trace(ix=None, trim=False)[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 type:

Union[Sequence[float], float]

Parameters:
abstract get_grad_trace(ix=None, trim=False)[source]

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 type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
abstract get_hess_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
abstract get_res_trace(ix=None, trim=False)[source]

Residuals.

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

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_schi2_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
abstract get_sres_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
abstract get_time_trace(ix=None, trim=False)[source]

Cumulative execution times [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_trimmed_indices()[source]

Get indices for a monotonically decreasing history.

Return type:

ndarray

abstract get_x_trace(ix=None, trim=False)[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.

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
implements_trace()[source]

Check whether the history has a trace that can be queried.

Return type:

bool

abstract property message: str

Return message.

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, sensi_orders, mode, result)[source]

Update history after a function evaluation.

Parameters:

  • x (ndarray) – The parameter vector.

  • sensi_orders (tuple[int, ...]) – The sensitivity orders computed.

  • mode (Literal['mode_fun', 'mode_res']) – The objective function mode computed (function value or residuals).

  • result (dict[str, Union[float, ndarray]]) – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

Return type:

None

class pypesto.history.HistoryOptions[source]

Bases: dict

Options for what values to record.

In addition implements a factory pattern to generate history objects.

Parameters:

  • trace_record (bool) – Flag indicating whether to record the trace of function calls. The trace_record_* flags only become effective if trace_record is True. Defaults to False.

  • trace_record_grad (bool) – Flag indicating whether to record the gradient in the trace. Defaults to True.

  • trace_record_hess (bool) – Flag indicating whether to record the Hessian in the trace. Defaults to True.

  • trace_record_res (bool) – Flag indicating whether to record the residual in the trace. Defaults to True.

  • trace_record_sres (bool) – Flag indicating whether to record the residual sensitivities in the trace. Defaults to True.

  • trace_save_iter (int) – After how many iterations to store the trace. Defaults to 10.

  • storage_file (Union[str, Path, None]) – 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. Defaults to None.

__init__(trace_record=False, trace_record_grad=True, trace_record_hess=True, trace_record_res=True, trace_record_sres=True, trace_save_iter=10, storage_file=None)[source]
Parameters:

  • trace_record (bool) –

  • trace_record_grad (bool) –

  • trace_record_hess (bool) –

  • trace_record_res (bool) –

  • trace_record_sres (bool) –

  • trace_save_iter (int) –

  • storage_file (str | Path | None) –

static assert_instance(maybe_options)[source]

Return a valid options object.

Parameters:

maybe_options (HistoryOptions or dict) –

Return type:

HistoryOptions

exception pypesto.history.HistoryTypeError[source]

Bases: ValueError

Error raised when an unsupported history type is requested.

__init__(history_type)[source]
Parameters:

history_type (str) –

class pypesto.history.MemoryHistory[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 (Union[HistoryOptions, dict, None]) – History options, see pypesto.history.HistoryOptions. Defaults to None, which implies default options.

__init__(options=None)[source]
Parameters:

options (HistoryOptions | dict | None) –

get_fval_trace(ix=None, trim=False)[source]

See HistoryBase.get_fval_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_grad_trace(ix=None, trim=False)[source]

See HistoryBase.get_grad_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_hess_trace(ix=None, trim=False)[source]

See HistoryBase.get_hess_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_res_trace(ix=None, trim=False)[source]

See HistoryBase.get_res_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_sres_trace(ix=None, trim=False)[source]

See HistoryBase.get_sres_trace().

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_time_trace(ix=None, trim=False)[source]

See HistoryBase.get_time_trace().

Return type:

Union[Sequence[float], float]

Parameters:
get_x_trace(ix=None, trim=False)[source]

See HistoryBase.get_x_trace().

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
update(x, sensi_orders, mode, result)[source]

See HistoryBase.update().

Return type:

None

Parameters:
class pypesto.history.NoHistory[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.

property exitflag: float

Return exitflag.

get_fval_trace(ix=None, trim=False)[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 type:

Union[Sequence[float], float]

Parameters:
get_grad_trace(ix=None, trim=False)[source]

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 type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_hess_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_res_trace(ix=None, trim=False)[source]

Residuals.

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

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_sres_trace(ix=None, trim=False)[source]

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.

Return type:

Union[Sequence[Union[ndarray, nan]], ndarray, nan]

Parameters:
get_time_trace(ix=None, trim=False)[source]

Cumulative execution times [s].

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

Return type:

Union[Sequence[float], float]

Parameters:
get_x_trace(ix=None, trim=False)[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.

Return type:

Union[Sequence[ndarray], ndarray]

Parameters:
property message: float

Return message.

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, sensi_orders, mode, result)[source]

Update history after a function evaluation.

Parameters:

  • x (ndarray) – The parameter vector.

  • sensi_orders (tuple[int, ...]) – The sensitivity orders computed.

  • mode (Literal['mode_fun', 'mode_res']) – The objective function mode computed (function value or residuals).

  • result (dict[str, Union[float, ndarray]]) – The objective function values for parameters x, sensitivities sensi_orders and mode mode.

Return type:

None

class pypesto.history.OptimizerHistory[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 (HistoryBase) – History object to attach to this container. This history object implements the storage of the actual history.

  • x0 (ndarray) – Initial values for optimization.

  • lb (ndarray) – Lower and upper bound. Used for checking validity of optimal points.

  • ub (ndarray) – Lower and upper bound. Used for checking validity of optimal points.

  • generate_from_history (bool) – If set to true, this function will try to fill attributes of this function based on the provided history. Defaults to False.

MIN_KEYS = ('x', 'fval', 'grad', 'hess', 'res', 'sres')
__init__(history, x0, lb, ub, generate_from_history=False)[source]
Parameters:
Return type:

None

finalize(message=None, exitflag=None)[source]

Finalize history.

Parameters:

  • message (Optional[str]) – Optimizer message to be saved. Defaults to None.

  • exitflag (Optional[int]) – Optimizer exitflag to be saved. Defaults to None.

update(x, sensi_orders, mode, result)[source]

Update history and best found value.

Parameters:

  • x (ndarray) – Current parameter vector.

  • sensi_orders (tuple[int]) – Sensitivity orders to be evaluated.

  • mode (Literal['mode_fun', 'mode_res']) – Mode of the evaluation.

  • result (dict[str, Union[float, ndarray]]) – Current result.

Return type:

None

pypesto.history.create_history(id, x_names, options)[source]

Create a HistoryBase object; Factory method.

Parameters:
Return type:

HistoryBase

Returns:

A history object corresponding to the inputs.