API reference

pyPESTO

Parameter Estimation TOolbox for python.

class pypesto.AmiciObjective(amici_model: Union[amici.Model, amici.ModelPtr], amici_solver: Union[amici.Solver, amici.SolverPtr], edatas: Union[Sequence[amici.ExpData], amici.ExpData], max_sensi_order: Optional[int] = None, x_ids: Optional[Sequence[str]] = None, x_names: Optional[Sequence[str]] = None, parameter_mapping: Optional[ParameterMapping] = None, guess_steadystate: Optional[bool] = None, n_threads: Optional[int] = 1, fim_for_hess: Optional[bool] = True, amici_object_builder: Optional[pypesto.objective.amici.AmiciObjectBuilder] = None, calculator: Optional[pypesto.objective.amici_calculator.AmiciCalculator] = None)[source]

Bases: pypesto.objective.base.ObjectiveBase

Allows to create an objective directly from an amici model.

__init__(amici_model: Union[amici.Model, amici.ModelPtr], amici_solver: Union[amici.Solver, amici.SolverPtr], edatas: Union[Sequence[amici.ExpData], amici.ExpData], max_sensi_order: Optional[int] = None, x_ids: Optional[Sequence[str]] = None, x_names: Optional[Sequence[str]] = None, parameter_mapping: Optional[ParameterMapping] = None, guess_steadystate: Optional[bool] = None, n_threads: Optional[int] = 1, fim_for_hess: Optional[bool] = True, amici_object_builder: Optional[pypesto.objective.amici.AmiciObjectBuilder] = None, calculator: Optional[pypesto.objective.amici_calculator.AmiciCalculator] = None)[source]

Initialize objective.

Parameters
  • amici_model – The amici model.

  • amici_solver – The solver to use for the numeric integration of the model.

  • edatas – The experimental data. If a list is passed, its entries correspond to multiple experimental conditions.

  • max_sensi_order – Maximum sensitivity order supported by the model. Defaults to 2 if the model was compiled with o2mode, otherwise 1.

  • x_ids – Ids of optimization parameters. In the simplest case, this will be the AMICI model parameters (default).

  • x_names – Names of optimization parameters.

  • parameter_mapping – Mapping of optimization parameters to model parameters. Format as created by amici.petab_objective.create_parameter_mapping. The default is just to assume that optimization and simulation parameters coincide.

  • guess_steadystate – Whether to guess steadystates based on previous steadystates and respective derivatives. This option may lead to unexpected results for models with conservation laws and should accordingly be deactivated for those models.

  • n_threads – Number of threads that are used for parallelization over experimental conditions. If amici was not installed with openMP support this option will have no effect.

  • fim_for_hess – Whether to use the FIM whenever the Hessian is requested. This only applies with forward sensitivities. With adjoint sensitivities, the true Hessian will be used, if available. FIM or Hessian will only be exposed if max_sensi_order>1.

  • amici_object_builder – AMICI object builder. Allows recreating the objective for pickling, required in some parallelization schemes.

  • calculator – Performs the actual calculation of the function values and derivatives.

apply_custom_timepoints()None[source]

Apply custom timepoints, if applicable.

See the set_custom_timepoints method for more information.

apply_steadystate_guess(condition_ix: int, x_dct: Dict)None[source]

Apply steady state guess to edatas[condition_ix].x0.

Use the stored steadystate as well as the respective sensitivity ( if available) and parameter value to approximate the steadystate at the current parameters using a zeroth or first order taylor approximation: x_ss(x’) = x_ss(x) [+ dx_ss/dx(x)*(x’-x)]

call_unprocessed(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, edatas: Sequence[amici.ExpData] = None, parameter_mapping: ParameterMapping = None)[source]

Call objective function without pre- or post-processing and formatting.

Returns

A dict containing the results.

Return type

result

check_gradients_match_finite_differences(x: Optional[numpy.ndarray] = None, *args, **kwargs)bool[source]

Check if gradients match finite differences (FDs).

Parameters

x (The parameters for which to evaluate the gradient.) –

Returns

Indicates whether gradients match (True) FDs or not (False)

Return type

bool

check_mode(mode: str)bool[source]

See ObjectiveBase documentation.

check_sensi_orders(sensi_orders: Tuple[int, ], mode: str)bool[source]

See ObjectiveBase documentation.

get_config()dict[source]

Return basic information of the objective configuration.

initialize()[source]

See ObjectiveBase documentation.

par_arr_to_dct(x: Sequence[float])Dict[str, float][source]

Create dict from parameter vector.

reset_steadystate_guesses()None[source]

Reset all steadystate guess data.

set_custom_timepoints(timepoints: Optional[Sequence[Sequence[Union[float, int]]]] = None, timepoints_global: Optional[Sequence[Union[float, int]]] = None)pypesto.objective.amici.AmiciObjective[source]

Create a copy of this objective that is evaluated at custom timepoints.

The intended use is to aid in predictions at unmeasured timepoints.

Parameters
  • timepoints – The outer sequence should contain a sequence of timepoints for each experimental condition.

  • timepoints_global – A sequence of timepoints that will be used for all experimental conditions.

Returns

Return type

The customized copy of this objective.

store_steadystate_guess(condition_ix: int, x_dct: Dict, rdata: amici.ReturnData)None[source]

Store condition parameter, steadystate and steadystate sensitivity.

Stored in steadystate_guesses if steadystate guesses are enabled for this condition.

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

Bases: pypesto.objective.history.History

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: Optional[Sequence[str]] = None, options: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None, load_from_file: bool = False)[source]

Initialize self. See help(type(self)) for accurate signature.

finalize()[source]

Finalize history. Called after a run.

get_chi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_fval_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_grad_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_hess_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_res_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_schi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_sres_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_time_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

update(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, result: Dict[str, Union[float, numpy.ndarray]])None[source]

