Objective¶
-
class
pypesto.objective.
AggregatedObjective
(objectives: Sequence[pypesto.objective.base.ObjectiveBase], x_names: Optional[Sequence[str]] = None)[source]¶ Bases:
pypesto.objective.base.ObjectiveBase
Aggregates multiple objectives into one objective.
-
__init__
(objectives: Sequence[pypesto.objective.base.ObjectiveBase], x_names: Optional[Sequence[str]] = None)[source]¶ Initialize objective.
- Parameters
objectives – Sequence of pypesto.ObjectiveBase instances
x_names – Sequence of names of the (optimized) parameters. (Details see documentation of x_names in
pypesto.ObjectiveBase
)
-
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.
-
-
class
pypesto.objective.
AmiciCalculator
[source]¶ Bases:
object
Class to perform the AMICI call and obtain objective function values.
-
__call__
(x_dct: Dict, sensi_orders: Tuple[int], mode: str, amici_model: Union[amici.Model, amici.ModelPtr], amici_solver: Union[amici.Solver, amici.SolverPtr], edatas: List[amici.ExpData], n_threads: int, x_ids: Sequence[str], parameter_mapping: ParameterMapping, fim_for_hess: bool)[source]¶ Perform the actual AMICI call.
Called within the
AmiciObjective.__call__()
method.- Parameters
x_dct – Parameters for which to compute function value and derivatives.
sensi_orders – Tuple of requested sensitivity orders.
mode – Call mode (function value or residual based).
amici_model – The AMICI model.
amici_solver – The AMICI solver.
edatas – The experimental data.
n_threads – Number of threads for AMICI call.
x_ids – Ids of optimization parameters.
parameter_mapping – Mapping of optimization to simulation parameters.
fim_for_hess – Whether to use the FIM (if available) instead of the Hessian (if requested).
-
-
class
pypesto.objective.
AmiciObjectBuilder
[source]¶ Bases:
abc.ABC
Allows to build AMICI model, solver, and edatas.
This class is useful for pickling an
pypesto.AmiciObjective
, which is required in some parallelization schemes. Therefore, this class itself must be picklable.
-
class
pypesto.objective.
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
-
check_sensi_orders
(sensi_orders: Tuple[int, …], mode: str) → bool[source]¶ See ObjectiveBase documentation.
-
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.
-
-
class
pypesto.objective.
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.
-
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.objective.
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 (Optional[bool]) – Derivative method for the gradient (see above).
hess (Optional[bool]) – Derivative method for the Hessian (see above).
sres (Optional[bool]) – Derivative method for the residual sensitivities (see above).
hess_via_fval (bool) – 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 (pypesto.objective.finite_difference.FDDelta) – 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 (pypesto.objective.finite_difference.FDDelta) – FD step sizes for gradients, if the Hessian is calculated via 1st order sensitivities from the gradients. Similar to delta_fun.
delta_res (pypesto.objective.finite_difference.FDDelta) – FD step sizes for residuals. Similar to delta_fun.
method (str) – 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.
-
delta_fun
: pypesto.objective.finite_difference.FDDelta¶
-
delta_grad
: pypesto.objective.finite_difference.FDDelta¶
-
delta_res
: pypesto.objective.finite_difference.FDDelta¶
-
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.
-
obj
: pypesto.objective.base.ObjectiveBase¶
-
class
pypesto.objective.
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 (Optional[Union[numpy.ndarray, float]]) – (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 (numpy.ndarray) – Step sizes to try out in step size selection. If None, a range [1e-1, 1e-2, …, 1e-8] is considered.
update_condition (str) – 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 (float) – Coefficient on the distance between current and reference point beyond which to update, in the FDDelta.DISTANCE update condition.
max_steps (int) – 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.
-
delta
: Optional[Union[numpy.ndarray, float]]¶
-
get
() → numpy.ndarray[source]¶ Get delta vector.
-
test_deltas
: numpy.ndarray¶
-
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.
-
x0
: Optional[numpy.ndarray]¶
-
class
pypesto.objective.
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.
-
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.
-
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.objective.
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.
-
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.objective.
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.
-
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_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.objective.
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) –
-
class
pypesto.objective.
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.objective.
NegLogParameterPriors
(prior_list: List[Dict], x_names: Optional[Sequence[str]] = None)[source]¶ Bases:
pypesto.objective.base.ObjectiveBase
Implements Negative Log Priors on Parameters.
Contains a list of prior dictionaries for the individual parameters of the format
- {‘index’: [int],
‘density_fun’: [Callable], ‘density_dx’: [Callable], ‘density_ddx’: [Callable]}
A prior instance can be added to e.g. an objective, that gives the likelihood, by an AggregatedObjective.
Notes
All callables should correspond to log-densities. That is, they return log-densities and their corresponding derivatives. Internally, values are multiplied by -1, since pyPESTO expects the Objective function to be of a negative log-density type.
-
__init__
(prior_list: List[Dict], x_names: Optional[Sequence[str]] = None)[source]¶ Initialize.
- Parameters
prior_list – List of dicts containing the individual parameter priors. Format see above.
x_names – Sequence of parameter names (optional).
-
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
-
check_sensi_orders
(sensi_orders: Tuple[int, …], mode: str) → bool[source]¶ See ObjectiveBase documentation.
-
class
pypesto.objective.
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.
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
-
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.objective.
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
-
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.objective.
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
-
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.
-
-
pypesto.objective.
get_parameter_prior_dict
(index: int, prior_type: str, prior_parameters: list, parameter_scale: str = 'lin')[source]¶ Return the prior dict used to define priors for some default priors.
- index:
index of the parameter in x_full
- prior_type:
Prior is defined in LINEAR=untransformed parameter space, unless it starts with “parameterScale”. prior_type can be any of {“uniform”, “normal”, “laplace”, “logNormal”, “parameterScaleUniform”, “parameterScaleNormal”, “parameterScaleLaplace”}
- prior_parameters:
Parameters of the priors. Parameters are defined in linear scale.
- parameter_scale:
scale in which the parameter is defined (since a parameter can be log-transformed, while the prior is always defined in the linear space, unless it starts with “parameterScale”)