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

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:
         /**