From 83ed682b907a31b2ed4dc11927490f3ba7a54208 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Thu, 4 Dec 2025 12:55:06 +0100 Subject: [PATCH] doc: fix formatting Add newline after `@brief` block. Fixes a number of sphinx/breathe issues and improves readability. --- include/amici/abstract_model.h | 76 +++++++++++ include/amici/amici.h | 1 + include/amici/cblas.h | 1 + include/amici/edata.h | 2 + include/amici/event.h | 9 +- include/amici/exception.h | 7 +- include/amici/forwardproblem.h | 48 ++++++- include/amici/hdf5.h | 28 ++++ include/amici/logging.h | 3 + include/amici/misc.h | 18 +++ include/amici/model.h | 168 +++++++++++++++++++++++- include/amici/model_dae.h | 29 +++- include/amici/model_ode.h | 81 +++++++++--- include/amici/model_state.h | 2 + include/amici/newton_solver.h | 5 +- include/amici/rdata.h | 28 ++++ include/amici/serialization.h | 8 ++ include/amici/simulation_parameters.h | 4 + include/amici/solver.h | 137 ++++++++++++++++++- include/amici/solver_cvodes.h | 5 + include/amici/solver_idas.h | 3 + include/amici/splinefunctions.h | 22 ++++ include/amici/steadystateproblem.h | 8 ++ include/amici/sundials_linsol_wrapper.h | 79 +++++++++++ include/amici/sundials_matrix_wrapper.h | 48 ++++++- include/amici/symbolic_functions.h | 2 +- include/amici/vector.h | 54 +++++++- 27 files changed, 827 insertions(+), 49 deletions(-) diff --git a/include/amici/abstract_model.h b/include/amici/abstract_model.h index ea105a29ac..43609c1936 100644 --- a/include/amici/abstract_model.h +++ b/include/amici/abstract_model.h @@ -34,6 +34,7 @@ class AbstractModel { /** * @brief Root function + * * @param t time * @param x state * @param dx time derivative of state (DAE only) @@ -46,6 +47,7 @@ class AbstractModel { /** * @brief Residual function + * * @param t time * @param x state * @param dx time derivative of state (DAE only) @@ -58,6 +60,7 @@ class AbstractModel { /** * @brief Sensitivity Residual function + * * @param t time * @param x state * @param dx time derivative of state (DAE only) @@ -93,6 +96,7 @@ class AbstractModel { /** * @brief Computes the sparse backward Jacobian for steadystate integration * and writes it to the model member + * * @param t timepoint * @param cj scalar in Jacobian * @param x Vector with the states @@ -108,6 +112,7 @@ class AbstractModel { /** * @brief Dense Jacobian function + * * @param t time * @param cj scaling factor (inverse of timestep, DAE only) * @param x state @@ -122,6 +127,7 @@ class AbstractModel { /** * @brief Dense Jacobian function + * * @param t time * @param cj scaling factor (inverse of timestep, DAE only) * @param x state @@ -139,6 +145,7 @@ class AbstractModel { /** * @brief Sparse Jacobian function + * * @param t time * @param cj scaling factor (inverse of timestep, DAE only) * @param x state @@ -153,6 +160,7 @@ class AbstractModel { /** * @brief Sparse Jacobian function + * * @param t time * @param cj scaling factor (inverse of timestep, DAE only) * @param x state @@ -170,6 +178,7 @@ class AbstractModel { /** * @brief Diagonal Jacobian function + * * @param t time * @param Jdiag array to which the diagonal of the Jacobian will be written * @param cj scaling factor (inverse of timestep, DAE only) @@ -184,6 +193,7 @@ class AbstractModel { /** * @brief Model-specific sparse implementation of explicit parameter * derivative of right hand side + * * @param t time * @param x state * @param dx time derivative of state (DAE only) @@ -193,6 +203,7 @@ class AbstractModel { /** * @brief Jacobian multiply function + * * @param t time * @param x state * @param dx time derivative of state (DAE only) @@ -208,18 +219,21 @@ class AbstractModel { /** * @brief Returns the AMICI version that was used to generate the model + * * @return AMICI version string */ [[nodiscard]] virtual std::string get_amici_version() const; /** * @brief Returns the AMICI commit that was used to generate the model + * * @return AMICI commit string */ [[nodiscard]] virtual std::string get_amici_commit() const; /** * @brief Model-specific implementation of fx0 + * * @param x0 initial state * @param t initial time * @param p parameter vector @@ -231,6 +245,7 @@ class AbstractModel { /** * @brief Function indicating whether reinitialization of states depending * on fixed parameters is permissible + * * @return flag indicating whether reinitialization of states depending on * fixed parameters is permissible */ @@ -239,6 +254,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fx0_fixedParameters + * * @param x0 initial state * @param t initial time * @param p parameter vector @@ -253,6 +269,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsx0_fixedParameters + * * @param sx0 initial state sensitivities * @param t initial time * @param x0 initial state @@ -270,6 +287,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsx0 + * * @param sx0 initial state sensitivities * @param t initial time * @param x0 initial state @@ -285,6 +303,7 @@ class AbstractModel { /** * @brief Initial value for time derivative of states (only necessary for * DAEs) + * * @param x0 Vector with the initial states * @param dx0 Vector to which the initial derivative states will be written * (only DAE) @@ -293,6 +312,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fstau + * * @param stau total derivative of event timepoint * @param t current time * @param x current state @@ -315,6 +335,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fy + * * @param y model output at current timepoint * @param t current time * @param x current state @@ -329,6 +350,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdydp + * * @param dydp partial derivative of observables y w.r.t. model parameters p * @param t current time * @param x current state @@ -352,6 +374,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdydx + * * @param dydx partial derivative of observables y w.r.t. model states x * @param t current time * @param x current state @@ -367,6 +390,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fz + * * @param z value of event output * @param ie event index * @param t current time @@ -381,6 +405,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsz + * * @param sz Sensitivity of rz, total derivative * @param ie event index * @param t current time @@ -397,6 +422,7 @@ class AbstractModel { /** * @brief Model-specific implementation of frz + * * @param rz value of root function at current timepoint (non-output events * not included) * @param ie event index @@ -412,6 +438,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsrz + * * @param srz Sensitivity of rz, total derivative * @param ie event index * @param t current time @@ -429,6 +456,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdzdp + * * @param dzdp partial derivative of event-resolved output z w.r.t. model * parameters p * @param ie event index @@ -446,6 +474,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdzdx + * * @param dzdx partial derivative of event-resolved output z w.r.t. model * states x * @param ie event index @@ -462,6 +491,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdrzdp + * * @param drzdp partial derivative of root output rz w.r.t. model parameters * p * @param ie event index @@ -479,6 +509,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdrzdx + * * @param drzdx partial derivative of root output rz w.r.t. model states x * @param ie event index * @param t current time @@ -494,6 +525,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdeltax + * * @param deltax state update * @param t current time * @param x current state @@ -513,6 +545,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdeltasx + * * @param deltasx sensitivity update * @param t current time * @param x current state @@ -538,6 +571,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdeltaxB + * * @param deltaxB adjoint state update * @param t current time * @param x current state @@ -563,6 +597,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdeltaqB + * * @param deltaqB sensitivity update * @param t current time * @param x current state @@ -587,6 +622,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsigmay + * * @param sigmay standard deviation of measurements * @param t current time * @param p parameter vector @@ -600,6 +636,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdsigmaydp + * * @param dsigmaydp partial derivative of standard deviation of measurements * @param t current time * @param p parameter vector @@ -613,6 +650,7 @@ class AbstractModel { ); /** * @brief Model-specific implementation of fsigmay + * * @param dsigmaydy partial derivative of standard deviation of measurements * w.r.t. model outputs * @param t current time @@ -627,6 +665,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsigmaz + * * @param sigmaz standard deviation of event measurements * @param t current time * @param p parameter vector @@ -637,6 +676,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fsigmaz + * * @param dsigmazdp partial derivative of standard deviation of event * measurements * @param t current time @@ -651,6 +691,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fJy + * * @param nllh negative log-likelihood for measurements y * @param iy output index * @param p parameter vector @@ -665,6 +706,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fJz + * * @param nllh negative log-likelihood for event measurements z * @param iz event output index * @param p parameter vector @@ -679,6 +721,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fJrz + * * @param nllh regularization for event measurements z * @param iz event output index * @param p parameter vector @@ -693,6 +736,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJydy + * * @param dJydy partial derivative of time-resolved measurement negative * log-likelihood Jy * @param iy output index @@ -709,6 +753,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJydy colptrs + * * @param dJydy sparse matrix to which colptrs will be written * @param index ytrue index */ @@ -716,6 +761,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJydy rowvals + * * @param dJydy sparse matrix to which rowvals will be written * @param index `ytrue` index */ @@ -723,6 +769,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJydsigma + * * @param dJydsigma Sensitivity of time-resolved measurement negative * log-likelihood Jy w.r.t. standard deviation sigmay * @param iy output index @@ -739,6 +786,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJzdz + * * @param dJzdz partial derivative of event measurement negative * log-likelihood Jz * @param iz event output index @@ -755,6 +803,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJzdsigma + * * @param dJzdsigma Sensitivity of event measurement negative log-likelihood * Jz w.r.t. standard deviation sigmaz * @param iz event output index @@ -771,6 +820,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJrzdz + * * @param dJrzdz partial derivative of event penalization Jrz * @param iz event output index * @param p parameter vector @@ -785,6 +835,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdJrzdsigma + * * @param dJrzdsigma Sensitivity of event penalization Jrz w.r.t. standard * deviation sigmaz * @param iz event output index @@ -800,6 +851,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fw + * * @param w Recurring terms in xdot * @param t timepoint * @param x vector with the states @@ -820,6 +872,7 @@ class AbstractModel { /** * @brief Model-specific sparse implementation of dwdp + * * @param dwdp Recurring terms in xdot, parameter derivative * @param t timepoint * @param x vector with the states @@ -846,18 +899,21 @@ class AbstractModel { /** * @brief Model-specific implementation for dwdp, column pointers + * * @param dwdp sparse matrix to which colptrs will be written */ virtual void fdwdp_colptrs(SUNMatrixWrapper& dwdp); /** * @brief Model-specific implementation for dwdp, row values + * * @param dwdp sparse matrix to which rowvals will be written */ virtual void fdwdp_rowvals(SUNMatrixWrapper& dwdp); /** * @brief Model-specific implementation of dwdx, data part + * * @param dwdx Recurring terms in xdot, state derivative * @param t timepoint * @param x vector with the states @@ -880,18 +936,21 @@ class AbstractModel { /** * @brief Model-specific implementation for dwdx, column pointers + * * @param dwdx sparse matrix to which colptrs will be written */ virtual void fdwdx_colptrs(SUNMatrixWrapper& dwdx); /** * @brief Model-specific implementation for dwdx, row values + * * @param dwdx sparse matrix to which rowvals will be written */ virtual void fdwdx_rowvals(SUNMatrixWrapper& dwdx); /** * @brief Model-specific implementation of fdwdw, no w chainrule + * * @param dwdw partial derivative w wrt w * @param t timepoint * @param x Vector with the states @@ -913,18 +972,21 @@ class AbstractModel { /** * @brief Model-specific implementation of fdwdw, colptrs part + * * @param dwdw sparse matrix to which colptrs will be written */ virtual void fdwdw_colptrs(SUNMatrixWrapper& dwdw); /** * @brief Model-specific implementation of fdwdw, rowvals part + * * @param dwdw sparse matrix to which rowvals will be written */ virtual void fdwdw_rowvals(SUNMatrixWrapper& dwdw); /** * @brief Compute dx_rdata / dx_solver + * * @param dx_rdatadx_solver dx_rdata / dx_solver * @param p parameter vector * @param k constant vector @@ -938,18 +1000,21 @@ class AbstractModel { /** * @brief Model-specific implementation of fdx_rdatadx_solver, colptrs part + * * @param dxrdatadxsolver sparse matrix to which colptrs will be written */ virtual void fdx_rdatadx_solver_colptrs(SUNMatrixWrapper& dxrdatadxsolver); /** * @brief Model-specific implementation of fdx_rdatadx_solver, rowvals part + * * @param dxrdatadxsolver sparse matrix to which rowvals will be written */ virtual void fdx_rdatadx_solver_rowvals(SUNMatrixWrapper& dxrdatadxsolver); /** * @brief Compute dx_rdata / dp + * * @param dx_rdatadp dx_rdata / dp * @param p parameter vector * @param k constant vector @@ -964,6 +1029,7 @@ class AbstractModel { /** * @brief Compute dx_rdata / dtcl + * * @param dx_rdatadtcl dx_rdata / dtcl * @param p parameter vector * @param k constant vector @@ -977,18 +1043,21 @@ class AbstractModel { /** * @brief Model-specific implementation of fdx_rdatadtcl, colptrs part + * * @param dx_rdatadtcl sparse matrix to which colptrs will be written */ virtual void fdx_rdatadtcl_colptrs(SUNMatrixWrapper& dx_rdatadtcl); /** * @brief Model-specific implementation of fdx_rdatadtcl, rowvals part + * * @param dx_rdatadtcl sparse matrix to which rowvals will be written */ virtual void fdx_rdatadtcl_rowvals(SUNMatrixWrapper& dx_rdatadtcl); /** * @brief Compute dtotal_cl / dp + * * @param dtotal_cldp dtotal_cl / dp * @param x_rdata State variables with conservation laws applied * @param p parameter vector @@ -1002,6 +1071,7 @@ class AbstractModel { /** * @brief Compute dtotal_cl / dx_rdata + * * @param dtotal_cldx_rdata dtotal_cl / dx_rdata * @param x_rdata State variables with conservation laws applied * @param p parameter vector @@ -1015,6 +1085,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdtotal_cldx_rdata, colptrs part + * * @param dtotal_cldx_rdata sparse matrix to which colptrs will be written */ virtual void @@ -1022,6 +1093,7 @@ class AbstractModel { /** * @brief Model-specific implementation of fdtotal_cldx_rdata, rowvals part + * * @param dtotal_cldx_rdata sparse matrix to which rowvals will be written */ virtual void @@ -1029,6 +1101,7 @@ class AbstractModel { /** * @brief Model-specific implementation of spline creation + * * @param p parameter vector * @param k constants vector * @return Vector of splines used in the model @@ -1039,6 +1112,7 @@ class AbstractModel { /** * @brief Model-specific implementation the parametric derivatives * of spline node values + * * @param dspline_valuesdp vector to which derivatives will be written * @param p parameter vector * @param k constants vector @@ -1051,6 +1125,7 @@ class AbstractModel { /** * @brief Model-specific implementation the parametric derivatives * of slopevalues at spline nodes + * * @param dspline_slopesdp vector to which derivatives will be written * @param p parameter vector * @param k constants vector @@ -1062,6 +1137,7 @@ class AbstractModel { /** * @brief Compute explicit roots of the model. + * * @param p parameter vector * @param k constant vector * @param w vector with helper variables diff --git a/include/amici/amici.h b/include/amici/amici.h index fa6254d10a..83b5d78250 100644 --- a/include/amici/amici.h +++ b/include/amici/amici.h @@ -41,6 +41,7 @@ std::vector> run_simulations( /** * @brief Get the string representation of the given simulation status code * (see ReturnData::status). + * * @param status Status code * @return Name of the variable representing this status code. */ diff --git a/include/amici/cblas.h b/include/amici/cblas.h index d8f320c821..2635cd4df4 100644 --- a/include/amici/cblas.h +++ b/include/amici/cblas.h @@ -62,6 +62,7 @@ void amici_dgemm( /** * @brief Compute y = a*x + y + * * @param n number of elements in y * @param alpha scalar coefficient of x * @param x vector of length n*incx diff --git a/include/amici/edata.h b/include/amici/edata.h index 98f4030e48..50be101019 100644 --- a/include/amici/edata.h +++ b/include/amici/edata.h @@ -471,6 +471,7 @@ class ExpData : public SimulationParameters { /** * @brief Equality operator + * * @param lhs some object * @param rhs another object * @return `true`, if both arguments are equal; `false` otherwise. @@ -541,6 +542,7 @@ class ConditionContext : public ContextManager { /** * @brief Restore original settings on constructor-supplied amici::Model. + * * Will be called during destruction. Explicit call is generally not * necessary. */ diff --git a/include/amici/event.h b/include/amici/event.h index af1d0a98ca..03e271f20d 100644 --- a/include/amici/event.h +++ b/include/amici/event.h @@ -29,6 +29,7 @@ class Event { public: /** * @brief Event constructor + * * @param id ID of the event * @param use_values_from_trigger_time Whether the event assignment is * evaluated using the state from the time point at which the event @@ -48,18 +49,21 @@ class Event { /** * @brief Get the ID of the event + * * @return The ID of the event. */ std::string const& get_id() const { return id_; } /** * @brief Get the initial value of the root function + * * @return The value of the root function at t_0. */ bool get_initial_value() const { return initial_value_; } /** * @brief Get the priority of the event assignments + * * @return The priority of the event assignments, or NAN if undefined. */ realtype get_priority() const { return priority_; } @@ -138,18 +142,21 @@ class EventQueue { /** * @brief Check if the queue is empty + * * @return True if the queue is empty, false otherwise */ bool empty() const { return pending_events_.empty(); } /** * @brief Push an event to the queue + * * @param event The event to push */ void push(PendingEvent event) { pending_events_.push_back(event); } /** * @brief Get the next event to handle and remove it from the queue + * * @return The next event to handle * @throws std::runtime_error if there are no pending events */ @@ -167,7 +174,7 @@ class EventQueue { }); // If there is any undefined (NaN) priority, the order of all - // simulataneously executed events is undefined. We just proceed + // simultaneously executed events is undefined. We just proceed // with the first one in the list. if (std::any_of( pending_events_.begin(), pending_events_.end(), diff --git a/include/amici/exception.h b/include/amici/exception.h index d01d4c2b61..5e948a7b07 100644 --- a/include/amici/exception.h +++ b/include/amici/exception.h @@ -127,12 +127,13 @@ class IntegrationFailureB : public AmiException { public: /** * @brief Constructor - * @param code error code returned by cvode/ida + * + * @param code error code returned by CVODES/IDAS * @param t time of integration failure */ IntegrationFailureB(int code, realtype t); - /** error code returned by cvode/ida */ + /** error code returned by CVODES/IDAS */ int error_code; /** time of integration failure */ @@ -150,6 +151,7 @@ class SetupFailure : public AmiException { public: /** * @brief Constructor with printf style interface + * * @param fmt error message with printf format * @param ... printf formatting variables */ @@ -167,6 +169,7 @@ class NewtonFailure : public AmiException { public: /** * @brief Constructor, simply calls AmiException constructor + * * @param function name of the function in which the error occurred * @param code error code */ diff --git a/include/amici/forwardproblem.h b/include/amici/forwardproblem.h index 6774d36a04..0827a78c90 100644 --- a/include/amici/forwardproblem.h +++ b/include/amici/forwardproblem.h @@ -23,6 +23,7 @@ class FinalStateStorer; struct Discontinuity { /** * @brief Constructor. + * * @param time * @param root_info * @param x_pre @@ -92,6 +93,7 @@ struct Discontinuity { /** * @brief Compute the number of roots for each root function from a vector of * discontinuities. + * * @param discs Encountered discontinuities. * @param ne Number of root functions (ne). * @param nmaxevents Maximum number of events to track (nmaxevents). @@ -107,6 +109,7 @@ compute_nroots(std::vector const& discs, int ne, int nmaxevents); struct FwdSimWorkspace { /** * @brief Constructor + * * @param model The model for which to set up the workspace. * @param solver The solver for which to set up this workspace. */ @@ -200,6 +203,7 @@ class EventHandlingSimulator { public: /** * @brief EventHandlingSimulator + * * @param model The model to simulate. * @param solver The solver to use for the simulation. * @param ws The workspace to use for the simulation. @@ -262,6 +266,7 @@ class EventHandlingSimulator { /** * @brief Returns maximal event index for which the timepoint is available + * * @return index */ [[nodiscard]] int get_root_counter() const { @@ -270,6 +275,7 @@ class EventHandlingSimulator { /** * @brief Returns maximal event index for which simulations are available + * * @return index */ [[nodiscard]] int get_event_counter() const { @@ -278,6 +284,7 @@ class EventHandlingSimulator { /** * @brief Creates a carbon copy of the current simulation state variables + * * @return state */ SimulationState get_simulation_state(); @@ -319,6 +326,7 @@ class EventHandlingSimulator { /** * @brief Check for, and if applicable, handle any secondary events + * * @return the number of secondary events found */ int detect_secondary_events(); @@ -410,6 +418,7 @@ class SteadyStateProblem { /** * @brief Return state at steady state + * * @return x */ [[nodiscard]] AmiVector const& get_state() const { @@ -418,6 +427,7 @@ class SteadyStateProblem { /** * @brief Return state sensitivity at steady state + * * @return sx */ [[nodiscard]] AmiVectorArray const& get_state_sensitivity() const { @@ -426,12 +436,14 @@ class SteadyStateProblem { /** * @brief Get the CPU time taken to solve the forward problem. + * * @return The CPU time in milliseconds. */ [[nodiscard]] double get_cpu_time() const { return cpu_time_; } /** * @brief Get the steady state computation status. + * * @return Execution status of the different approaches * [newton, simulation, newton]. */ @@ -442,6 +454,7 @@ class SteadyStateProblem { /** * @brief Get model time at which steady state was found through simulation. + * * @return Time at which steady state was found (model time units). */ [[nodiscard]] realtype get_steady_state_time() const { @@ -450,12 +463,14 @@ class SteadyStateProblem { /** * @brief Get the weighted root mean square of the residuals. + * * @return The weighted root-mean-square of the residuals. */ [[nodiscard]] realtype get_residual_norm() const { return wrms_; } /** * @brief Get the number of steps taken to find the steady state. + * * @return Number of steps taken to find the steady state as * [newton, simulation, newton]. */ @@ -466,18 +481,21 @@ class SteadyStateProblem { /** * @brief Check, whether any approach to find the steady state was * successful. + * * @return Whether any approach to find the steady state was successful. */ [[nodiscard]] bool check_steady_state_success() const; /** * @brief Get the pre-equilibration solver. + * * @return The preequilibration solver. */ [[nodiscard]] Solver const* get_solver() const { return solver_; } /** - * @brief Get the preequilibration result. + * @brief Get the pre-equilibration result. + * * @return */ [[nodiscard]] PeriodResult const& get_result() const { @@ -497,6 +515,7 @@ class SteadyStateProblem { /** * @brief Try to determine the steady state by using Newton's method. + * * @param newton_retry Flag indicating whether Newton's method is being * relaunched. */ @@ -504,6 +523,7 @@ class SteadyStateProblem { /** * @brief Try to determine the steady state by using forward simulation. + * * @param it Index of the current output time point. * @param t0 Initial time for the steady state simulation. * @return SteadyStateStatus indicating whether the steady state was found @@ -512,7 +532,8 @@ class SteadyStateProblem { SteadyStateStatus find_steady_state_by_simulation(int it, realtype t0); /** - * @brief Store state and throw an exception if equilibration failed + * @brief Store state and throw an exception if equilibration failed. + * * @param tried_newton_1 Whether any Newton step was attempted before * simulation * @param tried_simulation Whether simulation was attempted @@ -524,7 +545,8 @@ class SteadyStateProblem { ) const; /** - * @brief Checks convergence for state sensitivities + * @brief Checks convergence for state sensitivities. + * * @param wrms_computer_sx WRMSComputer instance for state sensitivities * @return weighted root mean squared residuals of the RHS */ @@ -533,7 +555,6 @@ class SteadyStateProblem { /** * @brief Launch simulation if Newton solver or linear system solve * fail or are disabled. - * simulation. */ void run_steadystate_simulation_fwd(); @@ -632,6 +653,7 @@ class ForwardProblem { public: /** * @brief Constructor + * * @param edata pointer to ExpData instance * @param model pointer to Model instance * @param solver pointer to Solver instance @@ -658,6 +680,7 @@ class ForwardProblem { /** * @brief Computes adjoint updates dJydx according to the provided model * and ExpData. + * * @param model Model instance * @param edata experimental data * @return dJydx @@ -667,6 +690,7 @@ class ForwardProblem { /** * @brief Accessor for sx + * * @return sx */ [[nodiscard]] AmiVectorArray const& get_state_sensitivity() const { @@ -675,6 +699,7 @@ class ForwardProblem { /** * @brief Get information on the discontinuities encountered so far. + * * @return The vector of discontinuities. */ [[nodiscard]] std::vector const& @@ -684,6 +709,7 @@ class ForwardProblem { /** * @brief Accessor for dJzdx + * * @return dJzdx */ [[nodiscard]] std::vector const& get_dJzdx() const { @@ -692,12 +718,14 @@ class ForwardProblem { /** * @brief Accessor for it + * * @return it */ [[nodiscard]] int get_current_time_iteration() const { return it_; } /** * @brief Returns final time point for which simulations are available + * * @return time point */ [[nodiscard]] realtype get_final_time() const { @@ -706,6 +734,7 @@ class ForwardProblem { /** * @brief Returns maximal event index for which simulations are available + * * @return index */ [[nodiscard]] int get_event_counter() const { @@ -715,6 +744,7 @@ class ForwardProblem { /** * @brief Retrieves the carbon copy of the simulation state variables at * the specified timepoint index + * * @param it timepoint index * @return state */ @@ -733,6 +763,7 @@ class ForwardProblem { /** * @brief Retrieves the carbon copy of the simulation state variables at * the specified event index + * * @param iroot event index * @return SimulationState */ @@ -744,6 +775,7 @@ class ForwardProblem { /** * @brief Retrieves the carbon copy of the simulation state variables at the * initial timepoint + * * @return SimulationState */ [[nodiscard]] SimulationState const& get_initial_simulation_state() const { @@ -753,6 +785,7 @@ class ForwardProblem { /** * @brief Retrieves the carbon copy of the simulation state variables at the * final timepoint (or when the simulation failed) + * * @return SimulationState */ [[nodiscard]] SimulationState const& get_final_simulation_state() const { @@ -761,6 +794,7 @@ class ForwardProblem { /** * @brief Return the preequilibration SteadyStateProblem. + * * @return The preequilibration SteadyStateProblem, if any. */ [[nodiscard]] SteadyStateProblem* get_preeq_problem() { @@ -771,6 +805,7 @@ class ForwardProblem { /** * @brief Return the preequilibration SteadyStateProblem. + * * @return The preequilibration SteadyStateProblem, if any. */ [[nodiscard]] SteadyStateProblem const* get_preeq_problem() const { @@ -781,6 +816,7 @@ class ForwardProblem { /** * @brief Return the postequilibration SteadyStateProblem. + * * @return The postequilibration SteadyStateProblem, if any. */ [[nodiscard]] SteadyStateProblem* get_posteq_problem() { @@ -791,6 +827,7 @@ class ForwardProblem { /** * @brief Return the postequilibration SteadyStateProblem. + * * @return The postequilibration SteadyStateProblem, if any. */ [[nodiscard]] SteadyStateProblem const* get_posteq_problem() const { @@ -801,6 +838,7 @@ class ForwardProblem { /** * @brief Get the presimulation results. + * * @return Presimulation results. */ PeriodResult const& get_presimulation_result() const { @@ -809,6 +847,7 @@ class ForwardProblem { /** * @brief Whether pre-equilibration was performed successfully. + * * @return */ bool was_preequilibrated() const { return preequilibrated_; } @@ -894,6 +933,7 @@ class FinalStateStorer : public ContextManager { public: /** * @brief constructor, attaches problem pointer + * * @param fwd problem from which the simulation state is to be stored */ explicit FinalStateStorer(ForwardProblem* fwd) diff --git a/include/amici/hdf5.h b/include/amici/hdf5.h index 9861bdb81d..65de98e745 100644 --- a/include/amici/hdf5.h +++ b/include/amici/hdf5.h @@ -64,6 +64,7 @@ void write_solver_settings_to_hdf5( /** * @brief Write solver options to HDF5 file. + * * @param file File to read from * @param solver Solver to write options from * @param hdf5Location Path inside the HDF5 file @@ -75,6 +76,7 @@ void write_solver_settings_to_hdf5( /** * @brief Read solver options from HDF5 file. + * * @param hdffile Name of HDF5 file * @param solver Solver to set options on * @param datasetPath Path inside the HDF5 file @@ -85,6 +87,7 @@ void read_solver_settings_from_hdf5( /** * @brief Read model data from HDF5 file. + * * @param hdffile Name of HDF5 file * @param model Model to set data on * @param datasetPath Path inside the HDF5 file @@ -95,6 +98,7 @@ void read_model_data_from_hdf5( /** * @brief Read model data from HDF5 file. + * * @param file HDF5 file handle to read from * @param model Model to set data on * @param datasetPath Path inside the HDF5 file @@ -105,6 +109,7 @@ void read_model_data_from_hdf5( /** * @brief Write ReturnData to HDF5 file. + * * @param rdata Data to write * @param file HDF5 file to write to * @param hdf5Location Full dataset path inside the HDF5 file (will be created) @@ -117,6 +122,7 @@ void write_return_data_to_hdf5( /** * @brief Write ReturnData to HDF5 file. + * * @param rdata Data to write * @param hdf5Filename Filename of HDF5 file * @param hdf5Location Full dataset path inside the HDF5 file (will be created) @@ -129,6 +135,7 @@ void write_return_data_to_hdf5( /** * @brief Write ReturnData diagnosis data to HDF5 file. + * * @param rdata Data to write * @param file HDF5 file to write to * @param hdf5Location Full dataset path inside the HDF5 file (will be created) @@ -140,6 +147,7 @@ void write_return_data_diagnosis( /** * @brief Write log message to HDF5 file + * * @param file HDF5 file to write to * @param logItems Log items to write * @param hdf5Location Full dataset path inside the HDF5 file (will be created) @@ -151,6 +159,7 @@ void write_log_items_to_hdf5( /** * @brief Create the given group and possibly parents. + * * @param file HDF5 file to write to * @param groupPath Path to the group to be created * @param recursively Create intermediary groups @@ -162,6 +171,7 @@ void create_group( /** * @brief Read AMICI ExpData data from HDF5 file. + * * @param hdf5Filename Name of HDF5 file * @param hdf5Root Path inside the HDF5 file to object having ExpData * @param model The model for which data is to be read @@ -175,6 +185,7 @@ std::unique_ptr read_exp_data_from_hdf5( /** * @brief Write AMICI experimental data to HDF5 file. + * * @param edata The experimental data which is to be written * @param file HDF5 file * @param hdf5Location Path inside the HDF5 file @@ -187,6 +198,7 @@ void write_exp_data_to_hdf5( /** * @brief Write AMICI experimental data to HDF5 file. + * * @param edata The experimental data which is to be written * @param filepath Name of HDF5 file * @param hdf5Location Path inside the HDF5 file @@ -199,6 +211,7 @@ void write_exp_data_to_hdf5( /** * @brief Check whether an attribute with the given name exists * on the given dataset. + * * @param file The HDF5 file object * @param optionsObject Dataset of which attributes should be checked * @param attributeName Name of the attribute of interest @@ -212,6 +225,7 @@ bool attribute_exists( /** * @brief Check whether an attribute with the given name exists * on the given object. + * * @param object An HDF5 object * @param attributeName Name of the attribute of interest * @return `true` if attribute exists, `false` otherwise @@ -222,6 +236,7 @@ bool attribute_exists( /** * @brief Create and write to 1-dimensional native integer dataset. + * * @param file HDF5 file object * @param datasetName Name of dataset to create * @param buffer Data to write to dataset @@ -233,6 +248,7 @@ void create_and_write_int_1d_dataset( /** * @brief Create and write to 2-dimensional native integer dataset. + * * @param file HDF5 file object * @param datasetName Name of dataset to create * @param buffer Flattened data to write to dataset (assuming row-major) @@ -246,6 +262,7 @@ void create_and_write_int_2d_dataset( /** * @brief Create and write to 1-dimensional native double dataset. + * * @param file HDF5 file object * @param datasetName Name of dataset to create * @param buffer Data to write to dataset @@ -257,6 +274,7 @@ void create_and_write_double_1d_dataset( /** * @brief Create and write to 2-dimensional native double dataset. + * * @param file HDF5 file object * @param datasetName Name of dataset to create * @param buffer Flattened data to write to dataset (assuming row-major) @@ -271,6 +289,7 @@ void create_and_write_double_2d_dataset( /** * @brief Create and write to 3-dimensional native double dataset. + * * @param file HDF5 file object * @param datasetName Name of dataset to create * @param buffer Flattened data to write to dataset (assuming row-major) @@ -286,6 +305,7 @@ void create_and_write_double_3d_dataset( /** * @brief Read string attribute from HDF5 object. + * * @param file HDF5 file * @param optionsObject Object to read attribute from * @param attributeName Name of attribute to read @@ -298,6 +318,7 @@ std::string get_string_attribute( /** * @brief Read scalar native double attribute from HDF5 object. + * * @param file HDF5 file * @param optionsObject Object to read attribute from * @param attributeName Name of attribute to read @@ -310,6 +331,7 @@ double get_double_scalar_attribute( /** * @brief Read scalar native integer attribute from HDF5 object. + * * @param file HDF5 file * @param optionsObject Object to read attribute from * @param attributeName Name of attribute to read @@ -323,6 +345,7 @@ int get_int_scalar_attribute( /** * @brief Read 1-dimensional native integer dataset from HDF5 file. + * * @param file HDF5 file object * @param name Name of dataset to read * @return Data read @@ -332,6 +355,7 @@ get_int_1d_dataset(const H5::H5File& file, std::string const& name); /** * @brief Read 1-dimensional native double dataset from HDF5 file. + * * @param file HDF5 file object * @param name Name of dataset to read * @return Data read @@ -342,6 +366,7 @@ get_double_1d_dataset(const H5::H5File& file, std::string const& name); /** * @brief Read 2-dimensional native double dataset from HDF5 file. + * * @param file HDF5 file object * @param name Name of dataset to read * @param m Number of rows in the dataset @@ -355,6 +380,7 @@ std::vector get_double_2d_dataset( /** * @brief Read 3-dimensional native double dataset from HDF5 file. + * * @param file HDF5 file object * @param name Name of dataset to read * @param m Length of first dimension in dataset @@ -371,6 +397,7 @@ std::vector get_double_3d_dataset( /** * @brief Check if the given location (group, link or dataset) exists in the * given file. + * * @param filename HDF5 filename * @param location Location to test for * @return `true` if exists, `false` otherwise @@ -380,6 +407,7 @@ bool location_exists(std::string const& filename, std::string const& location); /** * @brief Check if the given location (group, link or dataset) exists in the * given file. + * * @param file HDF5 file object * @param location Location to test for * @return `true` if exists, `false` otherwise diff --git a/include/amici/logging.h b/include/amici/logging.h index a70ecdbeda..3aa699ec33 100644 --- a/include/amici/logging.h +++ b/include/amici/logging.h @@ -25,6 +25,7 @@ class Logger { Logger() = default; /** * @brief Add a log entry + * * @param severity Severity level * @param identifier Short identifier for the logged event * @param message A more detailed message @@ -46,6 +47,7 @@ class Logger { // see https://github.com/swig/swig/issues/1643 /** * @brief Add a log entry with printf-like message formatting + * * @param severity Severity level * @param identifier Short identifier for the logged event * @param format printf format string @@ -70,6 +72,7 @@ struct LogItem { /** * @brief Construct a LogItem + * * @param severity * @param identifier * @param message diff --git a/include/amici/misc.h b/include/amici/misc.h index 240f0403a1..a4653aa410 100644 --- a/include/amici/misc.h +++ b/include/amici/misc.h @@ -60,6 +60,7 @@ gsl::span slice(std::vector const& data, int index, unsigned size) { /** * @brief local helper to check whether the provided buffer has the expected * size + * * @param buffer buffer to which values are to be written * @param expected_size expected size of the buffer */ @@ -80,6 +81,7 @@ void check_buffer_size( /** * @brief local helper function to write computed slice to provided buffer * (span) + * * @param slice computed value * @param buffer buffer to which values are to be written */ @@ -92,6 +94,7 @@ void write_slice(gsl::span const slice, gsl::span buffer) { /** * @brief local helper function to add the computed slice to provided buffer * (span) + * * @param slice computed value * @param buffer buffer to which values are to be added */ @@ -107,6 +110,7 @@ void add_slice(gsl::span const slice, gsl::span buffer) { /** * @brief local helper function to write computed slice to provided buffer * (vector) + * * @param s computed value * @param b buffer to which values are to be written */ @@ -120,6 +124,7 @@ void write_slice(std::vector const& s, std::vector& b) { /** * @brief local helper function to write computed slice to provided buffer * (vector/span) + * * @param s computed value * @param b buffer to which values are to be written */ @@ -130,6 +135,7 @@ template void write_slice(std::vector const& s, gsl::span b) { /** * @brief local helper function to add the computed slice to provided buffer * (vector/span) + * * @param s computed value * @param b buffer to which values are to be written */ @@ -140,6 +146,7 @@ template void add_slice(std::vector const& s, gsl::span b) { /** * @brief local helper function to write computed slice to provided buffer * (AmiVector/span) + * * @param s computed value * @param b buffer to which values are to be written */ @@ -171,6 +178,7 @@ double unscale_parameter(double scaledParameter, ParameterScaling scaling); /** * @brief Apply parameter scaling according to `scaling` + * * @param unscaledParameter * @param scaling parameter scaling * @return Scaled parameter @@ -179,6 +187,7 @@ double scale_parameter(double unscaledParameter, ParameterScaling scaling); /** * @brief Apply parameter scaling according to `scaling` + * * @param bufferUnscaled * @param pscale parameter scaling * @param bufferScaled destination @@ -190,6 +199,7 @@ void scale_parameters( /** * @brief Returns the current backtrace as std::string + * * @param maxFrames Number of frames to include * @param first_frame Index of first frame to include * @return Backtrace @@ -198,6 +208,7 @@ std::string get_backtrace_string(int maxFrames, int first_frame = 0); /** * @brief Convert std::regex_constants::error_type to string + * * @param err_type error type * @return Error type as string */ @@ -205,6 +216,7 @@ std::string regex_error_to_string(std::regex_constants::error_type err_type); /** * @brief Format printf-style arguments to std::string + * * @param fmt Format string * @param ap Argument list pointer * @return Formatted String @@ -225,6 +237,7 @@ class ContextManager { /** * @brief Convert a flat index to a pair of row/column indices, * assuming row-major order. + * * @param flat_idx flat index * @param num_cols number of columns of referred to matrix * @return row index, column index @@ -235,6 +248,7 @@ auto unravel_index(size_t flat_idx, size_t num_cols) /** * @brief Check if two spans are equal, treating NaNs in the same position as * equal. + * * @param a * @param b * @return Whether the contents of the two spans are equal. @@ -289,6 +303,7 @@ class CpuTimer { /** * @brief Get elapsed CPU time in seconds since initialization or last reset + * * @return CPU time in seconds */ [[nodiscard]] double elapsed_seconds() const { @@ -298,6 +313,7 @@ class CpuTimer { /** * @brief Get elapsed CPU time in milliseconds since initialization or last * reset + * * @return CPU time in milliseconds */ [[nodiscard]] double elapsed_milliseconds() const { @@ -331,6 +347,7 @@ class CpuTimer { /** * @brief Get elapsed CPU time in seconds since initialization or last reset + * * @return CPU time in seconds */ double elapsed_seconds() const { @@ -340,6 +357,7 @@ class CpuTimer { /** * @brief Get elapsed CPU time in milliseconds since initialization or last * reset + * * @return CPU time in milliseconds */ double elapsed_milliseconds() const { diff --git a/include/amici/model.h b/include/amici/model.h index 88181d3897..f63ead2004 100644 --- a/include/amici/model.h +++ b/include/amici/model.h @@ -106,6 +106,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Constructor with model dimensions. + * * @param model_dimensions Model dimensions * @param simulation_parameters Simulation parameters * @param o2mode Second order sensitivity mode @@ -125,6 +126,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Copy assignment is disabled until const members are removed. + * * @param other Object to copy from * @return */ @@ -132,12 +134,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Clone this instance. + * * @return The clone */ [[nodiscard]] virtual Model* clone() const = 0; /** * @brief Serialize Model (see `boost::serialization::serialize`). + * * @param ar Archive to serialize to * @param m Data to serialize * @param version Version number @@ -149,6 +153,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Check equality of data members. + * * @param a First model instance * @param b Second model instance * @return Equality @@ -216,6 +221,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Initialize model properties. + * * @param t Timepoint * @param x Reference to state variables * @param dx Reference to time derivative of states (DAE only) @@ -234,6 +240,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Re-initialize model properties after changing simulation context. + * * @param t Timepoint * @param x Reference to state variables * @param sx Reference to state variable sensitivities @@ -246,6 +253,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Initialize model properties. + * * @param xB Adjoint state variables * @param dxB Time derivative of adjoint states (DAE only) * @param xQB Adjoint quadratures @@ -257,6 +265,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Initialize model state. + * * @param t Initial timepoint * @param x State vector to be initialized (size: nx_solver). */ @@ -264,6 +273,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Initialize initial state sensitivities. + * * @param t Initial timepoint. * @param sx Reference to state variable sensitivities * @param x Reference to state variables @@ -323,24 +333,28 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get number of parameters wrt to which sensitivities are computed. + * * @return Length of sensitivity index vector */ int nplist() const; /** * @brief Get total number of model parameters. + * * @return Length of parameter vector */ int np() const; /** - * @brief Get number of constants - * @return Length of constant vector + * @brief Get number of fixed parameters. + * + * @return Number of fixed parameters. */ int nk() const; /** * @brief Get number of conservation laws. + * * @return Number of conservation laws (i.e., difference between `nx_rdata` * and `nx_solver`). */ @@ -348,36 +362,42 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get number of solver states subject to reinitialization. + * * @return Model member `nx_solver_reinit` */ int nx_reinit() const; /** * @brief Get fixed parameters. + * * @return Pointer to constants array */ double const* k() const; /** * @brief Get maximum number of events that may occur for each type. + * * @return Maximum number of events that may occur for each type */ int n_max_event() const; /** * @brief Set maximum number of events that may occur for each type. + * * @param nmaxevent Maximum number of events that may occur for each type */ void set_n_max_event(int nmaxevent); /** * @brief Get number of timepoints. + * * @return Number of timepoints */ int nt() const; /** * @brief Get parameter scale for each parameter. + * * @return Vector of parameter scales */ std::vector const& get_parameter_scale() const; @@ -403,18 +423,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get parameters with transformation according to parameter scale * applied. + * * @return Unscaled parameters */ std::vector const& get_unscaled_parameters() const; /** * @brief Get parameter vector. + * * @return The user-set parameters (see also `Model::getUnscaledParameters`) */ std::vector const& get_free_parameters() const; /** * @brief Get value of first model parameter with the specified ID. + * * @param par_id Parameter ID * @return Parameter value */ @@ -422,6 +445,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get value of first model parameter with the specified name. + * * @param par_name Parameter name * @return Parameter value */ @@ -429,6 +453,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the parameter vector. + * * @param p Vector of parameters */ void set_free_parameters(std::vector const& p); @@ -436,6 +461,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set model parameters according to the parameter IDs and mapped * values. + * * @param p Map of parameters IDs and values * @param ignoreErrors Ignore errors such as parameter IDs in p which are * not model parameters @@ -446,6 +472,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set value of first model parameter with the specified ID. + * * @param par_id Parameter ID * @param value Parameter value */ @@ -454,6 +481,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set all values of model parameters with IDs matching the specified * regular expression. + * * @param par_id_regex Parameter ID regex * @param value Parameter value * @return Number of parameter IDs that matched the regex @@ -464,6 +492,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set value of first model parameter with the specified name. + * * @param par_name Parameter name * @param value Parameter value */ @@ -473,6 +502,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set model parameters according to the parameter name and mapped * values. + * * @param p Map of parameters names and values * @param ignoreErrors Ignore errors such as parameter names in p which are * not model parameters @@ -484,6 +514,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set all values of all model parameters with names matching the * specified regex. + * * @param par_name_regex Parameter name regex * @param value Parameter value * @return Number of fixed parameter names that matched the regex @@ -494,6 +525,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get values of fixed parameters. + * * @return Vector of fixed parameters with same ordering as in * Model::getFixedParameterIds */ @@ -501,6 +533,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get value of fixed parameter with the specified ID. + * * @param par_id Parameter ID * @return Parameter value */ @@ -519,12 +552,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set values for constants. + * * @param k Vector of fixed parameters */ void set_fixed_parameters(std::vector const& k); /** * @brief Set value of first fixed parameter with the specified ID. + * * @param par_id Fixed parameter id * @param value Fixed parameter value */ @@ -533,6 +568,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set values of all fixed parameters with the ID matching the * specified regex. + * * @param par_id_regex Fixed parameter name regex * @param value Fixed parameter value * @return Number of fixed parameter IDs that matched the regex @@ -543,6 +579,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set value of first fixed parameter with the specified name. + * * @param par_name Fixed parameter ID * @param value Fixed parameter value */ @@ -552,6 +589,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set value of all fixed parameters with name matching the specified * regex. + * * @param par_name_regex Fixed parameter name regex * @param value Fixed parameter value * @return Number of fixed parameter names that matched the regex @@ -562,6 +600,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the model name. + * * @return Model name */ virtual std::string get_name() const; @@ -576,6 +615,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get names of the free model parameters. + * * @return The parameter names */ virtual std::vector get_free_parameter_names() const; @@ -590,18 +630,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get names of the model states. + * * @return State names */ virtual std::vector get_state_names() const; /** * @brief Get names of the solver states. + * * @return State names */ virtual std::vector get_state_names_solver() const; /** * @brief Report whether the model has fixed parameter names set. + * * @return Boolean indicating whether fixed parameter names were set. Also * returns `true` if the number of corresponding variables is just zero. */ @@ -609,12 +652,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get names of the fixed model parameters. + * * @return Fixed parameter names */ virtual std::vector get_fixed_parameter_names() const; /** * @brief Report whether the model has observable names set. + * * @return Boolean indicating whether observable names were set. Also * returns `true` if the number of corresponding variables is just zero. */ @@ -622,12 +667,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get names of the observables. + * * @return Observable names */ virtual std::vector get_observable_names() const; /** * @brief Report whether the model has expression names set. + * * @return Boolean indicating whether expression names were set. Also * returns `true` if the number of corresponding variables is just zero. */ @@ -635,12 +682,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get names of the expressions. + * * @return Expression names */ virtual std::vector get_expression_names() const; /** * @brief Report whether the model has parameter IDs set. + * * @return Boolean indicating whether parameter IDs were set. Also returns * `true` if the number of corresponding variables is just zero. */ @@ -648,12 +697,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get IDs of the model parameters. + * * @return Parameter IDs */ virtual std::vector get_free_parameter_ids() const; /** * @brief Report whether the model has state IDs set. + * * @return Boolean indicating whether state IDs were set. Also returns * `true` if the number of corresponding variables is just zero. */ @@ -661,18 +712,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get IDs of the model states. + * * @return State IDs */ virtual std::vector get_state_ids() const; /** * @brief Get IDs of the solver states. + * * @return State IDs */ virtual std::vector get_state_ids_solver() const; /** * @brief Report whether the model has fixed parameter IDs set. + * * @return Boolean indicating whether fixed parameter IDs were set. Also * returns `true` if the number of corresponding variables is just zero. */ @@ -680,12 +734,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get IDs of the fixed model parameters. + * * @return Fixed parameter IDs */ virtual std::vector get_fixed_parameter_ids() const; /** * @brief Report whether the model has observable IDs set. + * * @return Boolean indicating whether observable ids were set. Also returns * `true` if the number of corresponding variables is just zero. */ @@ -693,12 +749,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get IDs of the observables. + * * @return Observable IDs */ virtual std::vector get_observable_ids() const; /** * @brief Report whether the model has expression IDs set. + * * @return Boolean indicating whether expression ids were set. Also returns * `true` if the number of corresponding variables is just zero. */ @@ -706,6 +764,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get IDs of the expression. + * * @return Expression IDs */ virtual std::vector get_expression_ids() const; @@ -713,18 +772,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Checks whether the defined noise model is Gaussian, i.e., the nllh * is quadratic + * * @return boolean flag */ virtual bool has_quadratic_llh() const; /** * @brief Get the timepoint vector. + * * @return Timepoint vector */ std::vector const& get_timepoints() const; /** * @brief Get simulation timepoint for time index `it`. + * * @param it Time index * @return Timepoint */ @@ -732,12 +794,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the timepoint vector. + * * @param ts New timepoint vector */ void set_timepoints(std::vector const& ts); /** * @brief Get simulation start time. + * * @return Simulation start time */ double t0() const; @@ -756,6 +820,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the initial time to use for pre-equilibration. + * * @return Initial time, or NAN to use the model's t0. */ double t0_preeq() const; @@ -771,6 +836,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get flags indicating whether states should be treated as * non-negative. + * * @return Vector of flags */ std::vector const& get_state_is_non_negative() const; @@ -778,6 +844,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set flags indicating whether states should be treated as * non-negative. + * * @param stateIsNonNegative Vector of flags */ void set_state_is_non_negative(std::vector const& stateIsNonNegative); @@ -790,12 +857,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the current model state. + * * @return Current model state */ ModelState const& get_model_state() const { return state_; } /** * @brief Set the current model state. + * * @param state Model state */ void set_model_state(ModelState const& state) { @@ -813,9 +882,11 @@ class Model : public AbstractModel, public ModelDimensions { } /** - * @brief Sets the estimated lower boundary for sigma_y. When - * :meth:`setAddSigmaResiduals` is activated, this lower boundary must + * @brief Sets the estimated lower boundary for sigma_y. + * + * When :meth:`setAddSigmaResiduals` is activated, this lower boundary must * ensure that log(sigma) + min_sigma > 0. + * * @param min_sigma lower boundary */ void set_minimum_sigma_residuals(double const min_sigma) { @@ -824,6 +895,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Gets the specified estimated lower boundary for sigma_y. + * * @return lower boundary */ [[nodiscard]] realtype get_minimum_sigma_residuals() const { @@ -849,18 +921,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Checks whether residuals should be added to account for parameter * dependent sigma. + * * @return sigma_res */ bool get_add_sigma_residuals() const { return sigma_res_; } /** * @brief Get the list of parameters for which sensitivities are computed. + * * @return List of parameter indices */ std::vector const& get_parameter_list() const; /** * @brief Get entry in parameter list by index. + * * @param pos Index in sensitivity parameter list * @return Index in parameter list */ @@ -878,6 +953,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the initial state. + * * @param t0 Custom t0 for which to get initial states. * @return Initial state vector, before any events are executed. */ @@ -885,6 +961,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the initial state for Model::t0()`. + * * @return Initial state vector, before any events are executed. */ std::vector get_initial_state() { @@ -893,18 +970,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the pre-event initial state. + * * @param x0 Initial state vector */ void set_initial_state(std::vector const& x0); /** * @brief Return whether custom initial state have been set. + * * @return `true` if has custom initial state, otherwise `false` */ [[nodiscard]] bool has_custom_initial_state() const; /** * @brief Get the initial state sensitivities. + * * @return vector of initial state sensitivities */ std::vector get_initial_state_sensitivities() { @@ -913,6 +993,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the initial states sensitivities. + * * @param t0 Custom t0 for which to get initial states. * @return vector of initial state sensitivities */ @@ -920,6 +1001,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the initial state sensitivities. + * * @param sx0 vector of initial state sensitivities with chain rule applied. * This could be a slice of ReturnData::sx or ReturnData::sx0 */ @@ -927,6 +1009,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Return whether custom initial state sensitivities have been set. + * * @return `true` if has custom initial state sensitivities, otherwise * `false`. */ @@ -934,6 +1017,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the initial state sensitivities. + * * @param sx0 Vector of initial state sensitivities without chain rule * applied. This could be the read-in from a `model.sx0data` saved to HDF5. */ @@ -943,6 +1027,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the mode how steady state is computed in the steady state * simulation. + * * @param mode Steady state computation mode */ void set_steady_state_computation_mode(SteadyStateComputationMode mode); @@ -950,6 +1035,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Gets the mode how steady state is computed in the steadystate * simulation. + * * @return Mode */ SteadyStateComputationMode get_steady_state_computation_mode() const; @@ -957,6 +1043,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set the mode how sensitivities are computed in the steady-state * simulation. + * * @param mode Steady-state sensitivity mode */ void set_steady_state_sensitivity_mode(SteadyStateSensitivityMode mode); @@ -964,6 +1051,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Gets the mode how sensitivities are computed in the steady-state * simulation. + * * @return Mode */ [[nodiscard]] SteadyStateSensitivityMode @@ -972,6 +1060,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set whether initial states depending on fixed parameters are to be * reinitialized after preequilibration and presimulation. + * * @param flag Fixed parameters reinitialized? */ void set_reinitialize_fixed_parameter_initial_states(bool flag); @@ -979,6 +1068,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get whether initial states depending on fixedParameters are to be * reinitialized after preequilibration and presimulation. + * * @return flag `true` / `false` */ [[nodiscard]] bool get_reinitialize_fixed_parameter_initial_states() const; @@ -993,6 +1083,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get time-resolved `w`. + * * @param w Buffer (shape `nw`) * @param t Current timepoint * @param x Current state @@ -1001,6 +1092,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get time-resolved observables. + * * @param y Buffer (shape `ny`) * @param t Current timepoint * @param x Current state @@ -1009,6 +1101,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get scaling type for observable + * * @param iy observable index * @return scaling type */ @@ -1020,6 +1113,7 @@ class Model : public AbstractModel, public ModelDimensions { * * Total derivative \f$ sy = dydx * sx + dydp\f$ * (only for forward sensitivities). + * * @param sy buffer (shape `ny` x `nplist`, row-major) * @param t Timpoint * @param x State variables @@ -1032,6 +1126,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get time-resolved observable standard deviations + * * @param sigmay Buffer (shape `ny`) * @param it Timepoint index * @param edata Pointer to experimental data instance (optional, pass @@ -1059,6 +1154,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Add time-resolved measurement negative log-likelihood \f$ Jy \f$. + * * @param Jy Buffer (shape 1) * @param it Timepoint index * @param x State variables @@ -1118,6 +1214,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get event-resolved observables. + * * @param z Output buffer (shape `nz`) * @param ie Event index * @param t Timepoint @@ -1153,6 +1250,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get regularization for event-resolved observables. + * * @param rz Output buffer (shape `nz`) * @param ie Event index * @param t Timepoint @@ -1180,6 +1278,7 @@ class Model : public AbstractModel, public ModelDimensions { ); /** * @brief Get event-resolved observable standard deviations. + * * @param sigmaz Output buffer (shape `nz`) * @param ie Event index * @param nroots Event occurrence @@ -1212,6 +1311,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Add event-resolved observable negative log-likelihood. + * * @param Jz Output buffer (shape 1) * @param ie Event index * @param nroots Event occurrence @@ -1226,6 +1326,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Add event-resolved observable negative log-likelihood. + * * @param Jrz Output buffer (shape 1) * @param ie Event index * @param nroots Event occurrence @@ -1316,6 +1417,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Update state variables after event. + * * @param x Current state (will be overwritten) * @param ie Event index * @param t Current timepoint @@ -1332,6 +1434,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Update state sensitivity after event. + * * @param sx Current state sensitivity (will be overwritten) * @param ie Event index * @param t Current timepoint @@ -1352,6 +1455,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Update adjoint state after event. + * * @param xB Current adjoint state (will be overwritten) * @param ie Event index * @param t Current timepoint @@ -1369,6 +1473,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Update adjoint quadratures after event. + * * @param xQB Current quadrature state (will be overwritten) * @param ie Event index * @param t Current timepoint @@ -1440,6 +1545,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set whether the result of every call to `Model::f*` should be * checked for finiteness. + * * @param alwaysCheck */ void set_always_check_finite(bool alwaysCheck); @@ -1447,12 +1553,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get setting of whether the result of every call to `Model::f*` * should be checked for finiteness. + * * @return that */ [[nodiscard]] bool get_always_check_finite() const; /** * @brief Compute/get pre-event initial state. + * * @param t Timepoint. * @param x Output buffer (size: nx_solver). */ @@ -1461,6 +1569,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set only those initial states that are specified via * fixed parameters. + * * @param t Timepoint. * @param x Output buffer. */ @@ -1468,6 +1577,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute/get initial value for initial state sensitivities. + * * @param t Timepoint. * @param sx Output buffer for state sensitivities * @param x State variables @@ -1477,6 +1587,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get only those initial states sensitivities that are affected * from `amici::Model::fx0_fixedParameters`. + * * @param t Timepoint * @param sx Output buffer for state sensitivities * @param x State variables @@ -1494,6 +1605,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Expand conservation law for states. + * * @param x_rdata Output buffer for state variables with conservation laws * expanded (stored in `amici::ReturnData`). * @param x_solver State variables with conservation laws applied @@ -1503,6 +1615,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Expand conservation law for state sensitivities. + * * @param sx_rdata Output buffer for state variables sensitivities with * conservation laws expanded * (stored in `amici::ReturnData` shape `nplist` x `nx`, row-major). @@ -1518,14 +1631,16 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Set indices of states to be reinitialized based on provided - * constants / fixed parameters + * fixed parameters + * * @param idxs Array of state indices */ void set_reinitialization_state_idxs(std::vector const& idxs); /** * @brief Return indices of states to be reinitialized based on provided - * constants / fixed parameters + * fixed parameters + * * @return Those indices. */ [[nodiscard]] std::vector const& @@ -1533,6 +1648,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief getter for dxdotdp + * * @return dxdotdp */ [[nodiscard]] SUNMatrixWrapper const& get_dxdotdp_full() const; @@ -1574,6 +1690,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get event object for event index. + * * @param ie event index * @return The corresponding Event object. */ @@ -1584,6 +1701,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Whether there is at least one state variable for which * non-negativity is to be enforced. + * * @return Vector of all events. */ [[nodiscard]] bool get_any_state_nonnegative() const { @@ -1605,12 +1723,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get flag array for DAE equations + * * @return Flag array for DAE equations */ std::vector const& get_id_list() const { return id_list_; } /** * @brief Get second-order sensitivity mode. + * * @return Flag indicating whether for `SensitivityOrder::second` * directional or full second order derivative will be computed */ @@ -1618,12 +1738,14 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get the logger. + * * @return Logger pointer or nullptr. */ Logger* get_logger() const { return logger_; } /** * @brief Set the logger. + * * @param logger Logger pointer or nullptr. */ void set_logger(Logger* logger) { logger_ = logger; } @@ -1631,6 +1753,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Get map of trigger timepoints to event indices for events that * don't require root-finding. + * * @return Map of trigger timepoints to event indices */ std::map> const& get_explicit_roots() const { @@ -1641,6 +1764,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Write part of a slice to a buffer according to indices specified * in z2event. + * * @param slice Input data slice * @param buffer Output data slice * @param ie Event index @@ -1652,6 +1776,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Write part of a sensitivity slice to a buffer according to * indices specified in z2event. + * * @param slice source data slice * @param buffer output data slice * @param ie event index @@ -1663,6 +1788,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Separate first and second order objective sensitivity information * and write them into the respective buffers. + * * @param dLLhdp Data with mangled first- and second-order information * @param sllh First order buffer * @param s2llh Second order buffer @@ -1674,6 +1800,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Verify that the provided buffers have the expected size. + * * @param sllh first order buffer * @param s2llh second order buffer */ @@ -1688,6 +1815,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute observables / measurements. + * * @param t Current timepoint * @param x Current state */ @@ -1696,6 +1824,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of observables \f$ y \f$ w.r.t. model * parameters `p`. + * * @param t Current timepoint * @param x Current state */ @@ -1704,6 +1833,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of observables \f$ y \f$ w.r.t. state * variables `x`. + * * @param t Current timepoint * @param x Current state */ @@ -1711,6 +1841,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute standard deviation of measurements. + * * @param it Timepoint index * @param edata Experimental data */ @@ -1719,6 +1850,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of standard deviation of measurements * w.r.t. model parameters. + * * @param it Timepoint index * @param edata pointer to `amici::ExpData` data instance holding sigma * values @@ -1728,6 +1860,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of standard deviation of measurements * w.r.t. model outputs. + * * @param it Timepoint index * @param edata pointer to `amici::ExpData` data instance holding sigma * values @@ -1737,6 +1870,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of time-resolved measurement negative * log-likelihood \f$ Jy \f$. + * * @param it timepoint index * @param x state variables * @param edata Pointer to experimental data @@ -1746,6 +1880,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Sensitivity of time-resolved measurement negative log-likelihood * Jy w.r.t. standard deviation sigma. + * * @param it timepoint index * @param x state variables * @param edata pointer to experimental data instance @@ -1755,6 +1890,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of time-resolved measurement negative * log-likelihood \f$ Jy \f$ w.r.t. parameters for the given timepoint. + * * @param it timepoint index * @param x state variables * @param edata pointer to experimental data instance @@ -1764,6 +1900,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Sensitivity of time-resolved measurement negative log-likelihood * \f$ Jy \f$ w.r.t. state variables. + * * @param it Timepoint index * @param x State variables * @param edata Pointer to experimental data instance @@ -1772,6 +1909,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute event-resolved output. + * * @param ie Event index * @param t Current timepoint * @param x Current state @@ -1781,6 +1919,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of event-resolved output `z` w.r.t. * model parameters `p` + * * @param ie event index * @param t current timepoint * @param x current state @@ -1790,6 +1929,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of event-resolved output `z` w.r.t. * model states `x`. + * * @param ie Event index * @param t Current timepoint * @param x Current state @@ -1810,6 +1950,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event-resolved root output w.r.t. model * parameters `p`. + * * @param ie Event index * @param t Current timepoint * @param x Current state @@ -1819,6 +1960,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event-resolved measurements \f$ rz \f$ * w.r.t. model states `x`. + * * @param ie Event index * @param t Current timepoint * @param x Current state @@ -1827,6 +1969,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute standard deviation of events. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1837,6 +1980,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of standard deviation of events measurements * w.r.t. model parameters `p`. + * * @param ie Event index * @param nroots Event occurrence * @param t Current timepoint @@ -1847,6 +1991,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of event measurement negative * log-likelihood \f$ Jz \f$. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1860,6 +2005,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event measurement negative log-likelihood * \f$ Jz \f$ w.r.t. standard deviation sigmaz. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1873,6 +2019,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event-resolved measurement negative * log-likelihood Jz w.r.t. parameters. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1886,6 +2033,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event-resolved measurement negative * log-likelihood Jz w.r.t. state variables. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1899,6 +2047,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute partial derivative of event measurement negative * log-likelihood J. + * * @param ie Event index * @param nroots Event index * @param t Current timepoint @@ -1912,6 +2061,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute sensitivity of event measurement negative log-likelihood * Jz w.r.t. standard deviation sigmaz + * * @param ie event index * @param nroots event index * @param t current timepoint @@ -1924,18 +2074,21 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Spline functions + * * @param t timepoint */ void fspl(realtype t); /** * @brief Parametric derivatives of splines functions + * * @param t timepoint */ void fsspl(realtype t); /** * @brief Compute recurring terms in xdot. + * * @param t Timepoint * @param x Array with the states * @param include_static Whether to (re-)evaluate only dynamic expressions @@ -1947,6 +2100,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute parameter derivative for recurring terms in xdot. + * * @param t Timepoint * @param x Array with the states * @param include_static Whether to (re-)evaluate only dynamic expressions @@ -1958,6 +2112,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute state derivative for recurring terms in xdot. + * * @param t Timepoint * @param x Array with the states * @param include_static Whether to (re-)evaluate only dynamic expressions @@ -1969,6 +2124,7 @@ class Model : public AbstractModel, public ModelDimensions { /** * @brief Compute self derivative for recurring terms in xdot. + * * @param t Timepoint * @param x Array with the states * @param include_static Whether to (re-)evaluate only dynamic expressions diff --git a/include/amici/model_dae.h b/include/amici/model_dae.h index 47fe33ffdf..3a22ec4767 100644 --- a/include/amici/model_dae.h +++ b/include/amici/model_dae.h @@ -28,6 +28,7 @@ class Model_DAE : public Model { /** * @brief Constructor with model dimensions + * * @param model_dimensions Model dimensions * @param simulation_parameters Simulation parameters * @param o2mode second order sensitivity mode @@ -61,6 +62,7 @@ class Model_DAE : public Model { /** * @brief Jacobian of xdot with respect to states x + * * @param t timepoint * @param cj scaling factor, inverse of the step size * @param x Vector with the states @@ -79,6 +81,7 @@ class Model_DAE : public Model { /** * @brief Jacobian of xBdot with respect to adjoint state xB + * * @param t timepoint * @param cj scaling factor, inverse of the step size * @param x Vector with the states @@ -98,6 +101,7 @@ class Model_DAE : public Model { /** * @brief J in sparse form (for sparse solvers from the SuiteSparse Package) + * * @param t timepoint * @param cj scalar in Jacobian (inverse stepsize) * @param x Vector with the states @@ -118,6 +122,7 @@ class Model_DAE : public Model { /** * @brief JB in sparse form (for sparse solvers from the SuiteSparse * Package) + * * @param t timepoint * @param cj scalar in Jacobian * @param x Vector with the states @@ -133,6 +138,7 @@ class Model_DAE : public Model { /** * @brief Diagonal of the Jacobian (for preconditioning) + * * @param t timepoint * @param JDiag Vector to which the Jacobian diagonal will be written * @param cj scaling factor, inverse of the step size @@ -152,6 +158,7 @@ class Model_DAE : public Model { /** * @brief Matrix vector product of J with a vector v (for iterative solvers) + * * @param t timepoint * @param cj scaling factor, inverse of the step size * @param x Vector with the states @@ -167,6 +174,7 @@ class Model_DAE : public Model { /** * @brief Matrix vector product of JB with a vector v (for iterative *solvers) + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -189,6 +197,7 @@ class Model_DAE : public Model { /** * @brief Event trigger function for events + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -205,6 +214,7 @@ class Model_DAE : public Model { /** * @brief Residual function of the DAE + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -214,6 +224,7 @@ class Model_DAE : public Model { /** * @brief Right hand side of differential equation for adjoint state xB + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -228,6 +239,7 @@ class Model_DAE : public Model { /** * @brief Right hand side of integral equation for quadrature states qB + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -247,6 +259,7 @@ class Model_DAE : public Model { /** * @brief Implementation of fxBdot for steady state case at the N_Vector * level + * * @param t timepoint * @param xB Vector with the adjoint state * @param dxB Vector with the adjoint derivative states @@ -258,6 +271,7 @@ class Model_DAE : public Model { /** * @brief Implementation of fqBdot for steady state at the N_Vector level + * * @param t timepoint * @param xB Vector with the adjoint states * @param dxB Vector with the adjoint derivative states @@ -276,6 +290,7 @@ class Model_DAE : public Model { /** * @brief Computes the sparse backward Jacobian for steadystate integration * and writes it to the model member + * * @param t timepoint * @param cj scalar in Jacobian * @param x Vector with the states @@ -291,6 +306,7 @@ class Model_DAE : public Model { /** * @brief Sensitivity of dx/dt wrt model parameters p + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -309,6 +325,7 @@ class Model_DAE : public Model { /** * @brief Right hand side of differential equation for state sensitivities * sx + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -324,6 +341,7 @@ class Model_DAE : public Model { /** * @brief Mass matrix for DAE systems + * * @param t timepoint * @param x Vector with the states */ @@ -334,6 +352,7 @@ class Model_DAE : public Model { protected: /** * @brief Model specific implementation for fJSparse + * * @param JSparse Matrix to which the Jacobian will be written * @param t timepoint * @param x Vector with the states @@ -353,6 +372,7 @@ class Model_DAE : public Model { /** * @brief Model specific implementation for froot + * * @param root values of the trigger function * @param t timepoint * @param x Vector with the states @@ -370,6 +390,7 @@ class Model_DAE : public Model { /** * @brief Model specific implementation for fxdot + * * @param xdot residual function * @param t timepoint * @param x Vector with the states @@ -387,6 +408,7 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fdxdotdp + * * @param dxdotdp partial derivative xdot wrt p * @param t timepoint * @param x Vector with the states @@ -406,7 +428,6 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fdxdotdp_explicit, no w chainrule - * (Py) * * @param dxdotdp_explicit partial derivative xdot wrt p * @param t timepoint @@ -439,7 +460,6 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fdxdotdx_explicit, no w chainrule - * (Py) * * @param dxdotdx_explicit partial derivative xdot wrt x * @param t timepoint @@ -472,6 +492,7 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fdxdotdw, data part + * * @param dxdotdw partial derivative xdot wrt w * @param t timepoint * @param x Vector with the states @@ -489,18 +510,21 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fdxdotdw, colptrs part + * * @param dxdotdw sparse matrix to which colptrs will be written */ virtual void fdxdotdw_colptrs(SUNMatrixWrapper& dxdotdw); /** * @brief Model specific implementation of fdxdotdw, rowvals part + * * @param dxdotdw sparse matrix to which rowvals will be written */ virtual void fdxdotdw_rowvals(SUNMatrixWrapper& dxdotdw); /** * @brief Sensitivity of dx/dt wrt model parameters w + * * @param t timepoint * @param x Vector with the states * @param dx Vector with the derivative states @@ -509,6 +533,7 @@ class Model_DAE : public Model { /** * @brief Model specific implementation of fM + * * @param M mass matrix * @param t timepoint * @param x Vector with the states diff --git a/include/amici/model_ode.h b/include/amici/model_ode.h index 5dff674169..c6ba3f8034 100644 --- a/include/amici/model_ode.h +++ b/include/amici/model_ode.h @@ -26,6 +26,7 @@ class Model_ODE : public Model { /** * @brief Constructor with model dimensions + * * @param model_dimensions Model dimensions * @param simulation_parameters Simulation parameters * @param o2mode second order sensitivity mode @@ -53,7 +54,8 @@ class Model_ODE : public Model { * * This function provides an * interface to the model specific routines for the solver - * implementation as well as the AmiVector level implementation + * implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param x Vector with the states * @param xdot Vector with the right hand side @@ -67,9 +69,11 @@ class Model_ODE : public Model { SUNMatrix JB) override; /** - * @brief Implementation of fJB at the N_Vector level, this function - *provides an interface to the model specific routines for the solver - *implementation + * @brief Implementation of fJB at the N_Vector level. + * + * This function provides an interface to the model specific routines for + * the solver implementation. + * * @param t timepoint * @param x Vector with the states * @param xB Vector with the adjoint states @@ -86,9 +90,11 @@ class Model_ODE : public Model { ) override; /** - * @brief Implementation of fJSparse at the N_Vector level, this function - * provides an interface to the model specific routines for the solver - * implementation as well as the AmiVector level implementation + * @brief Implementation of fJSparse at the N_Vector level. + * + * This function provides an interface to the model specific routines for + * the solver implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param x Vector with the states * @param J Matrix to which the Jacobian will be written @@ -102,9 +108,11 @@ class Model_ODE : public Model { ) override; /** - * @brief Implementation of fJSparseB at the N_Vector level, this function - * provides an interface to the model specific routines for the solver - * implementation + * @brief Implementation of fJSparseB at the N_Vector level. + * + * This function provides an interface to the model specific routines for + * the solver implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param x Vector with the states * @param xB Vector with the adjoint states @@ -117,9 +125,11 @@ class Model_ODE : public Model { ); /** - * @brief Implementation of fJDiag at the N_Vector level, this function - *provides an interface to the model specific routines for the solver - *implementation + * @brief Implementation of fJDiag at the N_Vector level. + * + * This function provides an interface to the model specific routines for + * the solver implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param JDiag Vector to which the Jacobian diagonal will be written * @param x Vector with the states @@ -128,6 +138,7 @@ class Model_ODE : public Model { /** * @brief Diagonal of the Jacobian (for preconditioning) + * * @param t timepoint * @param JDiag Vector to which the Jacobian diagonal will be written * @param cj scaling factor, inverse of the step size @@ -146,6 +157,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fJv at the N_Vector level. + * * @param t timepoint * @param x Vector with the states * @param v Vector with which the Jacobian is multiplied @@ -156,6 +168,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fJvB at the N_Vector level + * * @param t timepoint * @param x Vector with the states * @param xB Vector with the adjoint states @@ -173,9 +186,11 @@ class Model_ODE : public Model { ) override; /** - * @brief Implementation of froot at the N_Vector level + * @brief Implementation of froot at the N_Vector level. + * * This function provides an interface to the model specific routines for - * the solver implementation as well as the AmiVector level implementation + * the solver implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param x Vector with the states * @param root array with root function values @@ -187,9 +202,11 @@ class Model_ODE : public Model { ) override; /** - * @brief Implementation of fxdot at the N_Vector level, this function - * provides an interface to the model specific routines for the solver - * implementation as well as the AmiVector level implementation + * @brief Implementation of fxdot at the N_Vector level. + * + * This function provides an interface to the model specific routines for + * the solver implementation as well as the AmiVector level implementation. + * * @param t timepoint * @param x Vector with the states * @param xdot Vector with the right hand side @@ -198,6 +215,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fxBdot at the N_Vector level + * * @param t timepoint * @param x Vector with the states * @param xB Vector with the adjoint states @@ -206,7 +224,8 @@ class Model_ODE : public Model { void fxBdot(realtype t, N_Vector x, N_Vector xB, N_Vector xBdot); /** - * @brief Implementation of fqBdot at the N_Vector level + * @brief Implementation of fqBdot at the N_Vector level. + * * @param t timepoint * @param x Vector with the states * @param xB Vector with the adjoint states @@ -222,6 +241,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fxBdot for steady state at the N_Vector level + * * @param t timepoint * @param xB Vector with the states * @param xBdot Vector with the adjoint right hand side @@ -231,6 +251,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fqBdot for steady state case at the N_Vector * level + * * @param t timepoint * @param xB Vector with the adjoint states * @param qBdot Vector with the adjoint quadrature right hand side @@ -239,6 +260,7 @@ class Model_ODE : public Model { /** * @brief Sparse Jacobian function backward, steady state case + * * @param JB sparse matrix to which values of the Jacobian will be written */ void fJSparseB_ss(SUNMatrix JB) override; @@ -246,6 +268,7 @@ class Model_ODE : public Model { /** * @brief Computes the sparse backward Jacobian for steadystate integration * and writes it to the model member + * * @param t timepoint * @param cj scalar in Jacobian * @param x Vector with the states @@ -266,6 +289,7 @@ class Model_ODE : public Model { /** * @brief Implementation of fsxdot at the N_Vector level + * * @param t timepoint * @param x Vector with the states * @param ip parameter index @@ -281,6 +305,7 @@ class Model_ODE : public Model { protected: /** * @brief Model specific implementation for fJSparse, data only + * * @param JSparse Matrix to which the Jacobian will be written * @param t timepoint * @param x Vector with the states @@ -298,18 +323,21 @@ class Model_ODE : public Model { /** * @brief Model specific implementation for fJSparse, column pointers + * * @param JSparse sparse matrix to which colptrs will be written **/ virtual void fJSparse_colptrs(SUNMatrixWrapper& JSparse); /** * @brief Model specific implementation for fJSparse, row values + * * @param JSparse sparse matrix to which rowvals will be written **/ virtual void fJSparse_rowvals(SUNMatrixWrapper& JSparse); /** * @brief Model specific implementation for froot + * * @param root values of the trigger function * @param t timepoint * @param x Vector with the states @@ -327,6 +355,7 @@ class Model_ODE : public Model { /** * @brief Model specific implementation for fxdot + * * @param xdot residual function * @param t timepoint * @param x Vector with the states @@ -343,6 +372,7 @@ class Model_ODE : public Model { /** * @brief Model specific implementation of fdxdotdp_explicit, no w chain * rule + * * @param dxdotdp_explicit partial derivative xdot wrt p * @param t timepoint * @param x Vector with the states @@ -359,12 +389,14 @@ class Model_ODE : public Model { /** * @brief Model specific implementation of fdxdotdp_explicit, colptrs part + * * @param dxdotdp sparse matrix to which colptrs will be written */ virtual void fdxdotdp_explicit_colptrs(SUNMatrixWrapper& dxdotdp); /** * @brief Model specific implementation of fdxdotdp_explicit, rowvals part + * * @param dxdotdp sparse matrix to which rowvals will be written */ virtual void fdxdotdp_explicit_rowvals(SUNMatrixWrapper& dxdotdp); @@ -372,6 +404,7 @@ class Model_ODE : public Model { /** * @brief Model specific implementation of fdxdotdx_explicit, no w chain * rule + * * @param dxdotdx_explicit partial derivative xdot wrt x * @param t timepoint * @param x Vector with the states @@ -388,18 +421,21 @@ class Model_ODE : public Model { /** * @brief Model specific implementation of fdxdotdx_explicit, colptrs part + * * @param dxdotdx sparse matrix to which colptrs will be written */ virtual void fdxdotdx_explicit_colptrs(SUNMatrixWrapper& dxdotdx); /** * @brief Model specific implementation of fdxdotdx_explicit, rowvals part + * * @param dxdotdx sparse matrix to which rowvals will be written */ virtual void fdxdotdx_explicit_rowvals(SUNMatrixWrapper& dxdotdx); /** * @brief Model specific implementation of fdxdotdw, data part + * * @param dxdotdw partial derivative xdot wrt w * @param t timepoint * @param x Vector with the states @@ -415,24 +451,29 @@ class Model_ODE : public Model { /** * @brief Model specific implementation of fdxdotdw, colptrs part + * * @param dxdotdw sparse matrix to which colptrs will be written */ virtual void fdxdotdw_colptrs(SUNMatrixWrapper& dxdotdw); /** * @brief Model specific implementation of fdxdotdw, rowvals part + * * @param dxdotdw sparse matrix to which rowvals will be written */ virtual void fdxdotdw_rowvals(SUNMatrixWrapper& dxdotdw); /** * @brief Sensitivity of dx/dt wrt model parameters w + * * @param t timepoint * @param x Vector with the states */ void fdxdotdw(realtype t, const_N_Vector x); - /** Explicit sensitivity of dx/dt wrt model parameters p + /** + * @brief Explicit sensitivity of dx/dt wrt model parameters p + * * @param t timepoint * @param x Vector with the states */ diff --git a/include/amici/model_state.h b/include/amici/model_state.h index fd45149e46..4e81a9aa37 100644 --- a/include/amici/model_state.h +++ b/include/amici/model_state.h @@ -77,6 +77,7 @@ struct ModelStateDerived { /** * @brief Constructor from model dimensions. + * * @param dim Model dimensions */ explicit ModelStateDerived(ModelDimensions const& dim); @@ -477,6 +478,7 @@ struct SolutionState { /** * @brief Constructor. + * * @param t_ Current timepoint. * @param nx_solver Number of solver state variables. * @param nplist Number of parameter w.r.t. which to compute sensitivities. diff --git a/include/amici/newton_solver.h b/include/amici/newton_solver.h index 1331ae90ae..f1ad226791 100644 --- a/include/amici/newton_solver.h +++ b/include/amici/newton_solver.h @@ -50,6 +50,7 @@ struct DEStateView { /** * @brief Construct a DEStateView from a SolutionState reference. + * * @param sol */ DEStateView(SolutionState& sol) @@ -113,8 +114,8 @@ class NewtonSolver { void prepare_linear_system(Model& model, DEStateView const& state); /** - * Writes the Jacobian (JB) for the Newton iteration and passes it to the - * linear solver + * @brief Writes the Jacobian (JB) for the Newton iteration and passes it to + * the linear solver. * * @param model the model instance * @param state current simulation state diff --git a/include/amici/rdata.h b/include/amici/rdata.h index 28923a6db3..2f200641fc 100644 --- a/include/amici/rdata.h +++ b/include/amici/rdata.h @@ -41,6 +41,7 @@ class ReturnData : public ModelDimensions { /** * @brief Constructor + * * @param ts_ see amici::SimulationParameters::ts * @param model_dimensions_ Model dimensions * @param nmaxevent_ see amici::ModelDimensions::nmaxevent @@ -69,6 +70,7 @@ class ReturnData : public ModelDimensions { /** * @brief constructor that uses information from model and solver to * appropriately initialize fields + * * @param solver solver instance * @param model model instance */ @@ -79,6 +81,7 @@ class ReturnData : public ModelDimensions { /** * @brief constructor that uses information from model and solver to * appropriately initialize fields + * * @param fwd simulated forward problem, pass `nullptr` to ignore * @param bwd simulated backward problem, pass `nullptr` to ignore * @param model matching model instance @@ -497,6 +500,7 @@ class ReturnData : public ModelDimensions { /** * @brief Serialize ReturnData (see boost::serialization::serialize) + * * @param ar Archive to serialize to * @param r Data to serialize * @param version Version number @@ -536,6 +540,7 @@ class ReturnData : public ModelDimensions { /** * @brief initializes storage for likelihood reporting mode + * * @param quadratic_llh whether model defines a quadratic nllh and computing * res, sres and FIM makes sense. */ @@ -543,6 +548,7 @@ class ReturnData : public ModelDimensions { /** * @brief initializes storage for observables + likelihood reporting mode + * * @param quadratic_llh whether model defines a quadratic nllh and computing * res, sres and FIM makes sense. */ @@ -550,24 +556,28 @@ class ReturnData : public ModelDimensions { /** * @brief initializes storage for residual reporting mode + * * @param enable_res whether residuals are to be computed */ void initialize_residual_reporting(bool enable_res); /** * @brief initializes storage for full reporting mode + * * @param enable_fim whether FIM Hessian approximation is to be computed */ void initialize_full_reporting(bool enable_fim); /** * @brief initialize values for chi2 and llh and derivatives + * * @param enable_chi2 whether chi2 values are to be computed */ void initialize_objective_function(bool enable_chi2); /** * @brief extracts data from a pre-equilibration SteadystateProblem + * * @param preeq SteadystateProblem for pre-equilibration * @param preeq_bwd SteadyStateBackwardProblem from pre-equilibration * @param model Model instance to compute return values @@ -579,6 +589,7 @@ class ReturnData : public ModelDimensions { /** * @brief extracts data from a post-equilibration SteadystateProblem + * * @param posteq SteadystateProblem for post-equilibration * @param posteq_bwd SteadyStateBackwardProblem from post-equilibration * @param model Model instance to compute return values @@ -592,6 +603,7 @@ class ReturnData : public ModelDimensions { /** * @brief extracts results from forward problem + * * @param fwd forward problem * @param model model that was used for forward simulation * @param edata ExpData instance containing observable data @@ -602,6 +614,7 @@ class ReturnData : public ModelDimensions { /** * @brief extracts results from backward problem + * * @param fwd forward problem * @param bwd backward problem * @param preeq SteadyStateProblem for preequilibration @@ -616,6 +629,7 @@ class ReturnData : public ModelDimensions { /** * @brief extracts results from solver + * * @param solver solver that was used for forward/backward simulation */ void process_solver(Solver const& solver); @@ -623,6 +637,7 @@ class ReturnData : public ModelDimensions { /** * @brief Evaluates and stores the Jacobian and right hand side at final * timepoint + * * @param problem forward problem or steadystate problem * @param model model that was used for forward/backward simulation */ @@ -652,6 +667,7 @@ class ReturnData : public ModelDimensions { /** * @brief Residual function + * * @param it time index * @param model model that was used for forward/backward simulation * @param sol Solution state the timepoint `it` @@ -662,6 +678,7 @@ class ReturnData : public ModelDimensions { /** * @brief Chi-squared function + * * @param it time index * @param edata ExpData instance containing observable data */ @@ -669,6 +686,7 @@ class ReturnData : public ModelDimensions { /** * @brief Residual sensitivity function + * * @param it time index * @param model model that was used for forward/backward simulation * @param sol solution state the timepoint `it` @@ -679,6 +697,7 @@ class ReturnData : public ModelDimensions { /** * @brief Fisher information matrix function + * * @param it time index * @param model model that was used for forward/backward simulation * @param sol Solution state the timepoint `it` @@ -690,6 +709,7 @@ class ReturnData : public ModelDimensions { /** * @brief Set likelihood, state variables, outputs and respective * sensitivities to NaN (typically after integration failure) + * * @param it_start time index at which to start invalidating */ void invalidate(int it_start); @@ -709,12 +729,14 @@ class ReturnData : public ModelDimensions { /** * @brief applies the chain rule to account for parameter transformation in * the sensitivities of simulation results + * * @param model Model from which the ReturnData was obtained */ void apply_chain_rule_factor_to_simulation_results(Model const& model); /** * @brief Checks whether forward sensitivity analysis is performed + * * @return boolean indicator */ [[nodiscard]] bool computing_fsa() const { @@ -727,6 +749,7 @@ class ReturnData : public ModelDimensions { /** * @brief Extracts output information for data-points, expects that * the model state was set appropriately + * * @param it timepoint index * @param model model that was used in forward solve * @param sol solution state the timepoint `it` @@ -739,6 +762,7 @@ class ReturnData : public ModelDimensions { /** * @brief Extracts data information for forward sensitivity analysis, * expects that the model state was set appropriately + * * @param it index of current timepoint * @param model model that was used in forward solve * @param sol Solution state the timepoint `it` @@ -751,6 +775,7 @@ class ReturnData : public ModelDimensions { /** * @brief Extracts output information for events, expects that the model * state was set appropriately + * * @param rootidx information about which roots fired * (1 indicating fired, 0/-1 for not) * @param model model that was used in forward solve @@ -765,6 +790,7 @@ class ReturnData : public ModelDimensions { /** * @brief Extracts event information for forward sensitivity analysis, * expects the model state was set appropriately + * * @param ie index of event type * @param model model that was used in forward solve * @param sol Solution state the timepoint `it` @@ -777,6 +803,7 @@ class ReturnData : public ModelDimensions { /** * @brief Updates contribution to likelihood from quadratures (xQB), * if preequilibration was run in adjoint mode + * * @param model model that was used for forward/backward simulation * @param sx0 State sensitivities at pre-equilibration steady state * @param xB Adjoint state from pre-equilibration. @@ -792,6 +819,7 @@ class ReturnData : public ModelDimensions { * @brief Updates contribution to likelihood for initial state sensitivities * (llhS0), if no preequilibration was run or if forward sensitivities were * used + * * @param model model that was used for forward/backward simulation * @param sol Solution state the timepoint `it` * @param llhS0 contribution to likelihood for initial state sensitivities diff --git a/include/amici/serialization.h b/include/amici/serialization.h index d441fd1597..7ac3a9b42e 100644 --- a/include/amici/serialization.h +++ b/include/amici/serialization.h @@ -31,6 +31,7 @@ namespace serialization { /** * @brief Serialize a raw array to a boost archive + * * @param ar archive * @param p Pointer to array * @param size Size of p @@ -52,6 +53,7 @@ void archive_vector(Archive& ar, T** p, int size) { #ifndef EXHALE_DOXYGEN_SHOULD_SKIP_THIS /** * @brief Serialize amici::Solver to boost archive + * * @param ar Archive * @param s Solver instance to serialize */ @@ -99,6 +101,7 @@ void serialize(Archive& ar, amici::Solver& s, unsigned int const /*version*/) { /** * @brief Serialize std::chrono::duration to boost archive + * * @param ar Archive * @param d Duration */ @@ -119,6 +122,7 @@ void serialize( /** * @brief Serialize amici::CVodeSolver to boost archive + * * @param ar Archive * @param s Solver instance to serialize */ @@ -131,6 +135,7 @@ void serialize( /** * @brief Serialize amici::Model to boost archive + * * @param ar Archive * @param m Model instance to serialize */ @@ -159,6 +164,7 @@ void serialize(Archive& ar, amici::Model& m, unsigned int const /*version*/) { /** * @brief Serialize amici::SimulationParameters to boost archive + * * @param ar Archive * @param s amici::SimulationParameters instance to serialize */ @@ -198,6 +204,7 @@ void serialize( /** * @brief Serialize amici::ReturnData to boost archive + * * @param ar Archive * @param r ReturnData instance to serialize */ @@ -268,6 +275,7 @@ void serialize( /** * @brief Serialize amici::ModelDimensions to boost archive + * * @param ar Archive * @param m ModelDimensions instance to serialize */ diff --git a/include/amici/simulation_parameters.h b/include/amici/simulation_parameters.h index 01fc4fced4..ba5090a731 100644 --- a/include/amici/simulation_parameters.h +++ b/include/amici/simulation_parameters.h @@ -16,6 +16,7 @@ class SimulationParameters { /** * @brief Constructor + * * @param timepoints Timepoints for which simulation results are requested */ explicit SimulationParameters(std::vector timepoints) @@ -23,6 +24,7 @@ class SimulationParameters { /** * @brief Constructor + * * @param fixed_parameters Model parameters excluded from sensitivity * analysis * @param free_parameters Model parameters included in sensitivity analysis @@ -52,6 +54,7 @@ class SimulationParameters { */ /** * @brief Constructor + * * @param fixed_parameters Model parameters excluded from sensitivity * analysis * @param free_parameters Model parameters included in sensitivity analysis @@ -71,6 +74,7 @@ class SimulationParameters { /** * @brief Constructor + * * @param timepoints Timepoints for which simulation results are requested * @param fixed_parameters Model parameters excluded from sensitivity * analysis diff --git a/include/amici/solver.h b/include/amici/solver.h index 6b52a0766f..c7671a5d4b 100644 --- a/include/amici/solver.h +++ b/include/amici/solver.h @@ -57,6 +57,7 @@ class Solver { /** * @brief Solver copy constructor + * * @param other */ Solver(Solver const& other); @@ -65,18 +66,21 @@ class Solver { /** * @brief Clone this instance + * * @return The clone */ virtual Solver* clone() const = 0; /** * @brief Get SUNDIALS context + * * @return context */ SUNContext get_sun_context() const; /** * @brief Get the name of this class. + * * @return Class name. */ virtual std::string get_class_name() const = 0; @@ -106,6 +110,7 @@ class Solver { /** * @brief Initializes the ami memory object and applies specified options + * * @param t0 initial timepoint * @param model pointer to the model instance * @param x0 initial states @@ -121,6 +126,7 @@ class Solver { /** * @brief Initializes the AMI memory object for the backwards problem + * * @param which index of the backward problem, will be set by this routine * @param tf final timepoint (initial timepoint for the bwd problem) * @param model pointer to the model instance @@ -136,6 +142,7 @@ class Solver { /** * @brief Initializes the ami memory for quadrature computation + * * @param t0 initial timepoint * @param model pointer to the model instance * @param x0 initial states @@ -159,7 +166,7 @@ class Solver { void update_and_reinit_states_and_sensitivities(Model* model) const; /** - * get_root_info extracts information which event occurred + * @brief Extract information which event occurred. * * @param rootsfound array with flags indicating whether the respective * event occurred @@ -199,24 +206,28 @@ class Solver { /** * @brief Return current sensitivity method + * * @return method enum */ SensitivityMethod get_sensitivity_method() const; /** * @brief Set sensitivity method + * * @param sensi_meth */ void set_sensitivity_method(SensitivityMethod sensi_meth); /** * @brief Return current sensitivity method during preequilibration + * * @return method enum */ SensitivityMethod get_sensitivity_method_pre_equilibration() const; /** * @brief Set sensitivity method for preequilibration + * * @param sensi_meth_preeq */ void set_sensitivity_method_pre_equilibration( @@ -231,6 +242,7 @@ class Solver { /** * @brief Get maximum number of allowed Newton steps for steady state * computation + * * @return */ int get_newton_max_steps() const; @@ -238,18 +250,21 @@ class Solver { /** * @brief Set maximum number of allowed Newton steps for steady state * computation + * * @param newton_maxsteps */ void set_newton_max_steps(int newton_maxsteps); /** * @brief Get a state of the damping factor used in the Newton solver + * * @return */ NewtonDampingFactorMode get_newton_damping_factor_mode() const; /** * @brief Turn on/off a damping factor in the Newton method + * * @param dampingFactorMode */ void @@ -257,24 +272,28 @@ class Solver { /** * @brief Get a lower bound of the damping factor used in the Newton solver + * * @return */ double get_newton_damping_factor_lower_bound() const; /** * @brief Set a lower bound of the damping factor in the Newton solver + * * @param dampingFactorLowerBound */ void set_newton_damping_factor_lower_bound(double dampingFactorLowerBound); /** * @brief Get sensitivity order + * * @return sensitivity order */ SensitivityOrder get_sensitivity_order() const; /** * @brief Set the sensitivity order + * * @param sensi sensitivity order */ void set_sensitivity_order(SensitivityOrder sensi); @@ -322,12 +341,14 @@ class Solver { /** * @brief Returns the relative tolerances for the forward sensitivity * problem + * * @return relative tolerances */ double get_relative_tolerance_fsa() const; /** * @brief Sets the relative tolerances for the forward sensitivity problem + * * @param rtol relative tolerance (non-negative number) */ void set_relative_tolerance_fsa(double rtol); @@ -335,12 +356,14 @@ class Solver { /** * @brief Returns the absolute tolerances for the forward sensitivity * problem + * * @return absolute tolerances */ double get_absolute_tolerance_fsa() const; /** * @brief Sets the absolute tolerances for the forward sensitivity problem + * * @param atol absolute tolerance (non-negative number) */ void set_absolute_tolerance_fsa(double atol); @@ -348,12 +371,14 @@ class Solver { /** * @brief Returns the relative tolerances for the adjoint sensitivity * problem + * * @return relative tolerances */ double get_relative_tolerance_b() const; /** * @brief Sets the relative tolerances for the adjoint sensitivity problem + * * @param rtol relative tolerance (non-negative number) */ void set_relative_tolerance_b(double rtol); @@ -361,6 +386,7 @@ class Solver { /** * @brief Returns the absolute tolerances for the backward problem for * adjoint sensitivity analysis + * * @return absolute tolerances */ double get_absolute_tolerance_b() const; @@ -368,30 +394,35 @@ class Solver { /** * @brief Sets the absolute tolerances for the backward problem for * adjoint sensitivity analysis + * * @param atol absolute tolerance (non-negative number) */ void set_absolute_tolerance_b(double atol); /** * @brief Returns the relative tolerance for the quadrature problem + * * @return relative tolerance */ double get_relative_tolerance_quadratures() const; /** * @brief sets the relative tolerance for the quadrature problem + * * @param rtol relative tolerance (non-negative number) */ void set_relative_tolerance_quadratures(double rtol); /** * @brief returns the absolute tolerance for the quadrature problem + * * @return absolute tolerance */ double get_absolute_tolerance_quadratures() const; /** * @brief sets the absolute tolerance for the quadrature problem + * * @param atol absolute tolerance (non-negative number) */ void set_absolute_tolerance_quadratures(double atol); @@ -402,6 +433,7 @@ class Solver { * Steady state simulation tolerances are the product of the simulation * tolerances and this factor, unless manually set with * `set(Absolute/Relative)ToleranceSteadyState()`. + * * @return steady state simulation tolerance factor */ double get_steady_state_tolerance_factor() const; @@ -412,30 +444,35 @@ class Solver { * Steady state simulation tolerances are the product of the simulation * tolerances and this factor, unless manually set with * `set(Absolute/Relative)ToleranceSteadyState()`. + * * @param factor tolerance factor (non-negative number) */ void set_steady_state_tolerance_factor(double factor); /** * @brief returns the relative tolerance for the steady state problem + * * @return relative tolerance */ double get_relative_tolerance_steady_state() const; /** * @brief sets the relative tolerance for the steady state problem + * * @param rtol relative tolerance (non-negative number) */ void set_relative_tolerance_steady_state(double rtol); /** * @brief returns the absolute tolerance for the steady state problem + * * @return absolute tolerance */ double get_absolute_tolerance_steady_state() const; /** * @brief sets the absolute tolerance for the steady state problem + * * @param atol absolute tolerance (non-negative number) */ void set_absolute_tolerance_steady_state(double atol); @@ -446,6 +483,7 @@ class Solver { * Steady state sensitivity simulation tolerances are the product of the * sensitivity simulation tolerances and this factor, unless manually set * with `set(Absolute/Relative)ToleranceSteadyStateSensi()`. + * * @return steady state simulation tolerance factor */ double get_steady_state_sensi_tolerance_factor() const; @@ -456,6 +494,7 @@ class Solver { * Steady state sensitivity simulation tolerances are the product of the * sensitivity simulation tolerances and this factor, unless manually set * with `set(Absolute/Relative)ToleranceSteadyStateSensi()`. + * * @param factor tolerance factor (non-negative number) */ void set_steady_state_sensi_tolerance_factor(double factor); @@ -463,6 +502,7 @@ class Solver { /** * @brief returns the relative tolerance for the sensitivities of the * steady state problem + * * @return relative tolerance */ double get_relative_tolerance_steady_state_sensi() const; @@ -477,6 +517,7 @@ class Solver { /** * @brief returns the absolute tolerance for the sensitivities of the * steady state problem + * * @return absolute tolerance */ double get_absolute_tolerance_steady_state_sensi() const; @@ -484,6 +525,7 @@ class Solver { /** * @brief sets the absolute tolerance for the sensitivities of the * steady state problem + * * @param atol absolute tolerance (non-negative number) */ void set_absolute_tolerance_steady_state_sensi(double atol); @@ -491,24 +533,28 @@ class Solver { /** * @brief returns the maximum number of solver steps for the forward * problem + * * @return maximum number of solver steps */ long int get_max_steps() const; /** * @brief sets the maximum number of solver steps for the forward problem + * * @param maxsteps maximum number of solver steps (positive number) */ void set_max_steps(long int maxsteps); /** * @brief Returns the maximum time allowed for integration + * * @return Time in seconds */ double get_max_time() const; /** * @brief Set the maximum CPU time allowed for integration + * * @param maxtime Time in seconds. Zero means infinite time. */ void set_max_time(double maxtime); @@ -520,6 +566,7 @@ class Solver { /** * @brief Check whether maximum integration time was exceeded + * * @param interval Only check the time every ``interval`` ths call to avoid * potentially relatively expensive syscalls @@ -531,6 +578,7 @@ class Solver { /** * @brief returns the maximum number of solver steps for the backward * problem + * * @return maximum number of solver steps */ long int get_max_steps_backward_problem() const; @@ -547,30 +595,35 @@ class Solver { /** * @brief returns the linear system multistep method + * * @return linear system multistep method */ LinearMultistepMethod get_linear_multistep_method() const; /** * @brief sets the linear system multistep method + * * @param lmm linear system multistep method */ void set_linear_multistep_method(LinearMultistepMethod lmm); /** * @brief returns the nonlinear system solution method + * * @return */ NonlinearSolverIteration get_non_linear_solver_iteration() const; /** * @brief sets the nonlinear system solution method + * * @param iter nonlinear system solution method */ void set_non_linear_solver_iteration(NonlinearSolverIteration iter); /** * @brief get_interpolation_type + * * @return */ InterpolationType get_interpolation_type() const; @@ -578,6 +631,7 @@ class Solver { /** * @brief sets the interpolation of the forward solution that is used for * the backwards problem + * * @param interpType interpolation type */ void set_interpolation_type(InterpolationType interpType); @@ -597,60 +651,70 @@ class Solver { * This only applies when linsol is set to LinearSolver::KLU or * LinearSolver::SuperLUMT. Mind the difference between * SUNLinSolKLU::StateOrdering and SUNLinSolSuperLUMT::StateOrdering. + * * @param ordering state ordering */ void set_state_ordering(int ordering); /** * @brief returns stability limit detection mode + * * @return stldet can be false (deactivated) or true (activated) */ bool get_stability_limit_flag() const; /** * @brief set stability limit detection mode + * * @param stldet can be false (deactivated) or true (activated) */ void set_stability_limit_flag(bool stldet); /** * @brief get_linear_solver + * * @return */ LinearSolver get_linear_solver() const; /** * @brief set_linear_solver + * * @param linsol */ void set_linear_solver(LinearSolver linsol); /** * @brief returns the internal sensitivity method + * * @return internal sensitivity method */ InternalSensitivityMethod get_internal_sensitivity_method() const; /** * @brief sets the internal sensitivity method + * * @param ism internal sensitivity method */ void set_internal_sensitivity_method(InternalSensitivityMethod ism); /** * @brief returns the ReturnData reporting mode + * * @return ReturnData reporting mode */ RDataReporting get_return_data_reporting_mode() const; /** * @brief sets the ReturnData reporting mode + * * @param rdrm ReturnData reporting mode */ void set_return_data_reporting_mode(RDataReporting rdrm); /** * @brief write solution from forward simulation + * * @param t time * @param x state * @param dx derivative state @@ -664,6 +728,7 @@ class Solver { /** * @brief write solution from forward simulation + * * @param t time * @param x state * @param dx derivative state @@ -675,12 +740,14 @@ class Solver { /** * @brief write solution from forward simulation + * * @param sol solution state */ void write_solution(SolutionState& sol) const; /** * @brief write solution from forward simulation + * * @param t Time for which to retrieve the solution * (interpolated if necessary). Must be greater than or equal to * the initial timepoint and less than or equal to the current timepoint. @@ -690,6 +757,7 @@ class Solver { /** * @brief write solution from backward simulation + * * @param t time * @param xB adjoint state * @param dxB adjoint derivative state @@ -702,6 +770,7 @@ class Solver { /** * @brief Access state solution at time t + * * @param t time * @return x or interpolated solution dky */ @@ -709,6 +778,7 @@ class Solver { /** * @brief Access derivative state solution at time t + * * @param t time * @return dx or interpolated solution dky */ @@ -716,6 +786,7 @@ class Solver { /** * @brief Access state sensitivity solution at time t + * * @param t time * @return (interpolated) solution sx */ @@ -723,6 +794,7 @@ class Solver { /** * @brief Access adjoint solution at time t + * * @param which adjoint problem index * @param t time * @return (interpolated) solution xB @@ -731,6 +803,7 @@ class Solver { /** * @brief Access adjoint derivative solution at time t + * * @param which adjoint problem index * @param t time * @return (interpolated) solution dxB @@ -739,6 +812,7 @@ class Solver { /** * @brief Access adjoint quadrature solution at time t + * * @param which adjoint problem index * @param t time * @return (interpolated) solution xQB @@ -747,6 +821,7 @@ class Solver { /** * @brief Access quadrature solution at time t + * * @param t time * @return (interpolated) solution xQ */ @@ -803,42 +878,49 @@ class Solver { /** * @brief current solver timepoint + * * @return t */ realtype get_t() const; /** * @brief Reads out the CPU time needed for forward solve + * * @return cpu_time */ realtype get_cpu_time() const; /** * @brief Reads out the CPU time needed for backward solve + * * @return cpu_timeB */ realtype get_cpu_time_b() const; /** - * @brief number of states with which the solver was initialized + * @brief number of state variables with which the solver was initialized + * * @return x.getLength() */ int nx() const; /** * @brief number of parameters with which the solver was initialized + * * @return sx.getLength() */ int nplist() const; /** * @brief number of quadratures with which the solver was initialized + * * @return xQB.getLength() */ int nquad() const; /** * @brief check if FSA is being computed + * * @return flag */ bool computing_fsa() const { @@ -849,6 +931,7 @@ class Solver { /** * @brief check if ASA is being computed + * * @return flag */ bool computing_asa() const { @@ -878,42 +961,49 @@ class Solver { /** * @brief Accessor ns + * * @return ns */ std::vector const& get_num_steps() const { return ns_; } /** * @brief Accessor nsB + * * @return nsB */ std::vector const& get_num_steps_b() const { return nsB_; } /** * @brief Accessor nrhs + * * @return nrhs */ std::vector const& get_num_rhs_evals() const { return nrhs_; } /** * @brief Accessor nrhsB + * * @return nrhsB */ std::vector const& get_num_rhs_evals_b() const { return nrhsB_; } /** * @brief Accessor netf + * * @return netf */ std::vector const& get_num_err_test_fails() const { return netf_; } /** * @brief Accessor netfB + * * @return netfB */ std::vector const& get_num_err_test_fails_b() const { return netfB_; } /** * @brief Accessor nnlscf + * * @return nnlscf */ std::vector const& get_num_non_lin_solv_conv_fails() const { @@ -922,6 +1012,7 @@ class Solver { /** * @brief Accessor nnlscfB + * * @return nnlscfB */ std::vector const& get_num_non_lin_solv_conv_fails_b() const { @@ -930,14 +1021,18 @@ class Solver { /** * @brief Accessor order + * * @return order */ std::vector const& get_last_order() const { return order_; } /** * @brief Returns how convergence checks for steadystate computation are - * performed. If activated, convergence checks are limited to every 25 steps + * performed. + * + * If activated, convergence checks are limited to every 25 steps * in the simulation solver to limit performance impact. + * * @return boolean flag indicating newton step (true) or the right hand side * (false) */ @@ -948,6 +1043,7 @@ class Solver { /** * @brief Returns how convergence checks for steadystate computation are * performed. + * * @return boolean flag indicating state and sensitivity equations (true) or * only state variables (false). */ @@ -958,6 +1054,7 @@ class Solver { /** * @brief Sets how convergence checks for steadystate computation are * performed. + * * @param flag boolean flag to pick newton step (true) or the right hand * side (false, default) */ @@ -968,6 +1065,7 @@ class Solver { /** * @brief Sets for which variables convergence checks for steadystate * computation are performed. + * * @param flag boolean flag to pick state and sensitivity equations (true, * default) or only state variables (false). */ @@ -978,6 +1076,7 @@ class Solver { /** * @brief Set the maximum number of nonlinear solver iterations permitted * per step. + * * @param max_nonlin_iters maximum number of nonlinear solver iterations */ void set_max_nonlin_iters(int max_nonlin_iters); @@ -985,6 +1084,7 @@ class Solver { /** * @brief Get the maximum number of nonlinear solver iterations permitted * per step. + * * @return maximum number of nonlinear solver iterations */ int get_max_nonlin_iters() const; @@ -992,6 +1092,7 @@ class Solver { /** * @brief Set the maximum number of nonlinear solver convergence failures * permitted per step. + * * @param max_conv_fails maximum number of nonlinear solver convergence */ void set_max_conv_fails(int max_conv_fails); @@ -999,6 +1100,7 @@ class Solver { /** * @brief Get the maximum number of nonlinear solver convergence failures * permitted per step. + * * @return maximum number of nonlinear solver convergence */ int get_max_conv_fails() const; @@ -1015,6 +1117,7 @@ class Solver { /** * @brief Get constraints on the model state. + * * @return constraints */ std::vector get_constraints() const { @@ -1023,18 +1126,21 @@ class Solver { /** * @brief Set the maximum step size + * * @param max_step_size maximum step size. `0.0` means no limit. */ void set_max_step_size(realtype max_step_size); /** * @brief Get the maximum step size + * * @return maximum step size */ realtype get_max_step_size() const; /** * @brief Serialize Solver (see boost::serialization::serialize) + * * @param ar Archive to serialize to * @param s Data to serialize * @param version Version number @@ -1046,6 +1152,7 @@ class Solver { /** * @brief Check equality of data members excluding solver memory + * * @param a * @param b * @return @@ -1054,12 +1161,14 @@ class Solver { /** * @brief Get the logger. + * * @return Logger pointer or nullptr. */ Logger* get_logger() const { return logger_; } /** * @brief Set the logger. + * * @param logger Logger pointer or nullptr. */ void set_logger(Logger* logger) { logger_ = logger; } @@ -1096,6 +1205,7 @@ class Solver { /** * @brief reinit_post_process_f postprocessing of the solver memory after a * discontinuity in the forward problem + * * @param tnext next timepoint (defines integration direction) */ virtual void reinit_post_process_f(realtype tnext) const = 0; @@ -1103,6 +1213,7 @@ class Solver { /** * @brief reinit_post_process_b postprocessing of the solver memory after a * discontinuity in the backward problem + * * @param tnext next timepoint (defines integration direction) */ virtual void reinit_post_process_b(realtype tnext) const = 0; @@ -1116,6 +1227,7 @@ class Solver { /** * @brief extracts the adjoint state at the current timepoint from * solver memory and writes it to the xB member variable + * * @param which index of the backwards problem */ virtual void get_b(int which) const = 0; @@ -1123,6 +1235,7 @@ class Solver { /** * @brief extracts the adjoint quadrature state at the current timepoint * from solver memory and writes it to the xQB member variable + * * @param which index of the backwards problem */ virtual void get_quad_b(int which) const = 0; @@ -1160,6 +1273,7 @@ class Solver { /** * @brief Initializes the forward sensitivities + * * @param sx0 initial states sensitivities * @param sdx0 initial derivative states sensitivities */ @@ -1197,6 +1311,7 @@ class Solver { /** * @brief Initialize non-linear solver for sensitivities + * * @param model Model instance */ void initialize_non_linear_solver_sens(Model const* model) const; @@ -1280,7 +1395,7 @@ class Solver { = 0; /** - * SetSensErrCon specifies whether error control is also enforced for + * @brief Set whether error control is also enforced for * sensitivities for the forward problem * * @param error_corr activation flag @@ -1441,7 +1556,7 @@ class Solver { virtual void adj_init() const = 0; /** - * @brief initializes the quadratures + * @brief initializes the quadratures# * @param xQ0 vector with initial values for xQ */ virtual void quad_init(AmiVector const& xQ0) const = 0; @@ -1560,6 +1675,7 @@ class Solver { /** * @brief Sets the linear solver for the backward problem + * * @param which index of the backward problem */ virtual void set_linear_solver_b(int which) const = 0; @@ -1571,6 +1687,7 @@ class Solver { /** * @brief Set the non-linear solver for the backward problem + * * @param which index of the backward problem */ virtual void set_non_linear_solver_b(int which) const = 0; @@ -1591,12 +1708,13 @@ class Solver { /** * @brief Initializes the non-linear solver for the backward problem + * * @param which index of the backward problem */ void initialize_non_linear_solver_b(int which) const; /** - * Accessor function to the model stored in the user data + * @brief Accessor function to the model stored in the user data * * @return user data model */ @@ -1625,6 +1743,7 @@ class Solver { /** * @brief checks whether memory for the backward problem has been allocated + * * @param which adjoint problem index * @return proxy for solverMemoryB->(cv|ida)_MallocDone */ @@ -1632,6 +1751,7 @@ class Solver { /** * @brief checks whether memory for backward quadratures has been allocated + * * @param which adjoint problem index * @return proxy for solverMemoryB->(cv|ida)_QuadMallocDone */ @@ -1639,6 +1759,7 @@ class Solver { /** * @brief checks whether memory for quadratures has been allocated + * * @return proxy for solverMemory->(cv|ida)_QuadMallocDone */ bool get_quad_init_done() const; @@ -1657,6 +1778,7 @@ class Solver { /** * @brief resets solverMemory and solverMemoryB + * * @param nx new number of state variables * @param nplist new number of sensitivity parameters * @param nquad new number of quadratures (only differs from nplist for @@ -1797,12 +1919,14 @@ class Solver { /** * @brief sets that memory for the backward problem has been allocated + * * @param which adjoint problem index */ void set_init_done_b(int which) const; /** * @brief sets that memory for backward quadratures has been allocated + * * @param which adjoint problem index */ void set_quad_init_done_b(int which) const; @@ -1814,6 +1938,7 @@ class Solver { /** * @brief Sets sensitivity method (for simulation or preequilibration) + * * @param sensi_meth new value for sensi_meth[_preeq] * @param preequilibration flag indicating preequilibration or simulation */ diff --git a/include/amici/solver_cvodes.h b/include/amici/solver_cvodes.h index c6ff6b967c..b22d10be78 100644 --- a/include/amici/solver_cvodes.h +++ b/include/amici/solver_cvodes.h @@ -34,6 +34,7 @@ class CVodeSolver : public Solver { /** * @brief Clone this instance + * * @return The clone */ Solver* clone() const override; @@ -114,6 +115,7 @@ class CVodeSolver : public Solver { /** * @brief Post-processing of the solver memory after a discontinuity + * * @param cv_mem pointer to CVODES solver memory object * @param t pointer to integration time * @param yout new state vector @@ -152,6 +154,7 @@ class CVodeSolver : public Solver { /** * @brief reset_state reset the CVODES solver to restart integration after a * rhs discontinuity. + * * @param cv_mem pointer to CVODES solver memory object * @param y0 new state vector */ @@ -203,6 +206,7 @@ class CVodeSolver : public Solver { /** * @brief Serialize amici::CVodeSolver to boost archive + * * @param ar Archive * @param s Solver instance to serialize */ @@ -212,6 +216,7 @@ class CVodeSolver : public Solver { /** * @brief Equality operator + * * @param a * @param b * @return Whether a and b are equal diff --git a/include/amici/solver_idas.h b/include/amici/solver_idas.h index d9febe9620..d6b09e7d0c 100644 --- a/include/amici/solver_idas.h +++ b/include/amici/solver_idas.h @@ -31,6 +31,7 @@ class IDASolver : public Solver { /** * @brief Clone this instance + * * @return The clone */ Solver* clone() const override; @@ -112,6 +113,7 @@ class IDASolver : public Solver { protected: /** * @brief Postprocessing of the solver memory after a discontinuity + * * @param ida_mem pointer to IDAS solver memory object * @param t pointer to integration time * @param yout new state vector @@ -153,6 +155,7 @@ class IDASolver : public Solver { /** * @brief reset_state reset the IDAS solver to restart integration after a * rhs discontinuity. + * * @param ida_mem pointer to IDAS solver memory object * @param yy0 new state vector * @param yp0 new state derivative vector diff --git a/include/amici/splinefunctions.h b/include/amici/splinefunctions.h index 9ae5537c03..86005aa1f8 100644 --- a/include/amici/splinefunctions.h +++ b/include/amici/splinefunctions.h @@ -25,6 +25,7 @@ class AbstractSpline { /** * @brief Common constructor for `AbstractSpline` instances. + * * @param nodes the nodes defining the position at which the value of * the spline is known * (if `equidistant_spacing` is true, it must contain only the first and @@ -52,6 +53,7 @@ class AbstractSpline { /** * @brief Compute the coefficients for all polynomial segments of * the derivatives of this spline with respect to the parameters + * * @param nplist number of parameters * @param spline_offset offset of this spline inside `dvaluesdp` * and `dslopesdp` @@ -69,6 +71,7 @@ class AbstractSpline { /** * @brief Get the value of this spline at a given point + * * @param t point at which the spline is to be evaluated * @return value of the spline at `t` */ @@ -77,6 +80,7 @@ class AbstractSpline { /** * @brief Get the value of this spline at a given point * in the scale in which interpolation is carried out (e.g., log-scale) + * * @param t point at which the spline is to be evaluated * @return scaled value of the spline at `t` */ @@ -84,6 +88,7 @@ class AbstractSpline { /** * @brief Get the value of this spline at a given node + * * @param i index of the node at which the spline is to be evaluated * @return value of the spline at the `i`-th node */ @@ -100,6 +105,7 @@ class AbstractSpline { /** * @brief Get the derivative of this spline with respect to a given * parameter at a given point + * * @param t point at which the sensitivity is to be evaluated * @param ip index of the parameter * @return sensitivity of the spline with respect to the `ip`th parameter @@ -110,6 +116,7 @@ class AbstractSpline { /** * @brief Get the derivative of this spline with respect to a given * parameter at a given point + * * @param t point at which the sensitivity is to be evaluated * @param ip index of the parameter * @param value value of the spline at the given time point. @@ -125,6 +132,7 @@ class AbstractSpline { * @brief Get the derivative of this spline with respect to a given * parameter at a given point * in the scale in which interpolation is carried out (e.g., log-scale) + * * @param t point at which the sensitivity is to be evaluated * @param ip index of the parameter * @return scaled sensitivity of the spline with respect to the `ip`th @@ -143,6 +151,7 @@ class AbstractSpline { /** * @brief Compute the limit of the value of the sensitivity * as the evaluation point tends to positive infinity. + * * @param nplist number of parameters * @param spline_offset offset of this spline inside `dspline_valuesdp` * and `dspline_slopesdp` @@ -160,6 +169,7 @@ class AbstractSpline { /** * @brief Get the limit value of the spline * as the evaluation point tends to positive infinity. + * * @return limit value */ [[nodiscard]] realtype get_final_value() const; @@ -168,6 +178,7 @@ class AbstractSpline { * @brief Get the limit value of the spline * (in the scale in which interpolation is carried out) * as the evaluation point tends to positive infinity. + * * @return limit value */ [[nodiscard]] realtype get_final_value_scaled() const; @@ -176,6 +187,7 @@ class AbstractSpline { * @brief Get the limit value of the sensitivity * with respect to the given parameter * as the evaluation point tends to positive infinity. + * * @param ip parameter index * @return limit value */ @@ -186,6 +198,7 @@ class AbstractSpline { * with respect to the given parameter * (in the scale in which interpolation is carried out) * as the evaluation point tends to positive infinity. + * * @param ip parameter index * @return limit value */ @@ -193,18 +206,21 @@ class AbstractSpline { /** * @brief Whether nodes are uniformly spaced + * * @return boolean flag */ [[nodiscard]] bool get_equidistant_spacing() const; /** * @brief Whether spline interpolation is carried out in log-space + * * @return boolean flag */ [[nodiscard]] bool get_logarithmic_parametrization() const; /** * @brief The number of interpolation nodes for this spline + * * @return number of nodes */ [[nodiscard]] int n_nodes() const { @@ -247,6 +263,7 @@ class AbstractSpline { * @brief Set the limit value of the spline * (in the scale in which interpolation is carried out) * as the evaluation point tends to positive infinity. + * * @param finalValue final value */ void set_final_value_scaled(realtype finalValue); @@ -255,6 +272,7 @@ class AbstractSpline { * @brief Set the limit value of the sensitivity * (in the scale in which interpolation is carried out) * as the evaluation point tends to positive infinity. + * * @param finalSensitivity final value of the sensitivity * for each parameter */ @@ -288,6 +306,7 @@ class HermiteSpline : public AbstractSpline { /** * @brief Construct a `HermiteSpline`. + * * @param nodes the nodes defining the position at which the value of * the spline is known * (if `equidistant_spacing` is true, it must contain only the first and @@ -335,6 +354,7 @@ class HermiteSpline : public AbstractSpline { /** * @brief Get the derivative of the spline at a given node + * * @param i index of the node at which the spline is to be evaluated * @return value of the derivative at the `i`-th node */ @@ -343,6 +363,7 @@ class HermiteSpline : public AbstractSpline { /** * @brief Get the derivative of the spline at a given node * in the scale in which interpolation is carried out (e.g., log-scale) + * * @param i index of the node at which the spline is to be evaluated * @return scaled value of the derivative at the `i`-th node */ @@ -354,6 +375,7 @@ class HermiteSpline : public AbstractSpline { /** * @brief Whether derivatives of this spline are computed * by finite differences + * * @return boolean flag */ [[nodiscard]] bool get_node_derivative_by_fd() const { diff --git a/include/amici/steadystateproblem.h b/include/amici/steadystateproblem.h index e0a194805a..4100511eb9 100644 --- a/include/amici/steadystateproblem.h +++ b/include/amici/steadystateproblem.h @@ -25,6 +25,7 @@ class WRMSComputer { public: /** * @brief Constructor. + * * @param n The length of the vectors for which to compute the WRMS. * @param sunctx A SUNDIALS context for the NVector. * @param atol Absolute tolerance to compute error weights. @@ -43,6 +44,7 @@ class WRMSComputer { /** * @brief Compute the weighted root-mean-square of the residuals. + * * @param x Vector to compute the WRMS for. * @param x_ref The reference vector from which to compute the error * weights. @@ -94,6 +96,7 @@ class NewtonsMethod { /** * @brief Run the Newton solver iterations and checks for convergence * to steady state. + * * @param xdot Time derivative of the state vector `state.x`. * @param state SimulationState instance containing the current state. * @param wrms_computer WRMSComputer instance to compute the WRMS norm. @@ -104,6 +107,7 @@ class NewtonsMethod { /** * @brief Compute the Newton step for the current state_.x and xdot and * store it in delta_. + * * @param xdot Time derivative of the state vector `state.x`. * @param state SimulationState instance containing the current state. */ @@ -111,18 +115,21 @@ class NewtonsMethod { /** * @brief Get the last Newton step. + * * @return Newton step */ [[nodiscard]] AmiVector const& get_delta() const { return delta_; } /** * @brief Get the number of steps taken in the current iteration. + * * @return Number of steps taken. */ [[nodiscard]] int get_num_steps() const { return i_step_; } /** * @brief Get the current WRMS norm. + * * @return The current WRMS norm. */ [[nodiscard]] realtype get_wrms() const { return wrms_; } @@ -143,6 +150,7 @@ class NewtonsMethod { /** * @brief Compute the weighted root-mean-square of the residuals. + * * @param xdot * @param state * @param wrms_computer diff --git a/include/amici/sundials_linsol_wrapper.h b/include/amici/sundials_linsol_wrapper.h index c67d4da47d..4ff564c359 100644 --- a/include/amici/sundials_linsol_wrapper.h +++ b/include/amici/sundials_linsol_wrapper.h @@ -45,18 +45,21 @@ class SUNLinSolWrapper { /** * @brief Copy constructor + * * @param other */ SUNLinSolWrapper(SUNLinSolWrapper const& other) = delete; /** * @brief Move constructor + * * @param other */ SUNLinSolWrapper(SUNLinSolWrapper&& other) noexcept; /** * @brief Copy assignment + * * @param other * @return */ @@ -64,6 +67,7 @@ class SUNLinSolWrapper { /** * @brief Move assignment + * * @param other * @return */ @@ -71,12 +75,14 @@ class SUNLinSolWrapper { /** * @brief Returns the wrapped SUNLinSol. + * * @return SUNLinearSolver */ SUNLinearSolver get() const; /** * @brief Returns an identifier for the linear solver type. + * * @return */ SUNLinearSolver_Type get_type() const; @@ -89,6 +95,7 @@ class SUNLinSolWrapper { /** * @brief Solves a linear system A*x = b + * * @param x A template for cloning vectors needed within the solver. * @param b * @param tol Tolerance (weighted 2-norm), iterative solvers only @@ -98,12 +105,14 @@ class SUNLinSolWrapper { /** * @brief Returns the last error flag encountered within the linear solver + * * @return error flag */ long int get_last_flag() const; /** * @brief Returns the integer and real workspace sizes for the linear solver + * * @param lenrwLS output argument for size of real workspace * @param leniwLS output argument for size of integer workspace * @return workspace size @@ -112,6 +121,7 @@ class SUNLinSolWrapper { /** * @brief Get the matrix A (matrix solvers only). + * * @return A */ virtual SUNMatrixWrapper& getMatrix(); @@ -120,6 +130,7 @@ class SUNLinSolWrapper { /** * @brief Performs linear solver initialization (assumes that all * solver-specific options have been set). + * * @return error code */ int initialize(); @@ -146,6 +157,7 @@ class SUNLinSolBand : public SUNLinSolWrapper { /** * @brief Create new band solver and matrix A. + * * @param x A template for cloning vectors needed within the solver. * @param ubw upper bandwidth of band matrix A * @param lbw lower bandwidth of band matrix A @@ -160,6 +172,7 @@ class SUNLinSolDense : public SUNLinSolWrapper { public: /** * @brief Create dense solver + * * @param x A template for cloning vectors needed within the solver. */ explicit SUNLinSolDense(AmiVector const& x); @@ -175,6 +188,7 @@ class SUNLinSolKLU : public SUNLinSolWrapper { /** * @brief Create KLU solver with given matrix + * * @param x A template for cloning vectors needed within the solver. * @param A sparse matrix */ @@ -182,6 +196,7 @@ class SUNLinSolKLU : public SUNLinSolWrapper { /** * @brief Create KLU solver and matrix to operate on + * * @param x A template for cloning vectors needed within the solver. * @param nnz Number of non-zeros in matrix A * @param sparsetype Sparse matrix type (CSC_MAT, CSR_MAT) @@ -197,6 +212,7 @@ class SUNLinSolKLU : public SUNLinSolWrapper { * (symbolic and numeric) to be conducted at the next solver setup call. * * For more details see sunlinsol/sunlinsol_klu.h + * * @param nnz Number of non-zeros * @param reinit_type SUNKLU_REINIT_FULL or SUNKLU_REINIT_PARTIAL */ @@ -205,6 +221,7 @@ class SUNLinSolKLU : public SUNLinSolWrapper { /** * @brief Sets the ordering used by KLU for reducing fill in the linear * solve. + * * @param ordering */ void set_ordering(StateOrdering ordering); @@ -234,6 +251,7 @@ class SUNLinSolSuperLUMT : public SUNLinSolWrapper { /** * @brief Create SuperLUMT solver with given matrix + * * @param x A template for cloning vectors needed within the solver. * @param A sparse matrix * @param numThreads Number of threads to be used by SuperLUMT @@ -257,6 +275,7 @@ class SUNLinSolSuperLUMT : public SUNLinSolWrapper { /** * @brief Create SuperLUMT solver and matrix to operate on + * * @param x A template for cloning vectors needed within the solver. * @param nnz Number of non-zeros in matrix A * @param sparsetype Sparse matrix type (CSC_MAT, CSR_MAT) @@ -271,6 +290,7 @@ class SUNLinSolSuperLUMT : public SUNLinSolWrapper { /** * @brief Sets the ordering used by SuperLUMT for reducing fill in the * linear solve. + * * @param ordering */ void set_ordering(StateOrdering ordering); @@ -286,6 +306,7 @@ class SUNLinSolPCG : public SUNLinSolWrapper { public: /** * @brief Create PCG solver. + * * @param y * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -295,7 +316,9 @@ class SUNLinSolPCG : public SUNLinSolWrapper { /** * @brief Sets the function pointer for ATimes + * * (see sundials/sundials_linearsolver.h). + * * @param A_data * @param ATimes * @return @@ -305,7 +328,9 @@ class SUNLinSolPCG : public SUNLinSolWrapper { /** * @brief Sets function pointers for PSetup and PSolve routines inside * of iterative linear solver objects + * * (see sundials/sundials_linearsolver.h). + * * @param P_data * @param Pset * @param Psol @@ -316,6 +341,7 @@ class SUNLinSolPCG : public SUNLinSolWrapper { /** * @brief Sets pointers to left/right scaling vectors for the linear * system solve (see sundials/sundials_linearsolver.h). + * * @param s * @param nul * @return @@ -325,12 +351,14 @@ class SUNLinSolPCG : public SUNLinSolWrapper { /** * @brief Returns the number of linear iterations performed in the last * 'Solve' call + * * @return Number of iterations */ int get_num_iters() const; /** * @brief Returns the final residual norm from the last 'Solve' call. + * * @return residual norm */ realtype get_res_norm() const; @@ -338,6 +366,7 @@ class SUNLinSolPCG : public SUNLinSolWrapper { /** * @brief Get preconditioned initial residual * (see sundials/sundials_linearsolver.h). + * * @return */ N_Vector get_resid() const; @@ -351,6 +380,7 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { public: /** * @brief SUNLinSolSPBCGS + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -363,6 +393,7 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief SUNLinSolSPBCGS + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -376,6 +407,7 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief Sets the function pointer for ATimes * (see sundials/sundials_linearsolver.h). + * * @param A_data * @param ATimes * @return @@ -385,7 +417,9 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief Sets function pointers for PSetup and PSolve routines inside * of iterative linear solver objects + * * (see sundials/sundials_linearsolver.h). + * * @param P_data * @param Pset * @param Psol @@ -396,6 +430,7 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief Sets pointers to left/right scaling vectors for the linear * system solve (see sundials/sundials_linearsolver.h). + * * @param s * @param nul * @return @@ -405,12 +440,14 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief Returns the number of linear iterations performed in the last * 'Solve' call + * * @return Number of iterations */ int get_num_iters() const; /** * @brief Returns the final residual norm from the last 'Solve' call. + * * @return residual norm */ realtype get_res_norm() const; @@ -418,6 +455,7 @@ class SUNLinSolSPBCGS : public SUNLinSolWrapper { /** * @brief Get preconditioned initial residual * (see sundials/sundials_linearsolver.h). + * * @return */ N_Vector get_resid() const; @@ -431,6 +469,7 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { public: /** * @brief SUNLinSolSPFGMR + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -441,6 +480,7 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { /** * @brief Sets the function pointer for ATimes * (see sundials/sundials_linearsolver.h). + * * @param A_data * @param ATimes * @return @@ -451,6 +491,7 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { * @brief Sets function pointers for PSetup and PSolve routines inside * of iterative linear solver objects * (see sundials/sundials_linearsolver.h). + * * @param P_data * @param Pset * @param Psol @@ -461,6 +502,7 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { /** * @brief Sets pointers to left/right scaling vectors for the linear * system solve (see sundials/sundials_linearsolver.h). + * * @param s * @param nul * @return @@ -470,12 +512,14 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { /** * @brief Returns the number of linear iterations performed in the last * 'Solve' call + * * @return Number of iterations */ int get_num_iters() const; /** * @brief Returns the final residual norm from the last 'Solve' call. + * * @return residual norm */ realtype get_res_norm() const; @@ -483,6 +527,7 @@ class SUNLinSolSPFGMR : public SUNLinSolWrapper { /** * @brief Get preconditioned initial residual * (see sundials/sundials_linearsolver.h). + * * @return */ N_Vector get_resid() const; @@ -496,6 +541,7 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { public: /** * @brief Create SPGMR solver + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -509,6 +555,7 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { /** * @brief Sets the function pointer for ATimes * (see sundials/sundials_linearsolver.h). + * * @param A_data * @param ATimes * @return @@ -519,6 +566,7 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { * @brief Sets function pointers for PSetup and PSolve routines inside * of iterative linear solver objects * (see sundials/sundials_linearsolver.h). + * * @param P_data * @param Pset * @param Psol @@ -529,6 +577,7 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { /** * @brief Sets pointers to left/right scaling vectors for the linear * system solve (see sundials/sundials_linearsolver.h). + * * @param s * @param nul * @return @@ -538,12 +587,14 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { /** * @brief Returns the number of linear iterations performed in the last * 'Solve' call + * * @return Number of iterations */ int get_num_iters() const; /** * @brief Returns the final residual norm from the last 'Solve' call. + * * @return residual norm */ realtype get_res_norm() const; @@ -551,6 +602,7 @@ class SUNLinSolSPGMR : public SUNLinSolWrapper { /** * @brief Get preconditioned initial residual * (see sundials/sundials_linearsolver.h). + * * @return */ N_Vector get_resid() const; @@ -564,6 +616,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { public: /** * @brief Create SPTFQMR solver + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -576,6 +629,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { /** * @brief Create SPTFQMR solver + * * @param x A template for cloning vectors needed within the solver. * @param pretype Preconditioner type (PREC_NONE, PREC_LEFT, PREC_RIGHT, * PREC_BOTH) @@ -589,6 +643,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { /** * @brief Sets the function pointer for ATimes * (see sundials/sundials_linearsolver.h). + * * @param A_data * @param ATimes * @return @@ -599,6 +654,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { * @brief Sets function pointers for PSetup and PSolve routines inside * of iterative linear solver objects * (see sundials/sundials_linearsolver.h). + * * @param P_data * @param Pset * @param Psol @@ -609,6 +665,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { /** * @brief Sets pointers to left/right scaling vectors for the linear * system solve (see sundials/sundials_linearsolver.h). + * * @param s * @param nul * @return @@ -618,12 +675,14 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { /** * @brief Returns the number of linear iterations performed in the last * 'Solve' call + * * @return Number of iterations */ int get_num_iters() const; /** * @brief Returns the final residual norm from the last 'Solve' call. + * * @return residual norm */ realtype get_res_norm() const; @@ -631,6 +690,7 @@ class SUNLinSolSPTFQMR : public SUNLinSolWrapper { /** * @brief Get preconditioned initial residual * (see sundials/sundials_linearsolver.h). + * * @return */ N_Vector get_resid() const; @@ -644,6 +704,7 @@ class SUNNonLinSolWrapper { public: /** * @brief SUNNonLinSolWrapper from existing SUNNonlinearSolver + * * @param sol */ explicit SUNNonLinSolWrapper(SUNNonlinearSolver sol); @@ -652,18 +713,21 @@ class SUNNonLinSolWrapper { /** * @brief Copy constructor + * * @param other */ SUNNonLinSolWrapper(SUNNonLinSolWrapper const& other) = delete; /** * @brief Move constructor + * * @param other */ SUNNonLinSolWrapper(SUNNonLinSolWrapper&& other) noexcept; /** * @brief Copy assignment + * * @param other * @return */ @@ -671,6 +735,7 @@ class SUNNonLinSolWrapper { /** * @brief Move assignment + * * @param other * @return */ @@ -678,18 +743,21 @@ class SUNNonLinSolWrapper { /** * @brief Get the wrapped SUNNonlinearSolver + * * @return SUNNonlinearSolver */ SUNNonlinearSolver get() const; /** * @brief Get type ID of the solver + * * @return */ SUNNonlinearSolver_Type get_type() const; /** * @brief Setup solver + * * @param y the initial iteration passed to the nonlinear solver. * @param mem the sundials integrator memory structure. * @return @@ -698,6 +766,7 @@ class SUNNonLinSolWrapper { /** * @brief solve the nonlinear system F (y) = 0 or G(y) = y. + * * @param y0 the initial iterate for the nonlinear solve. This must remain * unchanged throughout the solution process. * @param y the solution to the nonlinear system @@ -718,6 +787,7 @@ class SUNNonLinSolWrapper { /** * @brief Set function to evaluate the nonlinear residual function F(y) = 0 * or the fixed point function G(y) = y + * * @param SysFn * @return */ @@ -725,6 +795,7 @@ class SUNNonLinSolWrapper { /** * @brief Set linear solver setup function. + * * @param SetupFn * @return */ @@ -739,6 +810,7 @@ class SUNNonLinSolWrapper { /** * @brief Set function to test for convergence + * * @param CTestFn * @param ctest_data * @return @@ -747,6 +819,7 @@ class SUNNonLinSolWrapper { /** * @brief Set maximum number of non-linear iterations + * * @param maxiters * @return */ @@ -787,12 +860,14 @@ class SUNNonLinSolNewton : public SUNNonLinSolWrapper { public: /** * @brief Create Newton solver + * * @param x A template for cloning vectors needed within the solver. */ explicit SUNNonLinSolNewton(N_Vector x); /** * @brief Create Newton solver for enabled sensitivity analysis + * * @param count Number of vectors in the nonlinear solve. When integrating * a system containing Ns sensitivities the value of count is: * - Ns+1 if using a simultaneous corrector approach. @@ -803,6 +878,7 @@ class SUNNonLinSolNewton : public SUNNonLinSolWrapper { /** * @brief Get function to evaluate the nonlinear residual function F(y) = 0 + * * @param SysFn * @return */ @@ -816,6 +892,7 @@ class SUNNonLinSolFixedPoint : public SUNNonLinSolWrapper { public: /** * @brief Create fixed-point solver + * * @param x template for cloning vectors needed within the solver. * @param m number of acceleration vectors to use */ @@ -823,6 +900,7 @@ class SUNNonLinSolFixedPoint : public SUNNonLinSolWrapper { /** * @brief Create fixed-point solver for use with sensitivity analysis + * * @param count Number of vectors in the nonlinear solve. When integrating * a system containing Ns sensitivities the value of count is: * - Ns+1 if using a simultaneous corrector approach. @@ -834,6 +912,7 @@ class SUNNonLinSolFixedPoint : public SUNNonLinSolWrapper { /** * @brief Get function to evaluate the fixed point function G(y) = y + * * @param SysFn * @return */ diff --git a/include/amici/sundials_matrix_wrapper.h b/include/amici/sundials_matrix_wrapper.h index 836aec077a..8ff17cf9c9 100644 --- a/include/amici/sundials_matrix_wrapper.h +++ b/include/amici/sundials_matrix_wrapper.h @@ -29,6 +29,7 @@ class SUNMatrixWrapper { /** * @brief Create sparse matrix. See SUNSparseMatrix in sunmatrix_sparse.h + * * @param M Number of rows * @param N Number of columns * @param NNZ Number of nonzeros @@ -42,6 +43,7 @@ class SUNMatrixWrapper { /** * @brief Create dense matrix. See SUNDenseMatrix in sunmatrix_dense.h + * * @param M Number of rows * @param N Number of columns * @param sunctx SUNDIALS context @@ -50,6 +52,7 @@ class SUNMatrixWrapper { /** * @brief Create banded matrix. See SUNBandMatrix in sunmatrix_band.h + * * @param M Number of rows and columns * @param ubw Upper bandwidth * @param lbw Lower bandwidth @@ -60,9 +63,11 @@ class SUNMatrixWrapper { ); /** - * @brief Create sparse matrix from dense or banded matrix. See - * SUNSparseFromDenseMatrix and SUNSparseFromBandMatrix in + * @brief Create sparse matrix from dense or banded matrix. + * + * See SUNSparseFromDenseMatrix and SUNSparseFromBandMatrix in * sunmatrix_sparse.h + * * @param A Wrapper for dense matrix * @param droptol tolerance for dropping entries * @param sparsetype Sparse type @@ -73,6 +78,7 @@ class SUNMatrixWrapper { /** * @brief Wrap existing SUNMatrix + * * @param mat */ explicit SUNMatrixWrapper(SUNMatrix mat); @@ -86,18 +92,21 @@ class SUNMatrixWrapper { /** * @brief Copy constructor + * * @param other */ SUNMatrixWrapper(SUNMatrixWrapper const& other); /** * @brief Move constructor + * * @param other */ SUNMatrixWrapper(SUNMatrixWrapper&& other); /** * @brief Copy assignment + * * @param other * @return */ @@ -105,6 +114,7 @@ class SUNMatrixWrapper { /** * @brief Move assignment + * * @param other * @return */ @@ -112,6 +122,7 @@ class SUNMatrixWrapper { /** * @brief Reallocate space for sparse matrix according to specified nnz + * * @param nnz new number of nonzero entries */ void reallocate(sunindextype nnz); @@ -124,6 +135,7 @@ class SUNMatrixWrapper { /** * @brief Get the wrapped SUNMatrix + * * @return raw SunMatrix object * @note Even though the returned matrix_ pointer is const qualified, * matrix_->content will not be const. This is a shortcoming in the @@ -135,6 +147,7 @@ class SUNMatrixWrapper { /** * @brief Get the number of rows + * * @return number of rows */ sunindextype rows() const { @@ -149,6 +162,7 @@ class SUNMatrixWrapper { /** * @brief Get the number of columns + * * @return number of columns */ sunindextype columns() const { @@ -164,6 +178,7 @@ class SUNMatrixWrapper { /** * @brief Get the number of specified non-zero elements (sparse matrices * only) + * * @note value will be 0 before indexptrs are set. * @return number of nonzero entries */ @@ -172,30 +187,35 @@ class SUNMatrixWrapper { /** * @brief Get the number of indexptrs that can be specified (sparse matrices * only) + * * @return number of indexptrs */ sunindextype num_indexptrs() const; /** * @brief Get the number of allocated data elements + * * @return number of allocated entries */ sunindextype capacity() const; /** * @brief Get raw data of a sparse matrix + * * @return pointer to first data entry */ realtype* data(); /** * @brief Get const raw data of a sparse matrix + * * @return pointer to first data entry */ realtype const* data() const; /** * @brief Get data of a sparse matrix + * * @param idx data index * @return idx-th data entry */ @@ -209,6 +229,7 @@ class SUNMatrixWrapper { /** * @brief Get data entry for a dense matrix + * * @param irow row * @param icol col * @return A(irow,icol) @@ -223,6 +244,7 @@ class SUNMatrixWrapper { /** * @brief Set data entry for a sparse matrix + * * @param idx data index * @param data data for idx-th entry */ @@ -236,6 +258,7 @@ class SUNMatrixWrapper { /** * @brief Set data entry for a dense matrix + * * @param irow row * @param icol col * @param data data for idx-th entry @@ -252,6 +275,7 @@ class SUNMatrixWrapper { /** * @brief Get the index value of a sparse matrix + * * @param idx data index * @return row (CSC) or column (CSR) for idx-th data entry */ @@ -265,6 +289,7 @@ class SUNMatrixWrapper { /** * @brief Set the index value of a sparse matrix + * * @param idx data index * @param val row (CSC) or column (CSR) for idx-th data entry */ @@ -278,6 +303,7 @@ class SUNMatrixWrapper { /** * @brief Set the index values of a sparse matrix + * * @param vals rows (CSC) or columns (CSR) for data entries */ void set_indexvals(gsl::span const vals) { @@ -290,6 +316,7 @@ class SUNMatrixWrapper { /** * @brief Get the index pointer of a sparse matrix + * * @param ptr_idx pointer index * @return index where the ptr_idx-th column (CSC) or row (CSR) starts */ @@ -303,6 +330,7 @@ class SUNMatrixWrapper { /** * @brief Set the index pointer of a sparse matrix + * * @param ptr_idx pointer index * @param ptr data-index where the ptr_idx-th column (CSC) or row (CSR) * starts @@ -320,6 +348,7 @@ class SUNMatrixWrapper { /** * @brief Set the index pointers of a sparse matrix + * * @param ptrs starting data-indices where the columns (CSC) or rows (CSR) * start */ @@ -334,18 +363,21 @@ class SUNMatrixWrapper { /** * @brief Get the type of sparse matrix + * * @return matrix type */ int sparsetype() const; /** * @brief multiply with a scalar (in-place) + * * @param a scalar value to multiply matrix */ void scale(realtype a); /** * @brief N_Vector interface for multiply + * * @param c output vector, may already contain values * @param b multiplication vector * @param alpha scalar coefficient for matrix @@ -354,6 +386,7 @@ class SUNMatrixWrapper { /** * @brief AmiVector interface for multiply + * * @param c output vector, may already contain values * @param b multiplication vector * @param alpha scalar coefficient for matrix @@ -366,6 +399,7 @@ class SUNMatrixWrapper { /** * @brief Perform matrix vector multiplication c += alpha * A*b + * * @param c output vector, may already contain values * @param b multiplication vector * @param alpha scalar coefficient @@ -376,6 +410,7 @@ class SUNMatrixWrapper { /** * @brief Perform reordered matrix vector multiplication c += A[:,cols]*b + * * @param c output vector, may already contain values * @param b multiplication vector * @param cols int vector for column reordering @@ -387,6 +422,7 @@ class SUNMatrixWrapper { /** * @brief Perform reordered matrix vector multiplication c += A[:,cols]*b + * * @param c output vector, may already contain values * @param b multiplication vector * @param cols int vector for column reordering @@ -399,6 +435,7 @@ class SUNMatrixWrapper { /** * @brief Perform matrix matrix multiplication C = A * B for sparse A, B, C + * * @param C output matrix, * @param B multiplication matrix * @note will overwrite existing data, indexptrs, indexvals for C, but will @@ -408,6 +445,7 @@ class SUNMatrixWrapper { /** * @brief Perform sparse matrix matrix addition C = alpha * A + beta * B + * * @param A addition matrix * @param alpha scalar A * @param B addition matrix @@ -422,6 +460,7 @@ class SUNMatrixWrapper { /** * @brief Perform matrix-matrix addition A = sum(mats(0)...mats(len(mats))) + * * @param mats vector of sparse matrices * @note will overwrite existing data, indexptrs, indexvals for A, but will * use preallocated space for these vars @@ -492,6 +531,7 @@ class SUNMatrixWrapper { /** * @brief Get matrix id + * * @return SUNMatrix_ID */ [[nodiscard]] SUNMatrix_ID matrix_id() const { return id_; } @@ -504,6 +544,7 @@ class SUNMatrixWrapper { /** * @brief Get SUNDIALS context + * * @return SUNDIALS context or nullptr if the matrix is empty */ [[nodiscard]] SUNContext get_ctx() const; @@ -593,6 +634,7 @@ class SUNMatrixWrapper { /** * @brief Output formatter for SUNMatrixWrapper. + * * @param os output stream * @param mat SUNMatrixWrapper to output * @return os @@ -623,6 +665,7 @@ inline std::ostream& operator<<(std::ostream& os, SUNMatrixWrapper const& mat) { /** * @brief Convert a flat index to a pair of row/column indices. + * * @param i flat index * @param m referred to matrix * @return row index, column index @@ -635,6 +678,7 @@ auto unravel_index(sunindextype i, SUNMatrix m) namespace gsl { /** * @brief Create span from SUNMatrix + * * @param m SUNMatrix * @return Created span */ diff --git a/include/amici/symbolic_functions.h b/include/amici/symbolic_functions.h index b1dca9921f..a16d865d8d 100644 --- a/include/amici/symbolic_functions.h +++ b/include/amici/symbolic_functions.h @@ -22,7 +22,7 @@ double log(double x); double dirac(double x); /** - * The Heaviside function. + * @brief The Heaviside function. * * @param x argument * @param x0 value at x==0 diff --git a/include/amici/vector.h b/include/amici/vector.h index fc65242996..009297becc 100644 --- a/include/amici/vector.h +++ b/include/amici/vector.h @@ -46,6 +46,7 @@ class AmiVector { * Using N_VMake_Serial ensures that the N_Vector * module does not try to deallocate the data vector * when calling N_VDestroy_Serial + * * @param length number of elements in vector * @param sunctx SUNDIALS context */ @@ -58,6 +59,7 @@ class AmiVector { * * Moves data from std::vector and constructs an nvec that points to the * data + * * @param rvec vector from which the data will be moved * @param sunctx SUNDIALS context */ @@ -67,8 +69,9 @@ class AmiVector { gsl::narrow(vec_.size()), vec_.data(), sunctx )) {} - /** Copy data from gsl::span and constructs a vector - * @brief constructor from gsl::span, + /** + * @brief Copy data from gsl::span and construct a vector + * * @param rvec vector from which the data will be copied * @param sunctx SUNDIALS context */ @@ -79,6 +82,7 @@ class AmiVector { /** * @brief copy constructor + * * @param vold vector from which the data will be copied */ AmiVector(AmiVector const& vold) @@ -94,6 +98,7 @@ class AmiVector { /** * @brief Copy from N_Vector + * * @param vold vector from which the data will be copied */ AmiVector(N_Vector const& vold) @@ -106,6 +111,7 @@ class AmiVector { /** * @brief move constructor + * * @param other vector from which the data will be moved */ AmiVector(AmiVector&& other) noexcept @@ -120,6 +126,7 @@ class AmiVector { /** * @brief copy assignment operator + * * @param other right hand side * @return left hand side */ @@ -127,6 +134,7 @@ class AmiVector { /** * @brief operator *= (element-wise multiplication) + * * @param multiplier multiplier * @return result */ @@ -140,6 +148,7 @@ class AmiVector { /** * @brief operator /= (element-wise division) + * * @param divisor divisor * @return result */ @@ -154,6 +163,7 @@ class AmiVector { /** * @brief Returns an iterator that points to the first element of the * vector. + * * @return iterator that points to the first element */ auto begin() { return vec_.begin(); } @@ -161,42 +171,49 @@ class AmiVector { /** * @brief Returns an iterator that points to one element after the last * element of the vector. + * * @return iterator that points to one element after the last element */ auto end() { return vec_.end(); } /** * @brief data accessor + * * @return pointer to data array */ realtype* data(); /** * @brief const data accessor + * * @return const pointer to data array */ [[nodiscard]] realtype const* data() const; /** * @brief N_Vector accessor + * * @return N_Vector */ N_Vector get_nvector(); /** * @brief N_Vector accessor + * * @return N_Vector */ [[nodiscard]] const_N_Vector get_nvector() const; /** * @brief Vector accessor + * * @return Vector */ [[nodiscard]] std::vector const& get_vector() const; /** * @brief returns the length of the vector + * * @return length */ [[nodiscard]] int size() const; @@ -213,12 +230,14 @@ class AmiVector { /** * @brief sets all data elements to a specific value + * * @param val value for data elements */ void set(realtype val); /** * @brief accessor to data elements of the vector + * * @param pos index of element * @return element */ @@ -226,6 +245,7 @@ class AmiVector { /** * @brief accessor to data elements of the vector + * * @param pos index of element * @return element */ @@ -233,6 +253,7 @@ class AmiVector { /** * @brief accessor to data elements of the vector + * * @param pos index of element * @return element */ @@ -240,6 +261,7 @@ class AmiVector { /** * @brief accessor to data elements of the vector + * * @param pos index of element * @return element */ @@ -247,6 +269,7 @@ class AmiVector { /** * @brief copies data from another AmiVector + * * @param other data source */ void copy(AmiVector const& other); @@ -258,6 +281,7 @@ class AmiVector { /** * @brief Serialize AmiVector (see boost::serialization::serialize) + * * @param ar Archive to serialize to * @param v Data to serialize * @param version Version number @@ -269,6 +293,7 @@ class AmiVector { /** * @brief Get SUNContext + * * @return The current SUNContext or nullptr, if this AmiVector is empty */ [[nodiscard]] SUNContext get_ctx() const { @@ -297,6 +322,7 @@ class AmiVector { /** * @brief reconstructs nvec such that data pointer points to vec data array + * * @param sunctx SUNDIALS context */ void synchronise_nvector(SUNContext sunctx); @@ -304,6 +330,7 @@ class AmiVector { /** * @brief Output formatter for AmiVector. + * * @param os output stream * @param v AmiVector to output * @return os @@ -332,12 +359,14 @@ class AmiVectorArray { AmiVectorArray() = default; /** + * @brief empty constructor + * * Creates an std::vector and attaches the * data pointer to a newly created N_VectorArray * using CloneVectorArrayEmpty ensures that the N_Vector * module does not try to deallocate the data vector * when calling N_VDestroyVectorArray_Serial - * @brief empty constructor + * * @param length_inner length of vectors * @param length_outer number of vectors * @param sunctx SUNDIALS context @@ -348,6 +377,7 @@ class AmiVectorArray { /** * @brief copy constructor + * * @param vaold object to copy from */ AmiVectorArray(AmiVectorArray const& vaold); @@ -356,6 +386,7 @@ class AmiVectorArray { /** * @brief copy assignment operator + * * @param other right hand side * @return left hand side */ @@ -363,6 +394,7 @@ class AmiVectorArray { /** * @brief accessor to data of AmiVector elements + * * @param pos index of AmiVector * @return pointer to data array */ @@ -370,6 +402,7 @@ class AmiVectorArray { /** * @brief const accessor to data of AmiVector elements + * * @param pos index of AmiVector * @return const pointer to data array */ @@ -377,6 +410,7 @@ class AmiVectorArray { /** * @brief accessor to elements of AmiVector elements + * * @param ipos inner index in AmiVector * @param jpos outer index in AmiVectorArray * @return element @@ -385,6 +419,7 @@ class AmiVectorArray { /** * @brief const accessor to elements of AmiVector elements + * * @param ipos inner index in AmiVector * @param jpos outer index in AmiVectorArray * @return element @@ -393,12 +428,14 @@ class AmiVectorArray { /** * @brief accessor to NVectorArray + * * @return N_VectorArray */ N_Vector* get_nvector_array(); /** * @brief accessor to NVector element + * * @param pos index of corresponding AmiVector * @return N_Vector */ @@ -406,6 +443,7 @@ class AmiVectorArray { /** * @brief const accessor to NVector element + * * @param pos index of corresponding AmiVector * @return N_Vector */ @@ -413,6 +451,7 @@ class AmiVectorArray { /** * @brief accessor to AmiVector elements + * * @param pos index of AmiVector * @return AmiVector */ @@ -420,6 +459,7 @@ class AmiVectorArray { /** * @brief const accessor to AmiVector elements + * * @param pos index of AmiVector * @return const AmiVector */ @@ -427,6 +467,7 @@ class AmiVectorArray { /** * @brief length of AmiVectorArray + * * @return length */ int size() const; @@ -438,6 +479,7 @@ class AmiVectorArray { /** * @brief flattens the AmiVectorArray to a vector in row-major format + * * @param vec vector into which the AmiVectorArray will be flattened. Must * have length equal to number of elements. */ @@ -445,6 +487,7 @@ class AmiVectorArray { /** * @brief copies data from another AmiVectorArray + * * @param other data source */ void copy(AmiVectorArray const& other); @@ -476,6 +519,7 @@ class AmiVectorArray { /** * @brief Output formatter for AmiVectorArray. + * * @param os output stream * @param arr AmiVectorArray to output * @return os @@ -493,6 +537,7 @@ inline std::ostream& operator<<(std::ostream& os, AmiVectorArray const& arr) { /** * @brief Computes z = a*x + b*y + * * @param a coefficient for x * @param x a vector * @param b coefficient for y @@ -511,6 +556,7 @@ inline void linear_sum( /** * @brief Compute dot product of x and y + * * @param x vector * @param y vector * @return dot product of x and y @@ -527,6 +573,7 @@ inline realtype dot_prod(AmiVector const& x, AmiVector const& y) { namespace gsl { /** * @brief Create span from N_Vector + * * @param nv * @return */ @@ -536,6 +583,7 @@ inline span make_span(N_Vector nv) { /** * @brief Create span from AmiVector + * * @param av * */