Objective

class pypesto.objective.Objective(fun=None, grad=None, hess=None, hessp=None, res=None, sres=None, fun_accept_sensi_orders=False, res_accept_sensi_orders=False, x_names=None, options=None)

Bases: object

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.

Parameters:
  • fun (callable, optional) –

    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 (callable, bool, optional) –

    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 (callable, optional) –

    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 (callable, optional) –
    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 ({callable, bool}, optional) –
    Method for computing residuals, i.e.
    res(x) -> array_like, shape(m,).
  • sres (callable, optional) –

    Method for computing residual sensitivities. If its 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.

  • fun_accept_sensi_orders (bool, optional) – Flag indicating whether fun takes sensi_orders as an argument. Default: False.
  • res_accept_sensi_orders (bool, optional) – Flag indicating whether res takes sensi_orders as an argument. Default: False
  • x_names (list of str) – 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.
  • options (pypesto.ObjectiveOptions, optional) – Options as specified in pypesto.ObjectiveOptions.
history

For storing the call history. Initialized by the optimizer in reset_history().

Type:pypesto.ObjectiveHistory
preprocess

Preprocess input values to __call__.

Type:callable
postprocess

Postprocess output values from __call__.

Type:callable
sensitivity_orders

Temporary variable to store requested sensitivity orders

Type:tuple

Notes

preprocess, postprocess are configured in update_from_problem() and can be reset using the reset() method.

If fun_accept_sensi_orders resp. res_accept_sensi_orders is True, fun resp. res can also return dictionaries instead of tuples. In that case, they are expected to follow the naming conventions in constants.py. This is of interest, because when __call__ is called with return_dict = True, the full dictionary is returned, which can contain e.g. also simulation data or debugging information.

__call__(x, sensi_orders: tuple = (0, ), mode='mode_fun', return_dict=False)

Method to 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 (array_like) – The parameters for which to evaluate the objective function.
  • sensi_orders (tuple) – Specifies which sensitivities to compute, e.g. (0,1) -> fval, grad.
  • mode (str) – Whether to compute function values or residuals.
__init__(fun=None, grad=None, hess=None, hessp=None, res=None, sres=None, fun_accept_sensi_orders=False, res_accept_sensi_orders=False, x_names=None, options=None)

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

check_grad(x, x_indices=None, eps=1e-05, verbosity=1, mode='mode_fun') → pandas.core.frame.DataFrame

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

Parameters:
  • x (array_like) – The parameters for which to evaluate the gradient.
  • x_indices (array_like, optional) – List of index values for which to compute gradients. Default: all.
  • eps (float, optional) – Finite differences step size. Default: 1e-5.
  • verbosity (int) –
    Level of verbosity for function output
    0: no output 1: summary for all parameters 2: summary for individual parameters

    Default: 1.

  • mode (str) – Residual (MODE_RES) or objective function value (MODE_FUN, default) computation mode.
Returns:

result – gradient, finite difference approximations and error estimates.
Return type:

pd.DataFrame
check_sensi_orders(sensi_orders, mode)

Check if the objective is able to compute the requested sensitivities. If not, throw an exception.

finalize_history()

Finalize the history object.

get_fval(x)

Get the function value at x.

get_grad(x)

Get the gradient at x.

get_hess(x)

Get the Hessian at x.

get_res(x)

Get the residuals at x.

get_sres(x)

Get the residual sensitivities at x.

has_fun
has_grad
has_hess
has_hessp
has_res
has_sres
static output_to_dict(sensi_orders, mode, output_tuple)

Convert output tuple to dict.

static output_to_tuple(sensi_orders, mode, **kwargs)

Return values as requested by the caller, since usually only a subset is demanded. One output is returned as-is, more than one output are returned as a tuple in order (fval, grad, hess).

reset()

Completely reset the objective, i.e. undo the modifications in update_from_problem().

reset_history(index=None)

Reset the objective history and specify temporary saving options.

Parameters:index (As in ObjectiveHistory.index.) –
update_from_problem(dim_full, x_free_indices, x_fixed_indices, x_fixed_vals)

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 derivaties. 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 (int) – Dimension of the full vector including fixed parameters.
  • x_free_indices (array_like of int) – Vector containing the indices (zero-based) of free parameters (complimentary to x_fixed_indices).
  • x_fixed_indices (array_like of int, optional) – Vector containing the indices (zero-based) of parameter components that are not to be optimized.
  • x_fixed_vals (array_like, optional) – Vector of the same length as x_fixed_indices, containing the values of the fixed parameters.
