feat(Jacobian): Jacobian generation is now stateless.

Previously Jacobians were stored by engines and accessed through engine
accessors (e.g getJacobianMatrixEntry); however, this resulted in
desynced jacobian states. We have changed to a pattern of Engine creates
a jacobian and returns it to the caller. The caller can then do what
they will with it. Because of this the getJacobianMatrixEntry method has
been removed.

BREAKING CHANGE:
    - There is no longer any getJacobianMatrixEntry method on
DynamicEngine classes
    - the generateJacobian method signature has changed to return a
NetworkJacobian object. Internally this uses an Eigen Sparse Matrix to
store its data.
This commit is contained in:
2025-11-14 10:51:40 -05:00
parent 1500f863b6
commit 9417b79a32
14 changed files with 352 additions and 440 deletions

View File

@@ -148,7 +148,7 @@ namespace gridfire {
* @throws exceptions::StaleEngineError If the QSE cache misses, as it cannot proceed
* without a valid partition.
*/
void generateJacobianMatrix(
[[nodiscard]] NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -177,7 +177,7 @@ namespace gridfire {
*
* @throws exceptions::StaleEngineError If the QSE cache misses.
*/
void generateJacobianMatrix(
[[nodiscard]] NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho,
@@ -205,35 +205,13 @@ namespace gridfire {
*
* @throws exceptions::StaleEngineError If the QSE cache misses.
*/
void generateJacobianMatrix(
[[nodiscard]] NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho,
const SparsityPattern &sparsityPattern
) const override;
/**
* @brief Gets an entry from the previously generated Jacobian matrix.
*
* @param rowSpecies Species corresponding to the row index (i_full).
* @param colSpecies Species corresponding to the column index (j_full).
* @return Value of the Jacobian matrix at (i_full, j_full).
*
* @par Purpose
* To provide Jacobian entries to an implicit solver.
*
* @par How
* This method directly delegates to the base engine's `getJacobianMatrixEntry`.
* It does not currently modify the Jacobian to reflect the QSE algebraic constraints,
* as these are handled by setting `dY/dt = 0` in `calculateRHSAndEnergy`.
*
* @pre `generateJacobianMatrix()` must have been called for the current state.
*/
[[nodiscard]] double getJacobianMatrixEntry(
const fourdst::atomic::Species& rowSpecies,
const fourdst::atomic::Species& colSpecies
) const override;
/**
* @brief Generates the stoichiometry matrix for the network.
*
@@ -578,6 +556,8 @@ namespace gridfire {
*/
fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species &species) const override;
private:
/**