See History docstring.

class pypesto.FD(obj: pypesto.objective.base.ObjectiveBase, grad: Optional[bool] = None, hess: Optional[bool] = None, sres: Optional[bool] = None, hess_via_fval: bool = True, delta_fun: Union[pypesto.objective.finite_difference.FDDelta, numpy.ndarray, float, str] = 1e-06, delta_grad: Union[pypesto.objective.finite_difference.FDDelta, numpy.ndarray, float, str] = 1e-06, delta_res: Union[pypesto.objective.finite_difference.FDDelta, float, numpy.ndarray, str] = 1e-06, method: str = 'central', x_names: Optional[List[str]] = None)[source]

Bases: pypesto.objective.base.ObjectiveBase

Finite differences (FDs) for derivatives.

Given an objective that gives function values and/or residuals, this class allows to flexibly obtain all derivatives calculated via FDs.

For the parameters grad, hess, sres, a value of None means that the objective derivative is used if available, otherwise resorting to FDs. True means that FDs are used in any case, False means that the derivative is not exported.

Note that the step sizes should be carefully chosen. They should be small enough to provide an accurate linear approximation, but large enough to be robust against numerical inaccuracies, in particular if the objective relies on numerical approximations, such as an ODE.

Parameters
  • grad – Derivative method for the gradient (see above).

  • hess – Derivative method for the Hessian (see above).

  • sres – Derivative method for the residual sensitivities (see above).

  • hess_via_fval – If the Hessian is to be calculated via finite differences: whether to employ 2nd order FDs via fval even if the objective can provide a gradient.

  • delta_fun – FD step sizes for function values. Can be either a float, or a np.ndarray of shape (n_par,) for different step sizes for different coordinates.

  • delta_grad – FD step sizes for gradients, if the Hessian is calculated via 1st order sensitivities from the gradients. Similar to delta_fun.

  • delta_res – FD step sizes for residuals. Similar to delta_fun.

  • method – Method to calculate FDs. Can be any of FD.METHODS: central, forward or backward differences. The latter two require only roughly half as many function evaluations, are however less accurate than central (O(x) vs O(x**2)).

  • x_names – Parameter names that can be optionally used in, e.g., history or gradient checks.

Examples

Define residuals and objective function, and obtain all derivatives via FDs:

