Class ReturnData

Inheritance Relationships

Base Type

Class Documentation

class amici::ReturnData : public amici::ModelDimensions

Stores all data to be returned by amici::runAmiciSimulation.

NOTE: multi-dimensional arrays are stored in row-major order (C-style)

Public Functions

ReturnData() = default

Default constructor.

ReturnData(std::vector<realtype> ts, ModelDimensions const &model_dimensions, int nplist, int nmaxevent, int nt, int newton_maxsteps, std::vector<ParameterScaling> pscale, SecondOrderMode o2mode, SensitivityOrder sensi, SensitivityMethod sensi_meth, RDataReporting rdrm, bool quadratic_llh, bool sigma_res, realtype sigma_offset)

Constructor.

Parameters

  • ts: see amici::SimulationParameters::ts

  • model_dimensions: Model dimensions

  • nplist: see amici::ModelDimensions::nplist

  • nmaxevent: see amici::ModelDimensions::nmaxevent

  • nt: see amici::ModelDimensions::nt

  • newton_maxsteps: see amici::Solver::newton_maxsteps

  • pscale: see amici::SimulationParameters::pscale

  • o2mode: see amici::SimulationParameters::o2mode

  • sensi: see amici::Solver::sensi

  • sensi_meth: see amici::Solver::sensi_meth

  • rdrm: see amici::Solver::rdata_reporting

  • quadratic_llh: whether model defines a quadratic nllh and computing res, sres and FIM makes sense

  • sigma_res: indicates whether additional residuals are to be added for each sigma

  • sigma_offset: offset to ensure real-valuedness of sigma residuals

ReturnData(Solver const &solver, const Model &model)

constructor that uses information from model and solver to appropriately initialize fields

Parameters

  • solver: solver instance

  • model: model instance

~ReturnData() = default
void processSimulationObjects(SteadystateProblem const *preeq, ForwardProblem const *fwd, BackwardProblem const *bwd, SteadystateProblem const *posteq, Model &model, Solver const &solver, ExpData const *edata)

constructor that uses information from model and solver to appropriately initialize fields

Parameters

  • preeq: simulated preequilibration problem, pass nullptr to ignore

  • fwd: simulated forward problem, pass nullptr to ignore

  • bwd: simulated backward problem, pass nullptr to ignore

  • posteq: simulated postequilibration problem, pass nullptr to ignore

  • model: matching model instance

  • solver: matching solver instance

  • edata: matching experimental data

Public Members

std::vector<realtype> ts

timepoints (shape nt)

std::vector<realtype> xdot

time derivative (shape nx)

std::vector<realtype> J

Jacobian of differential equation right hand side (shape nx x nx, row-major)

std::vector<realtype> w

w data from the model (recurring terms in xdot, for imported SBML models from python, this contains the flux vector) (shape nt x nw, row major)

std::vector<realtype> z

event output (shape nmaxevent x nz, row-major)

std::vector<realtype> sigmaz

event output sigma standard deviation (shape nmaxevent x nz, row-major)

std::vector<realtype> sz

parameter derivative of event output (shape nmaxevent x nz, row-major)

std::vector<realtype> ssigmaz

parameter derivative of event output standard deviation (shape nmaxevent x nz, row-major)

std::vector<realtype> rz

event trigger output (shape nmaxevent x nz, row-major)

std::vector<realtype> srz

parameter derivative of event trigger output (shape nmaxevent x nz x nplist, row-major)

std::vector<realtype> s2rz

second-order parameter derivative of event trigger output (shape nmaxevent x nztrue x nplist x nplist, row-major)

std::vector<realtype> x

state (shape nt x nx, row-major)

std::vector<realtype> sx

parameter derivative of state (shape nt x nplist x nx, row-major)

std::vector<realtype> y

observable (shape nt x ny, row-major)

std::vector<realtype> sigmay

observable standard deviation (shape nt x ny, row-major)

std::vector<realtype> sy

parameter derivative of observable (shape nt x nplist x ny, row-major)

std::vector<realtype> ssigmay

parameter derivative of observable standard deviation (shape nt x nplist x ny, row-major)

std::vector<realtype> res

observable (shape nt*ny, row-major)

std::vector<realtype> sres

parameter derivative of residual (shape nt*ny x nplist, row-major)

std::vector<realtype> FIM

fisher information matrix (shape nplist x nplist, row-major)

std::vector<int> numsteps

number of integration steps forward problem (shape nt)

std::vector<int> numstepsB

number of integration steps backward problem (shape nt)

std::vector<int> numrhsevals

number of right hand side evaluations forward problem (shape nt)

std::vector<int> numrhsevalsB

number of right hand side evaluations backward problem (shape nt)

std::vector<int> numerrtestfails

number of error test failures forward problem (shape nt)

std::vector<int> numerrtestfailsB

number of error test failures backward problem (shape nt)

std::vector<int> numnonlinsolvconvfails

number of linear solver convergence failures forward problem (shape nt)

std::vector<int> numnonlinsolvconvfailsB

number of linear solver convergence failures backward problem (shape nt)

std::vector<int> order

employed order forward problem (shape nt)

double cpu_time = 0.0

computation time of forward solve [ms]

double cpu_timeB = 0.0

computation time of backward solve [ms]

std::vector<SteadyStateStatus> preeq_status

flags indicating success of steady state solver (preequilibration)

double preeq_cpu_time = 0.0

computation time of the steady state solver [ms] (preequilibration)

double preeq_cpu_timeB = 0.0

computation time of the steady state solver of the backward problem [ms] (preequilibration)

std::vector<SteadyStateStatus> posteq_status

flags indicating success of steady state solver (postequilibration)

double posteq_cpu_time = 0.0

computation time of the steady state solver [ms] (postequilibration)

double posteq_cpu_timeB = 0.0

computation time of the steady state solver of the backward problem [ms] (postequilibration)

std::vector<int> preeq_numsteps

number of Newton steps for steady state problem (preequilibration) [newton, simulation, newton] (length = 3)

std::vector<int> preeq_numlinsteps

number of linear steps by Newton step for steady state problem. this will only be filled for iterative solvers (preequilibration) (shape newton_maxsteps * 2)

int preeq_numstepsB = 0

number of simulation steps for adjoint steady state problem (preequilibration) [== 0 if analytical solution worked, > 0 otherwise]

std::vector<int> posteq_numsteps

number of Newton steps for steady state problem (preequilibration) [newton, simulation, newton] (shape 3) (postequilibration)

std::vector<int> posteq_numlinsteps

number of linear steps by Newton step for steady state problem. this will only be filled for iterative solvers (postequilibration) (shape newton_maxsteps * 2)

int posteq_numstepsB = 0

number of simulation steps for adjoint steady state problem (postequilibration) [== 0 if analytical solution worked, > 0 otherwise]

realtype preeq_t = NAN

time when steadystate was reached via simulation (preequilibration)

realtype preeq_wrms = NAN

weighted root-mean-square of the rhs when steadystate was reached (preequilibration)

realtype posteq_t = NAN

time when steadystate was reached via simulation (postequilibration)

realtype posteq_wrms = NAN

weighted root-mean-square of the rhs when steadystate was reached (postequilibration)

std::vector<realtype> x0

initial state (shape nx)

std::vector<realtype> x_ss

preequilibration steady state found by Newton solver (shape nx)

std::vector<realtype> sx0

initial sensitivities (shape nplist x nx, row-major)

std::vector<realtype> sx_ss

preequilibration sensitivities found by Newton solver (shape nplist x nx, row-major)

realtype llh = 0.0

log-likelihood value

realtype chi2 = 0.0

\(\chi^2\) value

std::vector<realtype> sllh