class pypesto.objective.ObjectiveOptions(trace_record=False, trace_record_grad=True, trace_record_hess=False, trace_record_res=False, trace_record_sres=False, trace_record_chi2=True, trace_record_schi2=True, trace_all=True, trace_file=None, trace_save_iter=10)

Bases: dict

Options for the objective that are used in optimization, profiles and sampling.

Parameters:
  • trace_record (bool, optional) – Flag indicating whether to record the trace of function calls. The trace_record_* flags only become effective if trace_record is True. Default: False.
  • trace_record_grad (bool, optional) – Flag indicating whether to record the gradient in the trace. Default: True.
  • trace_record_hess (bool, optional) – Flag indicating whether to record the Hessian in the trace. Default: False.
  • trace_record_res (bool, optional) – Flag indicating whether to record the residual in the trace. Default: False.
  • trace_record_sres (bool, optional.) – Flag indicating whether to record the residual sensitivities in the trace. Default: False.
  • trace_record_chi2 (bool, optional) – Flag indicating whether to record the chi2 in the trace. Default: True.
  • trace_record_schi2 (bool, optional) – Flag indicating whether to record the chi2 sensitivities in the trace. Default: True.
  • trace_all (bool, optional) – Flag indicating whether to record all (True, default) or only better (False) values.
  • trace_file (str or True, optional) – Either pass a string here denoting the file name for storing the trace, or True, in which case the default file name “tmp_trace_{index}.dat” is used. A contained substring {index} is converted to the multistart index. Default: None, i.e. no file is created.
  • index, optional (trace_save_iter.) – Trace is saved every tr_save_iter iterations. Default: 10.
__init__(trace_record=False, trace_record_grad=True, trace_record_hess=False, trace_record_res=False, trace_record_sres=False, trace_record_chi2=True, trace_record_schi2=True, trace_all=True, trace_file=None, trace_save_iter=10)

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

static assert_instance(maybe_options)

Returns a valid options object.

Parameters:maybe_options (ObjectiveOptions or dict) –
pypesto.objective.res_to_chi2(res)

We assume that the residuals res are related to an objective function value fval = chi2 via:

fval = 0.5 * sum(res**2)

which is the ‘Linear’ formulation in scipy.

pypesto.objective.sres_to_schi2(res, sres)

In line with the assumptions in res_to_chi2.

class pypesto.objective.AmiciObjective(amici_model, amici_solver, edatas, max_sensi_order=None, x_ids=None, x_names=None, mapping_par_opt_to_par_sim=None, mapping_scale_opt_to_scale_sim=None, guess_steadystate=True, n_threads=1, options=None)

Bases: pypesto.objective.objective.Objective

This class allows to create an objective directly from an amici model.

__init__(amici_model, amici_solver, edatas, max_sensi_order=None, x_ids=None, x_names=None, mapping_par_opt_to_par_sim=None, mapping_scale_opt_to_scale_sim=None, guess_steadystate=True, n_threads=1, options=None)

Constructor.

Parameters:
  • amici_model (amici.Model) – The amici model.
  • amici_solver (amici.Solver) – The solver to use for the numeric integration of the model.
  • edatas (amici.ExpData or list of amici.ExpData) – The experimental data. If a list is passed, its entries correspond to multiple experimental conditions.
  • max_sensi_order (int, optional) – Maximum sensitivity order supported by the model. Defaults to 2 if the model was compiled with o2mode, otherwise 1.
  • x_ids (list of str, optional) – Ids of optimization parameters. In the simplest case, this will be the AMICI model parameters (default).
  • x_names (list of str, optional) – See Objective.x_names.
  • mapping_par_opt_to_par_sim (optional) – Mapping of optimization parameters to model parameters. List array of size n_simulation_parameters * n_conditions. The default is just to assume that optimization and simulation parameters coincide. The default is to assume equality of both.
  • mapping_scale_opt_to_scale_sim (optional) – Mapping of optimization parameter scales to simulation parameter scales. The default is to just use the scales specified in the amici_model already.
  • guess_steadystate (bool, optional (default = True)) – 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 (int, optional (default = 1)) – 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.
  • options (pypesto.ObjectiveOptions, optional) – Further options.
