From 170d50676a3d346d182b802cad109fd65532828f Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 12 Feb 2015 04:04:55 +0000 Subject: [PATCH] [Doc] Document definition of the sensitivity coefficient --- include/cantera/zeroD/ReactorNet.h | 16 ++++++++++++++-- interfaces/cython/cantera/reactor.pyx | 27 +++++++++++++++++++-------- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/include/cantera/zeroD/ReactorNet.h b/include/cantera/zeroD/ReactorNet.h index 2ba1b7fed..884b51839 100644 --- a/include/cantera/zeroD/ReactorNet.h +++ b/include/cantera/zeroD/ReactorNet.h @@ -150,8 +150,19 @@ public: //! the values in the solution vector *y*. void updateState(doublereal* y); - //! Return the sensitivity of the *k*-th solution component with - //! respect to the *p*-th sensitivity parameter. + //! Return the sensitivity of the *k*-th solution component with respect to + //! the *p*-th sensitivity parameter. + /*! + * The normalized sensitivity coefficient \f$ S_{ki} \f$ of solution + * variable \f$ y_k \f$ with respect to sensitivity parameter \f$ p_i \f$ + * is defined as: + * + * \f[ S_{ki} = \frac{p_i}{y_k} \frac{\partial y_k}{\partial p_i} \f] + * + * For reaction sensitivities, the parameter is a multiplier on the forward + * rate constant (and implicitly on the reverse rate constant for + * reversible reactions). + */ double sensitivity(size_t k, size_t p) { if (!m_init) { initialize(); @@ -161,6 +172,7 @@ public: //! Return the sensitivity of the component named *component* with respect to //! the *p*-th sensitivity parameter. + //! @copydetails ReactorNet::sensitivity(size_t, size_t) double sensitivity(const std::string& component, size_t p, int reactor=0) { size_t k = globalComponentIndex(component, reactor); return sensitivity(k, p); diff --git a/interfaces/cython/cantera/reactor.pyx b/interfaces/cython/cantera/reactor.pyx index 8c102510b..b905f29d4 100644 --- a/interfaces/cython/cantera/reactor.pyx +++ b/interfaces/cython/cantera/reactor.pyx @@ -854,9 +854,10 @@ cdef class ReactorNet: Returns the sensitivity of the solution variable *component* in reactor *r* with respect to the parameter *p*. *component* can be a string or an integer. See `component_index` and `sensitivities` to - determine the integer index for the variables. If it is not given, *r* - defaults to the first reactor. Returns an empty array until the first - time step is taken. + determine the integer index for the variables and the definition of the + resulting sensitivity coefficient. If it is not given, *r* defaults to + the first reactor. Returns an empty array until the first time step is + taken. """ if isinstance(component, int): return self.net.sensitivity(component, p) @@ -864,12 +865,22 @@ cdef class ReactorNet: return self.net.sensitivity(stringify(component), p, r) def sensitivities(self): - """ + r""" Returns the senstivities of all of the solution variables with respect - to all of the registered parameters. The sensitivities are returned in - an array with dimensions *(n_vars, n_sensitivity_params)*, unless no - timesteps have been taken, in which case the shape is - *(0, n_sensitivity_params)*. The order of the variables (i.e. rows) is: + to all of the registered parameters. The normalized sensitivity + coefficient :math:`S_{ki}` of the solution varible :math:`y_k` with + respect to sensitivity parameter :math:`p_i` is defined as: + + .. math:: S_{ki} = \frac{p_i}{y_k} \frac{\partial y_k}{\partial p_i} + + For reaction sensitivities, the parameter is a multiplier on the forward + rate constant (and implicitly on the reverse rate constant for + reversible reactions). + + The sensitivities are returned in an array with dimensions *(n_vars, + n_sensitivity_params)*, unless no timesteps have been taken, in which + case the shape is *(0, n_sensitivity_params)*. The order of the + variables (i.e. rows) is: `Reactor` or `IdealGasReactor`: