feat(weak): major weak rate progress

Major weak rate progress which includes: A refactor of many of the public interfaces for GridFire Engines to use composition objects as opposed to raw abundance vectors. This helps prevent index mismatch errors. Further, the weak reaction class has been expanded with the majority of an implimentation, including an atomic_base derived class to allow for proper auto diff tracking of the interpolated table results. Some additional changes are that the version of fourdst and libcomposition have been bumped to versions with smarter caching of intermediate vectors and a few bug fixes.

src/include/gridfire/engine/engine_abstract.h

@@ -58,8 +58,10 @@ namespace gridfire {
      */
     template <IsArithmeticOrAD T>
     struct StepDerivatives {
-        std::vector<T> dydt; ///< Derivatives of abundances (dY/dt for each species).
+        std::map<fourdst::atomic::Species, T> dydt; ///< Derivatives of abundances (dY/dt for each species).
         T nuclearEnergyGenerationRate = T(0.0); ///< Specific energy generation rate (e.g., erg/g/s).
+
+        StepDerivatives() : dydt(), nuclearEnergyGenerationRate(T(0.0)) {}
     };
 
     using SparsityPattern = std::vector<std::pair<size_t, size_t>>;
@@ -107,7 +109,7 @@ namespace gridfire {
         /**
          * @brief Calculate the right-hand side (dY/dt) and energy generation.
          *
-         * @param Y Vector of current abundances for all species.
+         * @param comp Composition object containing current abundances.
          * @param T9 Temperature in units of 10^9 K.
          * @param rho Density in g/cm^3.
          * @return StepDerivatives<double> containing dY/dt and energy generation rate.
@@ -117,7 +119,7 @@ namespace gridfire {
          * rate for the current state.
          */
         [[nodiscard]] virtual std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
-            const std::vector<double>& Y,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho
         ) const = 0;
@@ -142,7 +144,7 @@ namespace gridfire {
         /**
          * @brief Generate the Jacobian matrix for the current state.
          *
-         * @param Y_dynamic Vector of current abundances.
+         * @param comp Composition object containing current abundances.
          * @param T9 Temperature in units of 10^9 K.
          * @param rho Density in g/cm^3.
          *
@@ -150,13 +152,13 @@ namespace gridfire {
          * for the current state. The matrix can then be accessed via getJacobianMatrixEntry().
          */
         virtual void generateJacobianMatrix(
-            const std::vector<double>& Y_dynamic,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho
         ) const = 0;
 
         virtual void generateJacobianMatrix(
-            const std::vector<double>& Y_dynamic,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho,
             const SparsityPattern& sparsityPattern
@@ -167,15 +169,15 @@ namespace gridfire {
         /**
          * @brief Get an entry from the previously generated Jacobian matrix.
          *
-         * @param i Row index (species index).
-         * @param j Column index (species index).
+         * @param rowSpecies The species corresponding to the row index (i)
+         * @param colSpecies The species corresponding to the column index (j)
          * @return Value of the Jacobian matrix at (i, j).
          *
          * The Jacobian must have been generated by generateJacobianMatrix() before calling this.
          */
         [[nodiscard]] virtual double getJacobianMatrixEntry(
-            int i,
-            int j
+            const fourdst::atomic::Species& rowSpecies,
+            const fourdst::atomic::Species& colSpecies
         ) const = 0;
 
 
@@ -190,22 +192,22 @@ namespace gridfire {
         /**
          * @brief Get an entry from the stoichiometry matrix.
          *
-         * @param speciesIndex Index of the species.
-         * @param reactionIndex Index of the reaction.
+         * @param species species to look up stoichiometry for.
+         * @param reaction reaction to find
          * @return Stoichiometric coefficient for the species in the reaction.
          *
          * The stoichiometry matrix must have been generated by generateStoichiometryMatrix().
          */
         [[nodiscard]] virtual int getStoichiometryMatrixEntry(
-            int speciesIndex,
-            int reactionIndex
+            const fourdst::atomic::Species& species,
+            const reaction::Reaction& reaction
         ) const = 0;
 
         /**
          * @brief Calculate the molar reaction flow for a given reaction.
          *
          * @param reaction The reaction for which to calculate the flow.
-         * @param Y Vector of current abundances.
+         * @param comp Composition object containing current abundances.
          * @param T9 Temperature in units of 10^9 K.
          * @param rho Density in g/cm^3.
          * @return Molar flow rate for the reaction (e.g., mol/g/s).
@@ -215,7 +217,7 @@ namespace gridfire {
          */
         [[nodiscard]] virtual double calculateMolarReactionFlow(
             const reaction::Reaction& reaction,
-            const std::vector<double>& Y,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho
         ) const = 0;
@@ -223,7 +225,7 @@ namespace gridfire {
         /**
          * @brief Calculate the derivatives of the energy generation rate with respect to T and rho.
          *
-         * @param Y Vector of current abundances.
+         * @param comp Composition object containing current abundances.
          * @param T9 Temperature in units of 10^9 K.
          * @param rho Density in g/cm^3.
          * @return EnergyDerivatives containing dEps/dT and dEps/dRho.
@@ -232,9 +234,9 @@ namespace gridfire {
          * generation rate with respect to temperature and density for the current state.
          */
         [[nodiscard]] virtual EnergyDerivatives calculateEpsDerivatives(
-            const std::vector<double>& Y,
-            const double T9,
-            const double rho
+            const fourdst::composition::Composition& comp,
+            double T9,
+            double rho
         ) const = 0;
 
         /**
@@ -249,7 +251,7 @@ namespace gridfire {
         /**
          * @brief Compute timescales for all species in the network.
          *
-         * @param Y Vector of current abundances.
+         * @param comp Composition object containing current abundances.
          * @param T9 Temperature in units of 10^9 K.
          * @param rho Density in g/cm^3.
          * @return Map from Species to their characteristic timescales (s).
@@ -258,13 +260,13 @@ namespace gridfire {
          * which can be used for timestep control, diagnostics, and reaction network culling.
          */
         [[nodiscard]] virtual std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
-            const std::vector<double>& Y,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho
         ) const = 0;
 
         [[nodiscard]] virtual std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
-            const std::vector<double>& Y,
+            const fourdst::composition::Composition& comp,
             double T9,
             double rho
         ) const = 0;