apply_steadystate_guess(condition_ix, x)

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)]

get_bound_fun()

Generate a fun function that calls _call_amici with MODE_FUN. Defining a non-class function that references self as a local variable will bind the function to a copy of the current self object and will accordingly not take future changes to self into account.

get_bound_res()

Generate a res function that calls _call_amici with MODE_RES. Defining a non-class function that references self as a local variable will bind the function to a copy of the current self object and will accordingly not take future changes to self into account.

get_error_output(rdatas)
rebind_fun()

Replace the current fun function with one that is bound to the current instance

rebind_res()

Replace the current res function with one that is bound to the current instance

reset()

Resets the objective, including steadystate guesses

reset_steadystate_guesses()

Resets all steadystate guess data

set_par_sim_for_condition(condition_ix, x)

Set the simulation parameters from the optimization parameters for the given condition.

Parameters:
  • condition_ix (int) – Index of the current experimental condition.
  • x (array_like) – Optimization parameters.
set_parameter_scale(condition_ix)
set_plist_for_condition(condition_ix)

Set the plist according to the optimization parameters for the given condition.

Parameters:
  • condition_ix (int) – Index of the current experimental condition.
  • x (array_like) – Optimization parameters.
store_steadystate_guess(condition_ix, x, rdata)

Store condition parameter, steadystate and steadystate sensitivity in steadystate_guesses if steadystate guesses are enabled for this condition

class pypesto.objective.AggregatedObjective(objectives, x_names=None, options=None)

Bases: pypesto.objective.objective.Objective

This class allows to create an aggregateObjective from a list of Objective instances.

__init__(objectives, x_names=None, options=None)

Constructor.

Parameters:objectives (list) – List of pypesto.objetive instances
aggregate_fun(x)
aggregate_fun_sensi_orders(x, sensi_orders)
aggregate_grad(x)
aggregate_hess(x)
aggregate_hessp(x)
aggregate_res(x)
aggregate_res_sensi_orders(x, sensi_orders)
aggregate_sres(x)
reset_steadystate_guesses()

Propagates reset_steadystate_guesses() to child objectives if available (currently only applies for amici_objective)

class pypesto.objective.PetabImporter(petab_problem: petab.core.Problem, output_folder: str = None, model_name: str = None)

Bases: object

MODEL_BASE_DIR = 'amici_models'
__init__(petab_problem: petab.core.Problem, output_folder: str = None, model_name: str = None)
petab_problem: petab.Problem
Managing access to the model and data.
output_folder: str, optional
Folder to contain the amici model. Defaults to ‘./amici_models/model_name’.
model_name: str, optional
Name of the model, which will in particular be the name of the compiled model python module.
compile_model()

Compile the model. If the output folder exists already, it is first deleted.

create_edatas(model=None, simulation_conditions=None)

Create list of amici.ExpData objects.

create_model(force_compile=False)

Import amici model. If necessary or force_compile is True, compile first.

Parameters:force_compile (str, optional) – If False, the model is compiled only if the output folder does not exist yet. If True, the output folder is deleted and the model (re-)compiled in either case.

Warning

If force_compile, then an existing folder of that name will be deleted.

create_objective(model=None, solver=None, edatas=None, force_compile: bool = False)

Create a pypesto.PetabAmiciObjective.

create_problem(objective)
create_solver(model=None)

Return model solver.

static from_folder(folder, output_folder: str = None, model_name: str = None)

Simplified constructor exploiting the standardized petab folder structure.

Parameters:
  • folder (str) – Path to the base folder of the model, as in petab.Problem.from_folder.
  • output_folder (See __init__.) –
  • model_name (See __init__.) –
rdatas_to_measurement_df(rdatas, model=None)

Create a measurement dataframe in the petab format from the passed rdatas and own information.

Parameters:rdatas (list of amici.RData) – A list of rdatas as produced by pypesto.AmiciObjective.__call__(x, return_dict=True)[‘rdatas’].
Returns:df – A dataframe built from the rdatas in the format as in self.petab_problem.measurement_df.
Return type:pandas.DataFrame