fix(engine_multiscale): resolved bug which prevented proper equilibrium abundances from being found

this was done by adjusting the scaling of the QSE operator() residuals from r = dy/dt to r=(dy/dt)/y

src/include/gridfire/engine/views/engine_defined.h

@@ -2,6 +2,7 @@
 
 #include "gridfire/engine/views/engine_view_abstract.h"
 #include "gridfire/engine/engine_abstract.h"
+#include "gridfire/engine/engine_graph.h"
 #include "gridfire/io/network_file.h"
 #include "gridfire/network.h"
 
@@ -15,7 +16,11 @@
 namespace gridfire{
     class DefinedEngineView : public DynamicEngine, public EngineView<DynamicEngine> {
     public:
-        DefinedEngineView(const std::vector<std::string>& peNames, DynamicEngine& baseEngine);
+        DefinedEngineView(const std::vector<std::string>& peNames, GraphEngine& baseEngine);
+
+        /** @brief Get the base engine associated with this defined engine view.
+         * @return A const reference to the base DynamicEngine.
+         */
         [[nodiscard]] const DynamicEngine& getBaseEngine() const override;
 
         // --- Engine Interface ---
@@ -159,7 +164,7 @@ namespace gridfire{
          */
         fourdst::composition::Composition update(const NetIn &netIn) override;
 
-        bool isStale(const NetIn& netIn) override;
+        [[deprecated]] bool isStale(const NetIn& netIn) override;
 
         /**
          * @brief Sets the screening model for the base engine.
@@ -182,11 +187,15 @@ namespace gridfire{
         [[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) override;
     protected:
         bool m_isStale = true;
-        DynamicEngine& m_baseEngine;
+        GraphEngine& m_baseEngine;
     private:
         quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log"); ///< Logger instance for trace and debug information.
         ///< Active species in the defined engine.
-        std::vector<fourdst::atomic::Species> m_activeSpecies;
+        std::set<fourdst::atomic::Species> m_activeSpecies;
+
+        ///< Cache for the active species vector to avoid dangling references.
+        mutable std::optional<std::vector<fourdst::atomic::Species>> m_activeSpeciesVectorCache = std::nullopt;
+
         ///< Active reactions in the defined engine.
         reaction::ReactionSet m_activeReactions;
 
@@ -266,7 +275,7 @@ namespace gridfire{
     class FileDefinedEngineView final: public DefinedEngineView {
     public:
         explicit FileDefinedEngineView(
-            DynamicEngine& baseEngine,
+            GraphEngine& baseEngine,
             const std::string& fileName,
             const io::NetworkFileParser& parser
         );

src/include/gridfire/engine/views/engine_multiscale.h

@@ -735,6 +735,15 @@ namespace gridfire {
             std::set<fourdst::atomic::Species> seed_species;      ///< Dynamic species in this group.
             double mean_timescale;                                ///< Mean timescale of the group.
 
+            // DEBUG METHODS.
+            // THESE SHOULD NOT BE USED IN PRODUCTION CODE.
+            [[deprecated("Use for debug only")]] void removeSpecies(const fourdst::atomic::Species& species);
+
+            [[deprecated("Use for debug only")]] void addSpeciesToAlgebraic(const fourdst::atomic::Species& species);
+
+            [[deprecated("Use for debug only")]] void addSpeciesToSeed(const fourdst::atomic::Species& species);
+
+
             /**
              * @brief Less-than operator for QSEGroup, used for sorting.
              * @param other The other QSEGroup to compare to.
@@ -848,7 +857,7 @@ namespace gridfire {
             m_T9(T9),
             m_rho(rho),
             m_Y_scale(Y_scale),
-            m_qse_solve_species_index_map(qse_solve_species_index_map){}
+            m_qse_solve_species_index_map(qse_solve_species_index_map) {}
 
             /**
              * @brief Gets the number of output values from the functor (size of the residual vector).

src/include/gridfire/engine/views/engine_priming.h

@@ -37,7 +37,7 @@ namespace gridfire {
          * @throws std::out_of_range If primingSymbol is not found in the species registry.
          * @throws std::runtime_error If no reactions contain the priming species.
          */
-        NetworkPrimingEngineView(const std::string& primingSymbol, DynamicEngine& baseEngine);
+        NetworkPrimingEngineView(const std::string& primingSymbol, GraphEngine& baseEngine);
         /**
          * @brief Constructs the view using an existing Species object.
          *
@@ -47,7 +47,7 @@ namespace gridfire {
          * @post The view will contain only reactions that involve the priming species.
          * @throws std::runtime_error If no reactions contain the priming species.
          */
-        NetworkPrimingEngineView(const fourdst::atomic::Species& primingSpecies, DynamicEngine& baseEngine);
+        NetworkPrimingEngineView(const fourdst::atomic::Species& primingSpecies, GraphEngine& baseEngine);
 
 
     private:
@@ -66,7 +66,7 @@ namespace gridfire {
          */
         [[nodiscard]] std::vector<std::string> constructPrimingReactionSet(
             const fourdst::atomic::Species& primingSpecies,
-            const DynamicEngine& baseEngine
+            const GraphEngine& baseEngine
         ) const;
     };