docs(GridFire): added loads of docs and supressed yaml-cpp shadow warnings

.gitignore

@@ -57,6 +57,8 @@ tags
 *.private
 *.private/
 
+*.bin
+
 subprojects/mfem/
 subprojects/tetgen/
 subprojects/yaml-cpp/

src/include/gridfire/engine/engine.h

@@ -1,3 +1,177 @@
+/**
+ * @file engine.h
+ * @brief Core header for the GridFire reaction network engine module.
+ *
+ * This module defines the core interfaces and classes for reaction network
+ * engines in GridFire. It provides abstract base classes for engines,
+ * dynamic engines, and engine views, as well as concrete engine
+ * implementations and view implementations.
+ *
+ * The engine module is designed to support a wide range of reaction network
+ * simulations, from simple single-zone calculations to complex multi-zone
+ * simulations with adaptive network topologies.
+ *
+ * @section EngineDesign Engine Design
+ *
+ * The engine module is built around the following key concepts:
+ *
+ *  - **Engine:** The base class for all reaction network engines. It defines
+ *    the minimal interface for evaluating the right-hand side (dY/dt) and
+ *    energy generation rate for a given set of abundances, temperature, and
+ *    density.
+ *
+ *  - **DynamicEngine:** An extension of the Engine class that supports
+ *    Jacobian and stoichiometry operations, as well as the ability to
+ *    dynamically modify the reaction network.
+ *
+ *  - **EngineView:** An abstract base class for "views" of reaction network
+ *    engines. Engine views provide a way to dynamically or adaptively
+ *    modify the network topology without modifying the underlying physics
+ *    engine.
+ *
+ * @section EngineComposition Engine Composition
+ *
+ * Engines and engine views can be composed to create complex reaction network
+ * simulations. For example, an AdaptiveEngineView can be used to dynamically
+ * cull species and reactions from a GraphEngine, reducing the computational
+ * cost of the simulation.
+ *
+ * The order in which engines and engine views are composed is important. The
+ * base engine should always be the innermost engine, and the engine views
+ * should be layered on top of the base engine.
+ *
+ * @section AvailableEngines Available Engines
+ *
+ * The engine module provides the following concrete engine implementations:
+ *
+ *  - **GraphEngine:** A reaction network engine that uses a graph-based
+ *    representation of the reaction network. It uses sparse matrices for
+ *    efficient storage and computation of the stoichiometry and Jacobian
+ *    matrices.
+ *
+ * @section AvailableViews Available Views
+ *
+ * The engine module provides the following engine view implementations:
+ *
+ *  - **AdaptiveEngineView:** An engine view that dynamically adapts the
+ *    reaction network based on runtime conditions. It culls species and
+ *    reactions with low reaction flow rates, reducing the computational
+ *    cost of the simulation.
+ *
+ *  - **DefinedEngineView:** An engine view that restricts the reaction
+ *    network to a predefined set of species and reactions. This can be
+ *    useful for simulating specific reaction pathways or for comparing
+ *    results with other codes.
+ *
+ *  - **MultiscalePartitioningEngineView:** An engine view that partitions the
+ *    reaction network into multiple groups based on timescales. This can be
+ *    useful for simulating stiff reaction networks, where some reactions
+ *    occur much faster than others.
+ *
+ *  - **NetworkPrimingEngineView:** An engine view that primes the reaction
+ *    network with a specific species or set of species. This can be useful
+ *    for igniting a reaction network or for studying the effects of specific
+ *    species on the network.
+ *
+ * @section UsageExamples Usage Examples
+ *
+ * @subsection GraphEngineExample GraphEngine Example
+ *
+ * The following code shows how to create a GraphEngine from a composition:
+ *
+ * @code
+ * #include "gridfire/engine/engine_graph.h"
+ * #include "fourdst/composition/composition.h"
+ *
+ * // Create a composition
+ * fourdst::composition::Composition composition;
+ *
+ * // Create a GraphEngine
+ * gridfire::GraphEngine engine(composition);
+ * @endcode
+ *
+ * @subsection AdaptiveEngineViewExample AdaptiveEngineView Example
+ *
+ * The following code shows how to create an AdaptiveEngineView from a
+ * GraphEngine:
+ *
+ * @code
+ * #include "gridfire/engine/views/engine_adaptive.h"
+ * #include "gridfire/engine/engine_graph.h"
+ * #include "fourdst/composition/composition.h"
+ *
+ * // Create a composition
+ * fourdst::composition::Composition composition;
+ *
+ * // Create a GraphEngine
+ * gridfire::GraphEngine baseEngine(composition);
+ *
+ * // Create an AdaptiveEngineView
+ * gridfire::AdaptiveEngineView engine(baseEngine);
+ * @endcode
+ *
+ * @subsection DefinedEngineViewExample DefinedEngineView Example
+ *
+ * The following code shows how to create a DefinedEngineView from a
+ * GraphEngine:
+ *
+ * @code
+ * #include "gridfire/engine/views/engine_defined.h"
+ * #include "gridfire/engine/engine_graph.h"
+ * #include "fourdst/composition/composition.h"
+ *
+ * // Create a composition
+ * fourdst::composition::Composition composition;
+ *
+ * // Create a GraphEngine
+ * gridfire::GraphEngine baseEngine(composition);
+ *
+ * // Create a DefinedEngineView
+ * std::vector<std::string> peNames = {"p(p,e+)d", "he4(a,g)be8"};
+ * gridfire::DefinedEngineView engine(peNames, baseEngine);
+ * @endcode
+ *
+ * @subsection MultiscalePartitioningEngineViewExample MultiscalePartitioningEngineView Example
+ *
+ * The following code shows how to create a MultiscalePartitioningEngineView from a
+ * GraphEngine:
+ *
+ * @code
+ * #include "gridfire/engine/views/engine_multiscale.h"
+ * #include "gridfire/engine/engine_graph.h"
+ * #include "fourdst/composition/composition.h"
+ *
+ * // Create a composition
+ * fourdst::composition::Composition composition;
+ *
+ * // Create a GraphEngine
+ * gridfire::GraphEngine baseEngine(composition);
+ *
+ * // Create a MultiscalePartitioningEngineView
+ * gridfire::MultiscalePartitioningEngineView engine(baseEngine);
+ * @endcode
+ *
+ * @subsection NetworkPrimingEngineViewExample NetworkPrimingEngineView Example
+ *
+ * The following code shows how to create a NetworkPrimingEngineView from a
+ * GraphEngine:
+ *
+ * @code
+ * #include "gridfire/engine/views/engine_priming.h"
+ * #include "gridfire/engine/engine_graph.h"
+ * #include "fourdst/composition/composition.h"
+ *
+ * // Create a composition
+ * fourdst::composition::Composition composition;
+ *
+ * // Create a GraphEngine
+ * gridfire::GraphEngine baseEngine(composition);
+ *
+ * // Create a NetworkPrimingEngineView
+ * std::string primingSymbol = "p";
+ * gridfire::NetworkPrimingEngineView engine(primingSymbol, baseEngine);
+ * @endcode
+ */
 #pragma once
 
 #include "gridfire/engine/engine_abstract.h"