parameter derivative of log-likelihood (shape nplist)

std::vector<realtype> s2llh

second-order parameter derivative of log-likelihood (shape nJ-1 x nplist, row-major)

int status = 0

status code

int nx = {0}

number of states (alias nx_rdata, kept for backward compatibility)

int nxtrue = {0}

number of states in the unaugmented system (alias nxtrue_rdata, kept for backward compatibility)

int nplist = {0}

number of parameter for which sensitivities were requested

int nmaxevent = {0}

maximal number of occurring events (for every event type)

int nt = {0}

number of considered timepoints

int newton_maxsteps = {0}

maximal number of newton iterations for steady state calculation

std::vector<ParameterScaling> pscale

scaling of parameterization

SecondOrderMode o2mode = {SecondOrderMode::none}

flag indicating whether second-order sensitivities were requested

SensitivityOrder sensi = {SensitivityOrder::none}

sensitivity order

SensitivityMethod sensi_meth = {SensitivityMethod::none}

sensitivity method

RDataReporting rdata_reporting = {RDataReporting::full}

reporting mode

bool sigma_res

boolean indicating whether residuals for standard deviations have been added

Protected Functions

void initializeLikelihoodReporting(bool quadratic_llh)

initializes storage for likelihood reporting mode

Parameters

  • quadratic_llh: whether model defines a quadratic nllh and computing res, sres and FIM makes sense.

void initializeResidualReporting(bool enable_res)

initializes storage for residual reporting mode

Parameters

  • enable_res: whether residuals are to be computed

void initializeFullReporting(bool enable_fim)

initializes storage for full reporting mode

Parameters

  • enable_fim: whether FIM Hessian approximation is to be computed

void initializeObjectiveFunction(bool enable_chi2)

initialize values for chi2 and llh and derivatives

Parameters

  • enable_chi2: whether chi2 values are to be computed

void processPreEquilibration(SteadystateProblem const &preeq, Model &model)

extracts data from a preequilibration SteadystateProblem

Parameters

void processPostEquilibration(SteadystateProblem const &posteq, Model &model, ExpData const *edata)

extracts data from a preequilibration SteadystateProblem

Parameters

void processForwardProblem(ForwardProblem const &fwd, Model &model, ExpData const *edata)

extracts results from forward problem

Parameters

  • fwd: forward problem

  • model: model that was used for forward simulation

  • edata: ExpData instance containing observable data

void processBackwardProblem(ForwardProblem const &fwd, BackwardProblem const &bwd, SteadystateProblem const *preeq, Model &model)

extracts results from backward problem

Parameters

  • fwd: forward problem

  • bwd: backward problem

  • preeq: SteadystateProblem for preequilibration

  • model: model that was used for forward/backward simulation

void processSolver(Solver const &solver)

extracts results from solver

Parameters

  • solver: solver that was used for forward/backward simulation

template<class T>
void storeJacobianAndDerivativeInReturnData(T const &problem, Model &model)

Evaluates and stores the Jacobian and right hand side at final timepoint.

Parameters

  • problem: forward problem or steadystate problem

  • model: model that was used for forward/backward simulation

void readSimulationState(SimulationState const &state, Model &model)

sets member variables and model state according to provided simulation state

Parameters

  • state: simulation state provided by Problem

  • model: model that was used for forward/backward simulation

void fres(int it, Model &model, const ExpData &edata)

Residual function.

Parameters

  • it: time index

  • model: model that was used for forward/backward simulation

  • edata: ExpData instance containing observable data

void fchi2(int it, const ExpData &edata)

Chi-squared function.

Parameters

  • it: time index

  • edata: ExpData instance containing observable data

void fsres(int it, Model &model, const ExpData &edata)

Residual sensitivity function.

Parameters

  • it: time index

  • model: model that was used for forward/backward simulation

  • edata: ExpData instance containing observable data

void fFIM(int it, Model &model, const ExpData &edata)