>>> from pypesto import Objective, FD
>>> import numpy as np
>>> x_obs = np.array([11, 12, 13])
>>> res = lambda x: x - x_obs
>>> fun = lambda x: 0.5 * sum(res(x)**2)
>>> obj = FD(Objective(fun=fun, res=res))
BACKWARD = 'backward'
CENTRAL = 'central'
FORWARD = 'forward'
METHODS = ['central', 'forward', 'backward']
__init__(obj: pypesto.objective.base.ObjectiveBase, grad: Optional[bool] = None, hess: Optional[bool] = None, sres: Optional[bool] = None, hess_via_fval: bool = True, delta_fun: Union[pypesto.objective.finite_difference.FDDelta, numpy.ndarray, float, str] = 1e-06, delta_grad: Union[pypesto.objective.finite_difference.FDDelta, numpy.ndarray, float, str] = 1e-06, delta_res: Union[pypesto.objective.finite_difference.FDDelta, float, numpy.ndarray, str] = 1e-06, method: str = 'central', x_names: Optional[List[str]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

call_unprocessed(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, **kwargs)Dict[str, Union[float, numpy.ndarray, Dict]][source]

See ObjectiveBase for more documentation.

Main method to overwrite from the base class. It handles and delegates the actual objective evaluation.

property has_fun

Check whether function is defined.

property has_grad

Check whether gradient is defined.

property has_hess

Check whether Hessian is defined.

property has_res

Check whether residuals are defined.

property has_sres

Check whether residual sensitivities are defined.

class pypesto.FDDelta(delta: Optional[Union[numpy.ndarray, float]] = None, test_deltas: Optional[numpy.ndarray] = None, update_condition: str = 'constant', max_distance: float = 0.5, max_steps: int = 30)[source]

Bases: object

Finite difference step size with automatic updating.

Reference implementation: https://github.com/ICB-DCM/PESTO/blob/master/private/getStepSizeFD.m

Parameters
  • delta – (Initial) step size, either a float, or a vector of size (n_par,). If not None, this is used as initial step size.

  • test_deltas – Step sizes to try out in step size selection. If None, a range [1e-1, 1e-2, …, 1e-8] is considered.

  • update_condition – A “good” step size may be a local property. Thus, this class allows updating the step size if certain criteria are met, in the pypesto.objective.finite_difference.FDDelta.update() function. FDDelta.CONSTANT means that the step size is only initially selected. FDDelta.DISTANCE means that the step size is updated if the current evaluation point is sufficiently far away from the last training point. FDDelta.STEPS means that the step size is updated max_steps evaluations after the last update. FDDelta.ALWAYS mean that the step size is selected in every call.

  • max_distance – Coefficient on the distance between current and reference point beyond which to update, in the FDDelta.DISTANCE update condition.

  • max_steps – Number of steps after which to update in the FDDelta.STEPS update condition.

ALWAYS = 'always'
CONSTANT = 'constant'
DISTANCE = 'distance'
STEPS = 'steps'
UPDATE_CONDITIONS = ['constant', 'distance', 'steps', 'always']
__init__(delta: Optional[Union[numpy.ndarray, float]] = None, test_deltas: Optional[numpy.ndarray] = None, update_condition: str = 'constant', max_distance: float = 0.5, max_steps: int = 30)[source]

Initialize self. See help(type(self)) for accurate signature.

get()numpy.ndarray[source]

Get delta vector.

update(x: numpy.ndarray, fval: Optional[Union[float, numpy.ndarray]], fun: Callable, fd_method: str)None[source]

Update delta if update conditions are met.

Parameters
  • x – Current parameter vector, shape (n_par,).

  • fval – fun(x), to avoid re-evaluation. Scalar- or vector-valued.

  • fun – Function whose 1st-order derivative to approximate. Scalar- or vector-valued.

  • fd_method – FD method employed by pypesto.objective.finite_difference.FD, see there.

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

Bases: pypesto.objective.history.History

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: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

finalize()[source]

See History docstring.

get_chi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_fval_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_grad_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_hess_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_history_directory()[source]

Return filepath.

get_res_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_schi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_sres_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_time_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

static load(id: str, file: str)[source]

Load the History object from memory.

property n_fval

See HistoryBase docstring.

property n_grad

See HistoryBase docstring.

property n_hess

See HistoryBase docstring.

property n_res

See HistoryBase docstring.

property n_sres

See HistoryBase docstring.

recover_options(file: str)[source]

Recover options when loading the hdf5 history from memory.

Done by testing which entries were recorded.

property trace_save_iter

After how many iterations to store the trace.

update(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, result: Dict[str, Union[float, numpy.ndarray]])None[source]

See History docstring.

class pypesto.History(options: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None)[source]

Bases: pypesto.objective.history.HistoryBase

Track number of function evaluations only, no trace.

Parameters

options – History options.

__init__(options: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

finalize()[source]

See HistoryBase docstring.

property n_fval

See HistoryBase docstring.

property n_grad

See HistoryBase docstring.

property n_hess

See HistoryBase docstring.

property n_res

See HistoryBase docstring.

property n_sres

See HistoryBase docstring.

property start_time

See HistoryBase docstring.

update(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, result: Dict[str, Union[float, numpy.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.HistoryBase[source]

Bases: abc.ABC

Abstract base class for history objects.

Can be used as a dummy history, but does not implement any history functionality.

finalize()[source]

Finalize history. Called after a run.

get_chi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[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.

get_fval_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[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.

get_grad_trace(ix: Optional[Union[int, Sequence[int]]] = None, trim: bool = False)Union[Sequence[Union[numpy.ndarray, np.nan]], numpy.ndarray, np.nan][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.

get_hess_trace(ix: Optional[Union[int, Sequence[int]]] = None, trim: bool = False)Union[Sequence[Union[numpy.ndarray, np.nan]], numpy.ndarray, np.nan][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.

get_res_trace(ix: Optional[Union[int, Sequence[int]]] = None, trim: bool = False)Union[Sequence[Union[numpy.ndarray, np.nan]], numpy.ndarray, np.nan][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.

get_schi2_trace(ix: Optional[Union[int, Sequence[int]]] = None, trim: bool = False)Union[Sequence[Union[numpy.ndarray, np.nan]], numpy.ndarray, np.nan][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.

get_sres_trace(ix: Optional[Union[int, Sequence[int]]] = None, trim: bool = False)Union[Sequence[Union[numpy.ndarray, np.nan]], numpy.ndarray, np.nan][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.

get_time_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[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()[source]

Get indices for a monotonically decreasing history.

get_x_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[numpy.ndarray], numpy.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

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.

property start_time

Return start time.

update(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, result: Dict[str, Union[float, numpy.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.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_record_chi2: bool = True, trace_record_schi2: bool = True, trace_save_iter: int = 10, storage_file: Optional[str] = None)[source]

Bases: dict

Options for the objective that are used in optimization.

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_record_chi2 – Flag indicating whether to record the chi2 in the trace.

  • trace_record_schi2 – Flag indicating whether to record the chi2 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_record_chi2: bool = True, trace_record_schi2: bool = True, trace_save_iter: int = 10, storage_file: Optional[str] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

static assert_instance(maybe_options: Union[pypesto.objective.history.HistoryOptions, Dict])pypesto.objective.history.HistoryOptions[source]

Return a valid options object.

Parameters

maybe_options (HistoryOptions or dict) –

create_history(id: str, x_names: Sequence[str])pypesto.objective.history.History[source]

Create a History object; Factory method.

Parameters
  • id – Identifier for the history.

  • x_names – Parameter names.

class pypesto.McmcPtResult(trace_x: numpy.ndarray, trace_neglogpost: numpy.ndarray, trace_neglogprior: numpy.ndarray, betas: Iterable[float], burn_in: Optional[int] = None, time: float = 0.0, auto_correlation: Optional[float] = None, effective_sample_size: Optional[float] = None, message: Optional[str] = None)[source]

Bases: dict

The result of a sampler run using Markov-chain Monte Carlo.

Currently result object of all supported samplers. Can be used like a dict.

Parameters
  • trace_x ([n_chain, n_iter, n_par]) – Parameters.

  • trace_neglogpost ([n_chain, n_iter]) – Negative log posterior values.

  • trace_neglogprior ([n_chain, n_iter]) – Negative log prior values.

  • betas ([n_chain]) – The associated inverse temperatures.

  • burn_in ([n_chain]) – The burn in index.

  • time ([n_chain]) – The computation time.

  • auto_correlation ([n_chain]) – The estimated chain autcorrelation.

  • effective_sample_size ([n_chain]) – The estimated effective sample size.

  • message (str) – Textual comment on the profile result.

  • Here

  • denotes the number of chains (n_chain) –

  • the number of (n_iter) –

  • (i.e. (iterations) –

  • chain length) (the) –

  • n_par the number of parameters. (and) –

__init__(trace_x: numpy.ndarray, trace_neglogpost: numpy.ndarray, trace_neglogprior: numpy.ndarray, betas: Iterable[float], burn_in: Optional[int] = None, time: float = 0.0, auto_correlation: Optional[float] = None, effective_sample_size: Optional[float] = None, message: Optional[str] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

class pypesto.MemoryHistory(options: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None)[source]

Bases: pypesto.objective.history.History

Class for optimization history stored in memory.

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

Parameters

options – History options.

__init__(options: Optional[Union[pypesto.objective.history.HistoryOptions, Dict]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

get_chi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_fval_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_grad_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_hess_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_res_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_schi2_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_sres_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

get_time_trace(ix: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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: Optional[Union[Sequence[int], int]] = None, trim: bool = False)Union[Sequence[Union[float, numpy.ndarray, np.nan]], float, numpy.ndarray, np.nan][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.

update(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, result: Dict[str, Union[float, numpy.ndarray]])None[source]

See History docstring.

class pypesto.NegLogPriors(objectives: Sequence[pypesto.objective.base.ObjectiveBase], x_names: Optional[Sequence[str]] = None)[source]

Bases: pypesto.objective.aggregated.AggregatedObjective

Aggregates different forms of negative log-prior distributions.

Allows to distinguish priors from the likelihood by testing the type of an objective.

Consists basically of a list of individual negative log-priors, given in self.objectives.

class pypesto.Objective(fun: Optional[Callable] = None, grad: Optional[Union[Callable, bool]] = None, hess: Optional[Callable] = None, hessp: Optional[Callable] = None, res: Optional[Callable] = None, sres: Optional[Union[Callable, bool]] = None, x_names: Optional[Sequence[str]] = None)[source]

Bases: pypesto.objective.base.ObjectiveBase

Objective class.

The objective class allows the user explicitly specify functions that compute the function value and/or residuals as well as respective derivatives.

Denote dimensions n = parameters, m = residuals.

Parameters
  • fun

    The objective function to be minimized. If it only computes the objective function value, it should be of the form

    fun(x) -> float

    where x is an 1-D array with shape (n,), and n is the parameter space dimension.

  • grad

    Method for computing the gradient vector. If it is a callable, it should be of the form

    grad(x) -> array_like, shape (n,).

    If its value is True, then fun should return the gradient as a second output.

  • hess

    Method for computing the Hessian matrix. If it is a callable, it should be of the form

    hess(x) -> array, shape (n, n).

    If its value is True, then fun should return the gradient as a second, and the Hessian as a third output, and grad should be True as well.

  • hessp

    Method for computing the Hessian vector product, i.e.

    hessp(x, v) -> array_like, shape (n,)

    computes the product H*v of the Hessian of fun at x with v.

  • res

    Method for computing residuals, i.e.

    res(x) -> array_like, shape(m,).

  • sres

    Method for computing residual sensitivities. If it is a callable, it should be of the form

    sres(x) -> array, shape (m, n).

    If its value is True, then res should return the residual sensitivities as a second output.

  • x_names – Parameter names. None if no names provided, otherwise a list of str, length dim_full (as in the Problem class). Can be read by the problem.

__init__(fun: Optional[Callable] = None, grad: Optional[Union[Callable, bool]] = None, hess: Optional[Callable] = None, hessp: Optional[Callable] = None, res: Optional[Callable] = None, sres: Optional[Union[Callable, bool]] = None, x_names: Optional[Sequence[str]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

call_unprocessed(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, **kwargs)Dict[str, Union[float, numpy.ndarray, Dict]][source]

Call objective function without pre- or post-processing and formatting.

Returns

A dict containing the results.

Return type

result

get_config()dict[source]

Return basic information of the objective configuration.

property has_fun

Check whether function is defined.

property has_grad

Check whether gradient is defined.

property has_hess

Check whether Hessian is defined.

property has_hessp
property has_res

Check whether residuals are defined.

property has_sres

Check whether residual sensitivities are defined.

class pypesto.ObjectiveBase(x_names: Optional[Sequence[str]] = None)[source]

Bases: abc.ABC

Abstract objective class.

The objective class is a simple wrapper around the objective function, giving a standardized way of calling. Apart from that, it manages several things including fixing of parameters and history.

The objective function is assumed to be in the format of a cost function, log-likelihood function, or log-posterior function. These functions are subject to minimization. For profiling and sampling, the sign is internally flipped, all returned and stored values are however given as returned by this objective function. If maximization is to be performed, the sign should be flipped before creating the objective function.

Parameters

x_names – Parameter names that can be optionally used in, e.g., history or gradient checks.

history

For storing the call history. Initialized by the methods, e.g. the optimizer, in initialize_history().

pre_post_processor

Preprocess input values to and postprocess output values from __call__. Configured in update_from_problem().

__call__(x: numpy.ndarray, sensi_orders: Tuple[int, ] = (0), mode: str = 'mode_fun', return_dict: bool = False, **kwargs)Union[float, numpy.ndarray, Tuple, Dict[str, Union[float, numpy.ndarray, Dict]]][source]

Obtain arbitrary sensitivities.

This is the central method which is always called, also by the get_* methods.

There are different ways in which an optimizer calls the objective function, and in how the objective function provides information (e.g. derivatives via separate functions or along with the function values). The different calling modes increase efficiency in space and time and make the objective flexible.

Parameters
  • x – The parameters for which to evaluate the objective function.

  • sensi_orders – Specifies which sensitivities to compute, e.g. (0,1) -> fval, grad.

  • mode – Whether to compute function values or residuals.

  • return_dict – If False (default), the result is a Tuple of the requested values in the requested order. Tuples of length one are flattened. If True, instead a dict is returned which can carry further information.

Returns

By default, this is a tuple of the requested function values and derivatives in the requested order (if only 1 value, the tuple is flattened). If return_dict, then instead a dict is returned with function values and derivatives indicated by ids.

Return type

result

__init__(x_names: Optional[Sequence[str]] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

abstract call_unprocessed(x: numpy.ndarray, sensi_orders: Tuple[int, ], mode: str, **kwargs)Dict[str, Union[float, numpy.ndarray, Dict]][source]

Call objective function without pre- or post-processing and formatting.

Parameters
  • x – The parameters for which to evaluate the objective function.

  • sensi_orders – Specifies which sensitivities to compute, e.g. (0,1) -> fval, grad.

  • mode – Whether to compute function values or residuals.

Returns

A dict containing the results.

Return type

result

check_grad(x: numpy.ndarray, x_indices: Optional[Sequence[int]] = None, eps: float = 1e-05, verbosity: int = 1, mode: str = 'mode_fun', order: int = 0, detailed: bool = False)pandas.core.frame.DataFrame[source]

Compare gradient evaluation.

Firstly approximate via finite differences, and secondly use the objective gradient.

Parameters
  • x – The parameters for which to evaluate the gradient.

  • x_indices – Indices for which to compute gradients. Default: all.

  • eps – Finite differences step size.

  • verbosity – Level of verbosity for function output. 0: no output, 1: summary for all parameters, 2: summary for individual parameters.

  • mode – Residual (MODE_RES) or objective function value (MODE_FUN) computation mode.

  • order – Derivative order, either gradient (0) or Hessian (1).

  • detailed – Toggle whether additional values are returned. Additional values are function values, and the central difference weighted by the difference in output from all methods (standard deviation and mean).

Returns

gradient, finite difference approximations and error estimates.

Return type

result

check_grad_multi_eps(*args, multi_eps: Optional[Iterable] = None, label: str = 'rel_err', **kwargs)[source]

Compare gradient evaluation.

Equivalent to the ObjectiveBase.check_grad method, except multiple finite difference step sizes are tested. The result contains the lowest finite difference for each parameter, and the corresponding finite difference step size.

Parameters
  • ObjectiveBase.check_grad method parameters. (All) –

  • multi_eps – The finite difference step sizes to be tested.

  • label – The label of the column that will be minimized for each parameter. Valid options are the column labels of the dataframe returned by the ObjectiveBase.check_grad method.

check_gradients_match_finite_differences(*args, x: Optional[numpy.ndarray] = None, x_free: Optional[Sequence[int]] = None, rtol: float = 0.01, atol: float = 0.001, mode: Optional[str] = None, order: int = 0, multi_eps=None, **kwargs)bool[source]

Check if gradients match finite differences (FDs).

Parameters
  • rtol (relative error tolerance) –

  • x (The parameters for which to evaluate the gradient) –

  • x_free (Indices for which to compute gradients) –

  • rtol

  • atol (absolute error tolerance) –

  • mode (function values or residuals) –

  • order (gradient order, 0 for gradient, 1 for hessian) –

  • multi_eps (multiple test step width for FDs) –

Returns

Indicates whether gradients match (True) FDs or not (False)

Return type

bool

check_mode(mode: str)bool[source]

Check if the objective is able to compute in the requested mode.

Either check_mode or the fun_… functions must be overwritten in derived classes.

Parameters

mode – Whether to compute function values or residuals.

Returns

Boolean indicating whether mode is supported

Return type

flag

check_sensi_orders(sensi_orders: Tuple[int, ], mode: str)bool[source]

Check if the objective is able to compute the requested sensitivities.

Either check_sensi_orders or the fun_… functions must be overwritten in derived classes.

Parameters
  • sensi_orders – Specifies which sensitivities to compute, e.g. (0,1) -> fval, grad.

  • mode – Whether to compute function values or residuals.

Returns

Boolean indicating whether combination of sensi_orders and mode is supported

Return type

flag

get_config()dict[source]

Get the configuration information of the objective function.

Return it as a dictonary.

get_fval(x: numpy.ndarray)float[source]

Get the function value at x.

get_grad(x: numpy.ndarray)numpy.ndarray[source]

Get the gradient at x.

get_hess(x: numpy.ndarray)numpy.ndarray[source]

Get the Hessian at x.

get_res(x: numpy.ndarray)numpy.ndarray[source]

Get the residuals at x.

get_sres(x: numpy.ndarray)numpy.ndarray[source]

Get the residual sensitivities at x.

property has_fun

Check whether function is defined.

property has_grad

Check whether gradient is defined.

property has_hess

Check whether Hessian is defined.

property has_hessp
property has_res

Check whether residuals are defined.

property has_sres

Check whether residual sensitivities are defined.

initialize()[source]

Initialize the objective function.

This function is used at the beginning of an analysis, e.g. optimization, and can e.g. reset the objective memory. By default does nothing.

static output_to_tuple(sensi_orders: Tuple[int, ], mode: str, **kwargs: Union[float, numpy.ndarray])Tuple[source]

Return values as requested by the caller.

Usually only a subset of outputs is demanded. One output is returned as-is, more than one output are returned as a tuple in order (fval, grad, hess).

update_from_problem(dim_full: int, x_free_indices: Sequence[int], x_fixed_indices: Sequence[int], x_fixed_vals: Sequence[float])[source]

Handle fixed parameters.

Later, the objective will be given parameter vectors x of dimension dim, which have to be filled up with fixed parameter values to form a vector of dimension dim_full >= dim. This vector is then used to compute function value and derivatives. The derivatives must later be reduced again to dimension dim.

This is so as to make the fixing of parameters transparent to the caller.

The methods preprocess, postprocess are overwritten for the above functionality, respectively.

Parameters
  • dim_full – Dimension of the full vector including fixed parameters.

  • x_free_indices – Vector containing the indices (zero-based) of free parameters (complimentary to x_fixed_indices).

  • x_fixed_indices – Vector containing the indices (zero-based) of parameter components that are not to be optimized.

  • x_fixed_vals – Vector of the same length as x_fixed_indices, containing the values of the fixed parameters.

property x_names

Parameter names.

class pypesto.OptimizeResult[source]

Bases: object

Result of the pypesto.optimize.minimize() function.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

append(optimizer_result: pypesto.result.optimize.OptimizerResult)[source]

Append an optimizer result to the result object.

Parameters

optimizer_result – The result of one (local) optimizer run.

as_dataframe(keys=None)pandas.core.frame.DataFrame[source]

Get as pandas DataFrame.

If keys is a list, return only the specified values, otherwise all.

as_list(keys=None)Sequence[source]

Get as list.

If keys is a list, return only the specified values.

Parameters

keys (list(str), optional) – Labels of the field to extract.

get_for_key(key)list[source]

Extract the list of values for the specified key as a list.

sort()[source]

Sort the optimizer results by function value fval (ascending).

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

Bases: object

Objective call history.

Container around a History object, which keeps track of optimal values.

fval0, fval_min

Initial and best function value found.

chi20, chi2_min

Initial and best chi2 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.

__init__(history: pypesto.objective.history.History, x0: numpy.ndarray, lb: numpy.ndarray, ub: numpy.ndarray, generate_from_history: bool = False)None[source]

Initialize self. See help(type(self)) for accurate signature.

extract_from_history(var: str, ix: int)bool[source]

Get value of var at iteration ix and assign to {var}_min.

Parameters
  • var (Variable to extract, e.g. 'grad', 'x'.) –

  • ix (Trace index.) –

Returns

Whether extraction and assignment worked. False in particular if the history value is nan.

Return type

successful

finalize()[source]

Finalize history.

update(x: numpy.ndarray, sensi_orders: Tuple[int], mode: str, result: Dict[str, Union[float, numpy.ndarray]])None[source]

Update history and best found value.

class pypesto.OptimizerResult(id: Optional[str] = None, x: Optional[numpy.ndarray] = None, fval: Optional[float] = None, grad: Optional[numpy.ndarray] = None, hess: Optional[numpy.ndarray] = None, res: Optional[numpy.ndarray] = None, sres: Optional[numpy.ndarray] = None, n_fval: Optional[int] = None, n_grad: Optional[int] = None, n_hess: Optional[int] = None, n_res: Optional[int] = None, n_sres: Optional[int] = None, x0: Optional[numpy.ndarray] = None, fval0: Optional[float] = None, history: Optional[pypesto.objective.history.History] = None, exitflag: Optional[int] = None, time: Optional[float] = None, message: Optional[str] = None)[source]

Bases: dict

The result of an optimizer run.

Used as a standardized return value to map from the individual result objects returned by the employed optimizers to the format understood by pypesto.

Can be used like a dict.

id

Id of the optimizer run. Usually the start index.

x

The best found parameters.

fval

The best found function value, fun(x).

grad

The gradient at x.

hess

The Hessian at x.

res

The residuals at x.

sres

The residual sensitivities at x.

n_fval

Number of function evaluations.

n_grad

Number of gradient evaluations.

n_hess

Number of Hessian evaluations.

n_res

Number of residuals evaluations.

n_sres

Number of residual sensitivity evaluations.

x0

The starting parameters.

fval0

The starting function value, fun(x0).

history

Objective history.

exitflag

The exitflag of the optimizer.

time

Execution time.

message

Textual comment on the optimization result.

Type

str

Notes

Any field not supported by the optimizer is filled with None.

__init__(id: Optional[str] = None, x: Optional[numpy.ndarray] = None, fval: Optional[float] = None, grad: Optional[numpy.ndarray] = None, hess: Optional[numpy.ndarray] = None, res: Optional[numpy.ndarray] = None, sres: Optional[numpy.ndarray] = None, n_fval: Optional[int] = None, n_grad: Optional[int] = None, n_hess: Optional[int] = None, n_res: Optional[int] = None, n_sres: Optional[int] = None, x0: Optional[numpy.ndarray] = None, fval0: Optional[float] = None, history: Optional[pypesto.objective.history.History] = None, exitflag: Optional[int] = None, time: Optional[float] = None, message: Optional[str] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

update_to_full(problem: pypesto.problem.Problem)None[source]

Update values to full vectors/matrices.

Parameters

problem – problem which contains info about how to convert to full vectors or matrices

class pypesto.PredictionConditionResult(timepoints: numpy.ndarray, output_ids: Sequence[str], output: Optional[numpy.ndarray] = None, output_sensi: Optional[numpy.ndarray] = None, output_weight: Optional[float] = None, output_sigmay: Optional[numpy.ndarray] = None, x_names: Optional[Sequence[str]] = None)[source]

Bases: object

Light-weight wrapper for the prediction of one simulation condition.

It should provide a common api how amici predictions should look like in pyPESTO.

__init__(timepoints: numpy.ndarray, output_ids: Sequence[str], output: Optional[numpy.ndarray] = None, output_sensi: Optional[numpy.ndarray] = None, output_weight: Optional[float] = None, output_sigmay: Optional[numpy.ndarray] = None, x_names: Optional[Sequence[str]] = None)[source]

Initialize PredictionConditionResult.

Parameters
  • timepoints – Output timepoints for this simulation condition

  • output_ids – IDs of outputs for this simulation condition

  • output – Postprocessed outputs (ndarray)

  • output_sensi – Sensitivities of postprocessed outputs (ndarray)

  • output_weight – LLH of the simulation

  • output_sigmay – Standard deviations of postprocessed observables

  • x_names – IDs of model parameter w.r.t to which sensitivities were computed

class pypesto.PredictionResult(conditions: Sequence[Union[pypesto.result.predict.PredictionConditionResult, Dict]], condition_ids: Optional[Sequence[str]] = None, comment: Optional[str] = None)[source]

Bases: object

Light-weight wrapper around prediction from pyPESTO made by an AMICI model.

Its only purpose is to have fixed format/api, how prediction results should be stored, read, and handled: as predictions are a very flexible format anyway, they should at least have a common definition, which allows to work with them in a reasonable way.

__init__(conditions: Sequence[Union[pypesto.result.predict.PredictionConditionResult, Dict]], condition_ids: Optional[Sequence[str]] = None, comment: Optional[str] = None)[source]

Initialize PredictionResult.

Parameters
  • conditions – A list of PredictionConditionResult objects or dicts

  • condition_ids – IDs or names of the simulation conditions, which belong to this prediction (e.g., PEtab uses tuples of preequilibration condition and simulation conditions)

  • comment – An additional note, which can be attached to this prediction

write_to_csv(output_file: str)[source]

Save predictions to a csv file.

Parameters

output_file – path to file/folder to which results will be written

write_to_h5(output_file: str, base_path: Optional[str] = None)[source]

Save predictions to an h5 file.

It appends to the file if the file already exists.

Parameters
  • output_file – path to file/folder to which results will be written

  • base_path – base path in the h5 file

class pypesto.Problem(objective: pypesto.objective.base.ObjectiveBase, lb: Union[numpy.ndarray, List[float]], ub: Union[numpy.ndarray, List[float]], dim_full: Optional[int] = None, x_fixed_indices: Optional[Union[Iterable[SupportsInt], SupportsInt]] = None, x_fixed_vals: Optional[Union[Iterable[SupportsFloat], SupportsFloat]] = None, x_guesses: Optional[Iterable[float]] = None, x_names: Optional[Iterable[str]] = None, x_scales: Optional[Iterable[str]] = None, x_priors_defs: Optional[pypesto.objective.priors.NegLogPriors] = None, lb_init: Optional[Union[numpy.ndarray, List[float]]] = None, ub_init: Optional[Union[numpy.ndarray, List[float]]] = None, copy_objective: bool = True)[source]

Bases: object

The problem formulation.

A problem specifies the objective function, boundaries and constraints, parameter guesses as well as the parameters which are to be optimized.

Parameters
  • objective – The objective function for minimization. Note that a shallow copy is created.

  • lb – The lower and upper bounds for optimization. For unbounded directions set to +-inf.

  • ub – The lower and upper bounds for optimization. For unbounded directions set to +-inf.

  • lb_init – The lower and upper bounds for initialization, typically for defining search start points. If not set, set to lb, ub.

  • ub_init – The lower and upper bounds for initialization, typically for defining search start points. If not set, set to lb, ub.

  • dim_full – The full dimension of the problem, including fixed parameters.

  • x_fixed_indices – Vector containing the indices (zero-based) of parameter components that are not to be optimized.

  • x_fixed_vals – Vector of the same length as x_fixed_indices, containing the values of the fixed parameters.

  • x_guesses – Guesses for the parameter values, shape (g, dim), where g denotes the number of guesses. These are used as start points in the optimization.

  • x_names – Parameter names that can be optionally used e.g. in visualizations. If objective.get_x_names() is not None, those values are used, else the values specified here are used if not None, otherwise the variable names are set to [‘x0’, … ‘x{dim_full}’]. The list must always be of length dim_full.

  • x_scales – Parameter scales can be optionally given and are used e.g. in visualisation and prior generation. Currently the scales ‘lin’, ‘log`and ‘log10’ are supported.

  • x_priors_defs – Definitions of priors for parameters. Types of priors, and their required and optional parameters, are described in the Prior class.

  • copy_objective – Whethter to generate a deep copy of the objective function before potential modification the problem class performs on it.

Notes

On the fixing of parameter values:

The number of parameters dim_full the objective takes as input must be known, so it must be either lb a vector of that size, or dim_full specified as a parameter.

All vectors are mapped to the reduced space of dimension dim in __init__, regardless of whether they were in dimension dim or dim_full before. If the full representation is needed, the methods get_full_vector() and get_full_matrix() can be used.

__init__(objective: pypesto.objective.base.ObjectiveBase, lb: Union[numpy.ndarray, List[float]], ub: Union[numpy.ndarray, List[float]], dim_full: Optional[int] = None, x_fixed_indices: Optional[Union[Iterable[SupportsInt], SupportsInt]] = None, x_fixed_vals: Optional[Union[Iterable[SupportsFloat], SupportsFloat]] = None, x_guesses: Optional[Iterable[float]] = None, x_names: Optional[Iterable[str]] = None, x_scales: Optional[Iterable[str]] = None, x_priors_defs: Optional[pypesto.objective.priors.NegLogPriors] = None, lb_init: Optional[Union[numpy.ndarray, List[float]]] = None, ub_init: Optional[Union[numpy.ndarray, List[float]]] = None, copy_objective: bool = True)[source]

Initialize self. See help(type(self)) for accurate signature.

property dim

Return dimension only considering non fixed parameters.

fix_parameters(parameter_indices: Union[Iterable[SupportsInt], SupportsInt], parameter_vals: Union[Iterable[SupportsFloat], SupportsFloat])None[source]

Fix specified parameters to specified values.

full_index_to_free_index(full_index: int)[source]

Calculate index in reduced vector from index in full vector.

Parameters

full_index (The index in the full vector.) –

Returns

free_index

Return type

The index in the free vector.

get_full_matrix(x: Optional[numpy.ndarray])Optional[numpy.ndarray][source]

Map matrix from dim to dim_full. Usually used for hessian.

Parameters

x (array_like, shape=(dim, dim)) – The matrix in dimension dim.

get_full_vector(x: Optional[numpy.ndarray], x_fixed_vals: Optional[Iterable[float]] = None)Optional[numpy.ndarray][source]

Map vector from dim to dim_full. Usually used for x, grad.

Parameters
  • x (array_like, shape=(dim,)) – The vector in dimension dim.

  • x_fixed_vals (array_like, ndim=1, optional) – The values to be used for the fixed indices. If None, then nans are inserted. Usually, None will be used for grad and problem.x_fixed_vals for x.

get_reduced_matrix(x_full: Optional[numpy.ndarray])Optional[numpy.ndarray][source]

Map matrix from dim_full to dim, i.e. delete fixed indices.

Parameters

x_full (array_like, ndim=2) – The matrix in dimension dim_full.

get_reduced_vector(x_full: Optional[numpy.ndarray], x_indices: Optional[List[int]] = None)Optional[numpy.ndarray][source]

Keep only those elements, which indices are specified in x_indices.

If x_indices is not provided, delete fixed indices.

Parameters
  • x_full (array_like, ndim=1) – The vector in dimension dim_full.

  • x_indices – indices of x_full that should remain

property lb

Return lower bounds of free parameters.

property lb_init

Return initial lower bounds of free parameters.

normalize()None[source]

Process vectors.

Reduce all vectors to dimension dim and have the objective accept vectors of dimension dim.

print_parameter_summary()None[source]

Print a summary of parameters.

Include what parameters are being optimized and parameter boundaries.

set_x_guesses(x_guesses: Iterable[float])[source]

Set the x_guesses of a problem.

Parameters

x_guesses

property ub

Return upper bounds of free parameters.

property ub_init

Return initial upper bounds of free parameters.

unfix_parameters(parameter_indices: Union[Iterable[SupportsInt], SupportsInt])None[source]

Free specified parameters.

property x_free_indices

Return non fixed parameters.

property x_guesses

Return guesses of the free parameter values.

class pypesto.ProfileResult[source]

Bases: object

Result of the profile() function.

It holds a list of profile lists. Each profile list consists of a list of ProfilerResult objects, one for each parameter.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

append_empty_profile_list()int[source]

Append an empty profile list to the list of profile lists.

Returns

The index of the created profile list.

Return type

index

append_profiler_result(profiler_result: Optional[pypesto.result.profile.ProfilerResult] = None, profile_list: Optional[int] = None)None[source]

Append the profiler result to the profile list.

Parameters
  • profiler_result – The result of one profiler run for a parameter, or None if to be left empty.

  • profile_list – Index specifying the profile list to which we want to append. Defaults to the last list.

get_profiler_result(i_par: int, profile_list: Optional[int] = None)[source]

Get the profiler result at parameter index i_par of profile_list.

Parameters
  • i_par – Integer specifying the profile index.

  • profile_list – Index specifying the profile list. Defaults to the last list.

set_profiler_result(profiler_result: pypesto.result.profile.ProfilerResult, i_par: int, profile_list: Optional[int] = None)None[source]

Write a profiler result to the result object.

Parameters
  • profiler_result – The result of one (local) profiler run.

  • i_par – Integer specifying the parameter index where to put profiler_result.

  • profile_list – Index specifying the profile list. Defaults to the last list.

class pypesto.ProfilerResult(x_path: numpy.ndarray, fval_path: numpy.ndarray, ratio_path: numpy.ndarray, gradnorm_path: numpy.ndarray = nan, exitflag_path: numpy.ndarray = nan, time_path: numpy.ndarray = nan, time_total: float = 0.0, n_fval: int = 0, n_grad: int = 0, n_hess: int = 0, message: Optional[str] = None)[source]

Bases: dict

The result of a profiler run.

The standardized return value from pypesto.profile, which can either be initialized from an OptimizerResult or from an existing ProfilerResult (in order to extend the computation).

Can be used like a dict.

x_path

The path of the best found parameters along the profile (Dimension: n_par x n_profile_points)

fval_path

The function values, fun(x), along the profile.

ratio_path

The ratio of the posterior function along the profile.

gradnorm_path

The gradient norm along the profile.

exitflag_path

The exitflags of the optimizer along the profile.

time_path

The computation time of the optimizer runs along the profile.

time_total

The total computation time for the profile.

n_fval

Number of function evaluations.

n_grad

Number of gradient evaluations.

n_hess

Number of Hessian evaluations.

message

Textual comment on the profile result.

Notes

Any field not supported by the profiler or the profiling optimizer is filled with None. Some fields are filled by pypesto itself.

__init__(x_path: numpy.ndarray, fval_path: numpy.ndarray, ratio_path: numpy.ndarray, gradnorm_path: numpy.ndarray = nan, exitflag_path: numpy.ndarray = nan, time_path: numpy.ndarray = nan, time_total: float = 0.0, n_fval: int = 0, n_grad: int = 0, n_hess: int = 0, message: Optional[str] = None)[source]

Initialize self. See help(type(self)) for accurate signature.

append_profile_point(x: numpy.ndarray, fval: float, ratio: float, gradnorm: float = nan, time: float = nan, exitflag: float = nan, n_fval: int = 0, n_grad: int = 0, n_hess: int = 0)None[source]

Append a new point to the profile path.

Parameters
  • x – The parameter values.

  • fval – The function value at x.

  • ratio – The ratio of the function value at x by the optimal function value.

  • gradnorm – The gradient norm at x.

  • time – The computation time to find x.

  • exitflag – The exitflag of the optimizer (useful if an optimization was performed to find x).

  • n_fval – Number of function evaluations performed to find x.

  • n_grad – Number of gradient evaluations performed to find x.

  • n_hess – Number of Hessian evaluations performed to find x.

flip_profile()None[source]

Flip the profiling direction (left-right).

Profiling direction needs to be changed once (if the profile is new), or twice if we append to an existing profile. All profiling paths are flipped in-place.

class pypesto.Result(problem=None)[source]

Bases: object

Universal result object for pypesto.

The algorithms like optimize, profile, sample fill different parts of it.

problem

The problem underlying the results.

Type

pypesto.Problem

optimize_result

The results of the optimizer runs.

profile_result

The results of the profiler run.

sample_result

The results of the sampler run.

__init__(problem=None)[source]

Initialize self. See help(type(self)) for accurate signature.

class pypesto.SampleResult[source]

Bases: object

Result of the sample() function.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.