src/include/gridfire/engine/engine_graph.h

@@ -833,14 +833,6 @@ namespace gridfire {
         // --- Pre-setup (flags to control conditionals in an AD safe / branch aware manner) ---
         // ----- Constants for AD safe calculations ---
         const T zero = static_cast<T>(0.0);
-        const T one = static_cast<T>(1.0);
-
-        // ----- Initialize variables for molar concentration product and thresholds ---
-        // Note: the logic here is that we use CppAD::CondExprLt to test thresholds and if they are less we set the flag
-        //       to zero so that the final returned reaction flow is 0. This is as opposed to standard if statements
-        //       which create branches that break the AD tape.
-        const T Y_threshold = static_cast<T>(MIN_ABUNDANCE_THRESHOLD);
-        T threshold_flag = one;
 
         // --- Calculate the molar reaction rate (in units of [s^-1][cm^3(N-1)][mol^(1-N)] for N reactants) ---
         const T k_reaction = reaction.calculate_rate(T9);
@@ -864,9 +856,6 @@ namespace gridfire {
             const size_t species_index = species_it->second;
             const T Yi = Y[species_index];
 
-            // --- Check if the species abundance is below the threshold where we ignore reactions ---
-            // threshold_flag *= CppAD::CondExpLt(Yi, Y_threshold, zero, one);
-
             // --- If count is > 1 , we need to raise the molar concentration to the power of count since there are really count bodies in that reaction ---
             molar_concentration_product *= CppAD::pow(Yi, static_cast<T>(count)); // ni^count
 
@@ -881,7 +870,7 @@ namespace gridfire {
         //       the tape more expensive to record, but it will also mean that we only need to record it once for
         //       the entire network.
         const T densityTerm = CppAD::pow(rho, totalReactants > 1 ? static_cast<T>(totalReactants - 1) : zero); // Density raised to the power of (N-1) for N reactants
-        return molar_concentration_product * k_reaction * threshold_flag * densityTerm;
+        return molar_concentration_product * k_reaction * densityTerm;
     }
 
 };

src/include/gridfire/screening/screening_weak.h

@@ -78,7 +78,7 @@ namespace gridfire::screening {
         ) const override;
     private:
         /// @brief Logger instance for recording trace and debug information.
-        quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
+        [[maybe_unused]] quill::Logger* m_logger = fourdst::logging::LogManager::getInstance().getLogger("log");
 
     private:
         /**

src/lib/engine/engine_graph.cpp

@@ -41,8 +41,8 @@ namespace gridfire {
         const partition::PartitionFunction& partitionFunction,
         const BuildDepthType buildDepth) :
     m_reactions(build_reaclib_nuclear_network(composition, buildDepth, false)),
-    m_partitionFunction(partitionFunction.clone()),
-    m_depth(buildDepth)
+    m_depth(buildDepth),
+    m_partitionFunction(partitionFunction.clone())
     {
         syncInternalMaps();
     }

src/lib/engine/views/engine_multiscale.cpp

@@ -5,6 +5,7 @@
 
 #include "fourdst/logging/logging.h"
 
+#include <stdexcept>
 #include <vector>
 #include <unordered_map>
 #include <unordered_set>
@@ -482,18 +483,7 @@ namespace gridfire {
         // --- Step 5. Identify potential seed species for each candidate pool ---
         LOG_TRACE_L1(m_logger, "Identifying potential seed species for candidate pools...");
         const std::vector<QSEGroup> candidate_groups = constructCandidateGroups(connected_pools, Y, T9, rho);
-        LOG_TRACE_L1(
-            m_logger,
-            "Found {} candidate QSE groups for further analysis: {}",
-            candidate_groups.size(),
-            [&]() -> std::string {
-                std::stringstream ss;
-                for (const auto& group : candidate_groups) {
-                     ss << group << " ";
-                }
-                return ss.str();
-            }()
-        );
+        LOG_TRACE_L1(m_logger, "Found {} candidate QSE groups for further analysis", candidate_groups.size());
 
         LOG_TRACE_L1(m_logger, "Validating candidate groups with flux analysis...");
         const std::vector<QSEGroup> validated_groups = validateGroupsWithFluxAnalysis(candidate_groups, Y, T9, rho);
@@ -1401,9 +1391,7 @@ namespace gridfire {
 
                 // Add clique
                 for (const size_t& u : intersection) {
-                    const auto& uSpecies = m_baseEngine.getNetworkSpecies()[u];
                     for (const size_t& v : intersection) {
-                        const auto & vSpecies = m_baseEngine.getNetworkSpecies()[v];
                         if (u != v) { // Avoid self-loops
                             connectivity_graph[u].push_back(v);
                         }
@@ -1623,4 +1611,35 @@ namespace gridfire {
         return !(*this == other);
     }
 
+    void MultiscalePartitioningEngineView::CacheStats::hit(const operators op) {
+        if (op == operators::All) {
+            throw std::invalid_argument("Cannot use 'ALL' as an operator for a hit");
+        }
+
+        m_hit ++;
+        m_operatorHits[op]++;
+    }
+    void MultiscalePartitioningEngineView::CacheStats::miss(const operators op) {
+        if (op == operators::All) {
+            throw std::invalid_argument("Cannot use 'ALL' as an operator for a miss");
+        }
+
+        m_miss ++;
+        m_operatorMisses[op]++;
+    }
+
+    size_t MultiscalePartitioningEngineView::CacheStats::hits(const operators op) const {
+        if (op == operators::All) {
+            return m_hit;
+        }
+        return m_operatorHits.at(op);
+    }
+
+    size_t MultiscalePartitioningEngineView::CacheStats::misses(const operators op) const {
+        if (op == operators::All) {
+            return m_miss;
+        }
+        return m_operatorMisses.at(op);
+    }
+
 }

src/lib/io/network_file.cpp

@@ -53,10 +53,8 @@ namespace gridfire::io {
 
         ParsedNetworkData parsed;
         std::string line;
-        int line_number = 0;
         while (std::getline(file, line)) {
-            line_number++;
-            LOG_TRACE_L3(m_logger, "Parsing reaction list file {}, line {}: {}", filename, line_number, line);
+            LOG_TRACE_L3(m_logger, "Parsing reaction list file {}, line: {}", filename, line);
 
             const size_t comment_pos = line.find('#');
             if (comment_pos != std::string::npos) {

src/python/engine/trampoline/py_engine.cpp

@@ -14,11 +14,24 @@
 namespace py = pybind11;
 
 const std::vector<fourdst::atomic::Species>& PyEngine::getNetworkSpecies() const {
-    PYBIND11_OVERRIDE_PURE(
-        std::vector<fourdst::atomic::Species>,
-        gridfire::Engine,  /* Base class */
-        getNetworkSpecies
-    );
+    /*
+     * Acquire the GIL (Global Interpreter Lock) for thread safety
+     * with the Python interpreter.
+     */
+    py::gil_scoped_acquire gil;
+
+    /*
+     * get_override() looks for a Python method that overrides this C++ one.
+     */
+    py::function override = py::get_override(this, "getNetworkSpecies");
+
+    if (override) {
+        py::object result = override();
+        m_species_cache = result.cast<std::vector<fourdst::atomic::Species>>();
+        return m_species_cache;
+    }
+
+    py::pybind11_fail("Tried to call pure virtual function \"DynamicEngine::getNetworkSpecies\"");
 }
 
 std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError> PyEngine::calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const {
@@ -35,11 +48,24 @@ std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEn
 /////////////////////////////////////
 
 const std::vector<fourdst::atomic::Species>& PyDynamicEngine::getNetworkSpecies() const {
-    PYBIND11_OVERRIDE_PURE(
-        std::vector<fourdst::atomic::Species>,
-        gridfire::DynamicEngine,  /* Base class */
-        getNetworkSpecies
-    );
+    /*
+     * Acquire the GIL (Global Interpreter Lock) for thread safety
+     * with the Python interpreter.
+     */
+    py::gil_scoped_acquire gil;
+
+    /*
+     * get_override() looks for a Python method that overrides this C++ one.
+     */
+    py::function override = py::get_override(this, "getNetworkSpecies");
+
+    if (override) {
+        py::object result = override();
+        m_species_cache = result.cast<std::vector<fourdst::atomic::Species>>();
+        return m_species_cache;
+    }
+
+    py::pybind11_fail("Tried to call pure virtual function \"DynamicEngine::getNetworkSpecies\"");
 }
 std::expected<gridfire::StepDerivatives<double>, gridfire::expectations::StaleEngineError> PyDynamicEngine::calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const {
     PYBIND11_OVERRIDE_PURE(

src/python/engine/trampoline/py_engine.h

@@ -13,9 +13,12 @@ class PyEngine final : public gridfire::Engine {
 public:
     const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
     std::expected<gridfire::StepDerivatives<double>,gridfire::expectations::StaleEngineError> calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const override;
+private:
+    mutable std::vector<fourdst::atomic::Species> m_species_cache;
 };
 
 class PyDynamicEngine final : public gridfire::DynamicEngine {
+public:
     const std::vector<fourdst::atomic::Species>& getNetworkSpecies() const override;
     std::expected<gridfire::StepDerivatives<double>,gridfire::expectations::StaleEngineError> calculateRHSAndEnergy(const std::vector<double> &Y, double T9, double rho) const override;
     void generateJacobianMatrix(const std::vector<double> &Y_dynamic, double T9, double rho) const override;
@@ -41,6 +44,10 @@ class PyDynamicEngine final : public gridfire::DynamicEngine {
     void rebuild(const fourdst::composition::Composition& comp, gridfire::BuildDepthType depth) override {
         throw std::logic_error("Setting network depth not supported by this engine.");
     }
+private:
+    mutable std::vector<fourdst::atomic::Species> m_species_cache;
+
+
 };
 
 class PyEngineView final : public gridfire::EngineView<gridfire::Engine> {

subprojects/fourdst.wrap

@@ -1,4 +1,4 @@
 [wrap-git]
 url = https://github.com/4D-STAR/fourdst
-revision = v0.5.0
-depth = 1
+revision = v0.5.1
+depth = 1

tests/python/test.py

@@ -16,7 +16,7 @@ netIn = NetIn()
 netIn.composition = comp
 netIn.temperature = 1.5e7
 netIn.density = 1.5e2
-netIn.tMax = 3e14
+netIn.tMax = 3e17
 netIn.dt0 = 1e-12
 
 baseEngine = GraphEngine(comp, 2)