Fisher information matrix function.

Parameters

  • it: time index

  • model: model that was used for forward/backward simulation

  • edata: ExpData instance containing observable data

void invalidate(int it_start)

Set likelihood, state variables, outputs and respective sensitivities to NaN (typically after integration failure)

Parameters

  • it_start: time index at which to start invalidating

void invalidateLLH()

Set likelihood and chi2 to NaN (typically after integration failure)

void invalidateSLLH()

Set likelihood sensitivities to NaN (typically after integration failure)

void applyChainRuleFactorToSimulationResults(const Model &model)

applies the chain rule to account for parameter transformation in the sensitivities of simulation results

Parameters

bool computingFSA() const

Checks whether forward sensitivity analysis is performed.

Return

boolean indicator

void getDataOutput(int it, Model &model, ExpData const *edata)

Extracts output information for data-points, expects that x_solver_ and sx_solver_ were set appropriately.

Parameters

  • it: timepoint index

  • model: model that was used in forward solve

  • edata: ExpData instance carrying experimental data

void getDataSensisFSA(int it, Model &model, ExpData const *edata)

Extracts data information for forward sensitivity analysis, expects that x_solver_ and sx_solver_ were set appropriately.

Parameters

  • it: index of current timepoint

  • model: model that was used in forward solve

  • edata: ExpData instance carrying experimental data

void getEventOutput(realtype t, const std::vector<int> rootidx, Model &model, ExpData const *edata)

Extracts output information for events, expects that x_solver_ and sx_solver_ were set appropriately.

Parameters

  • t: event timepoint

  • rootidx: information about which roots fired (1 indicating fired, 0/-1 for not)

  • model: model that was used in forward solve

  • edata: ExpData instance carrying experimental data

void getEventSensisFSA(int ie, realtype t, Model &model, ExpData const *edata)

Extracts event information for forward sensitivity analysis, expects that x_solver_ and sx_solver_ were set appropriately.

Parameters

  • ie: index of event type

  • t: event timepoint

  • model: model that was used in forward solve

  • edata: ExpData instance carrying experimental data

void handleSx0Backward(const Model &model, SteadystateProblem const &preeq, std::vector<realtype> &llhS0, AmiVector &xQB) const

Updates contribution to likelihood from quadratures (xQB), if preequilibration was run in adjoint mode.

Parameters

  • model: model that was used for forward/backward simulation

  • preeq: SteadystateProblem for preequilibration

  • llhS0: contribution to likelihood for initial state sensitivities of preequilibration

  • xQB: vector with quadratures from adjoint computation

void handleSx0Forward(const Model &model, std::vector<realtype> &llhS0, AmiVector &xB) const

Updates contribution to likelihood for initial state sensitivities (llhS0), if no preequilibration was run or if forward sensitivities were used.

Parameters

  • model: model that was used for forward/backward simulation

  • llhS0: contribution to likelihood for initial state sensitivities

  • xB: vector with final adjoint state (excluding conservation laws)

Protected Attributes

realtype sigma_offset

offset for sigma_residuals

realtype t_

timepoint for model evaluation

AmiVector x_solver_

partial state vector, excluding states eliminated from conservation laws

AmiVector dx_solver_

partial time derivative of state vector, excluding states eliminated from conservation laws

AmiVectorArray sx_solver_

partial sensitivity state vector array, excluding states eliminated from conservation laws

AmiVector x_rdata_

full state vector, including states eliminated from conservation laws

AmiVectorArray sx_rdata_

full sensitivity state vector array, including states eliminated from conservation laws

std::vector<int> nroots_

array of number of found roots for a certain event type (shape ne)

Friends

template<class Archive>
friend void serialize(Archive &ar, ReturnData &r, unsigned int version)

Serialize ReturnData (see boost::serialization::serialize)

Parameters

  • ar: Archive to serialize to

  • r: Data to serialize

  • version: Version number