tboudreaux/GridFire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ridfire)

Browse Source 
Added more documentation, also moved all engine code into
gridfire::engine namespace to be more in line with other parts of teh
code base
This commit is contained in:
Emily Boudreaux
2025-11-24 09:07:49 -05:00
parent 15ed7f70b1
commit 9fab4fbfae
64 changed files with 2506 additions and 848 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
src/include/gridfire/engine/views/engine_adaptive.h
View File

@@ -3,7 +3,7 @@
#include "gridfire/engine/views/engine_view_abstract.h"
#include "gridfire/screening/screening_abstract.h"
#include "gridfire/screening/screening_types.h"
#include "gridfire/network.h"
#include "gridfire/types/types.h"
#include "fourdst/atomic/atomicSpecies.h"
#include "fourdst/config/config.h"
@@ -13,7 +13,7 @@
#include "quill/Logger.h"
namespace gridfire {
namespace gridfire::engine {
/**
* @class AdaptiveEngineView
* @brief An engine view that dynamically adapts the reaction network based on runtime conditions.
@@ -101,7 +101,7 @@ namespace gridfire {
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
[[nodiscard]] std::expected<StepDerivatives<double>, engine::EngineStatus> calculateRHSAndEnergy(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -140,6 +140,20 @@ namespace gridfire {
double rho
) const override;
/**
* @brief Generates the Jacobian matrix for some set of active species such that that set is a subset of the active species in the view.
*
* @param comp The current composition of the system.
* @param T9 The temperature in units of 10^9 K.
* @param rho The density in g/cm^3.
* @param activeSpecies The list of active species for which to generate the Jacobian.
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to generate the Jacobian matrix.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
@@ -147,6 +161,20 @@ namespace gridfire {
const std::vector<fourdst::atomic::Species> &activeSpecies
) const override;
/**
* @brief Generates the Jacobian matrix for the active species with a given sparsity pattern.
*
* @param comp The current composition of the system.
* @param T9 The temperature in units of 10^9 K.
* @param rho The density in g/cm^3.
* @param sparsityPattern The sparsity pattern to use for the Jacobian matrix.
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to generate the Jacobian matrix.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @see AdaptiveEngineView::update()
*/
[[nodiscard]] NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
@@ -213,6 +241,15 @@ namespace gridfire {
*/
[[nodiscard]] const reaction::ReactionSet& getNetworkReactions() const override;
/**
* @brief Sets the reaction set for the base engine.
*
* This method delegates the call to the base engine to set the reaction set.
*
* @param reactions The ReactionSet to set in the base engine.
*
* @post The reaction set of the base engine is updated.
*/
void setNetworkReactions(const reaction::ReactionSet& reactions) override;
/**
@@ -228,13 +265,26 @@ namespace gridfire {
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, EngineStatus> getSpeciesTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
) const override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
/**
* @brief Computes destruction timescales for all active species in the network.
*
* @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 destruction timescales (s).
*
* This method maps the culled abundances to the full network abundances and calls the base engine
* to compute the species destruction timescales.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, EngineStatus> getSpeciesDestructionTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -278,14 +328,62 @@ namespace gridfire {
*/
[[nodiscard]] screening::ScreeningType getScreeningModel() const override;
/**
* @brief Gets the index of a species in the active species list.
*
* @param species The species for which to get the index.
* @return The index of the species in the active species list.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
* @throws std::out_of_range If the species is not part of the active species in the adaptive engine view.
*/
[[nodiscard]] size_t getSpeciesIndex(const fourdst::atomic::Species &species) const override;
/**
* @brief Maps the molar abundance vector from the active species to the full network species.
*
* @param netIn The current network input, containing temperature, density, and composition.
* @return A vector of molar abundances for all species in the full network.
*
* This method constructs a molar abundance vector for the full network by mapping the
* abundances from the active species in `netIn` to their corresponding indices in the
* full network. Species not present in `netIn` are assigned an abundance of zero.
*
* @throws std::runtime_error If the AdaptiveEngineView is stale (i.e., `update()` has not been called).
*/
[[nodiscard]] std::vector<double> mapNetInToMolarAbundanceVector(const NetIn &netIn) const override;
/**
* @brief Primes the engine with the given network input.
*
* @param netIn The current network input, containing temperature, density, and composition.
* @return A PrimingReport indicating the result of the priming operation.
*
* This method delegates the priming operation to the base engine.
*/
[[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) override;
fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
/**
* @brief Collect the composition of the base engine, ensure all active species are registered, and pass
* the composition back to the caller.
*
* @param comp The current composition of the system.
* @param T9 The temperature in units of 10^9 K.
* @param rho The density in g/cm^3.
*
* @note This function ensures that the state of both the base engine and the adaptive view are synchronized in the
* result back to the caller
*/
[[nodiscard]] fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
/**
* @brief Gets the status of a species in the network.
*
* @param species The species for which to get the status.
* @return The SpeciesStatus indicating the status of the species.
*
* This method delegates the call to the base engine to get the species status. If the base engine says that the species is active but it is not in the active species list of this view, the status is returned as INACTIVE_FLOW.
*/
[[nodiscard]] SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species &species) const override;
private:
using Config = fourdst::config::Config;

69
src/include/gridfire/engine/views/engine_defined.h
View File

@@ -4,7 +4,7 @@
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/engine_graph.h"
#include "gridfire/io/network_file.h"
#include "gridfire/network.h"
#include "gridfire/types/types.h"
#include "fourdst/config/config.h"
#include "fourdst/logging/logging.h"
@@ -13,7 +13,7 @@
#include <string>
namespace gridfire{
namespace gridfire::engine {
class DefinedEngineView : public DynamicEngine, public EngineView<DynamicEngine> {
public:
DefinedEngineView(const std::vector<std::string>& peNames, GraphEngine& baseEngine);
@@ -42,7 +42,7 @@ namespace gridfire{
*
* @throws std::runtime_error If the view is stale (i.e., `update()` has not been called after `setNetworkFile()`).
*/
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
[[nodiscard]] std::expected<StepDerivatives<double>, engine::EngineStatus> calculateRHSAndEnergy(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -150,7 +150,15 @@ namespace gridfire{
*/
[[nodiscard]] const reaction::ReactionSet& getNetworkReactions() const override;
/**
* @brief Sets the active reactions in the network.
*
* @param reactions The ReactionSet containing the reactions to set as active.
*
* @post The view is marked as stale and will need to be updated.
*/
void setNetworkReactions(const reaction::ReactionSet& reactions) override;
/**
* @brief Computes timescales for all active species in the network.
*
@@ -161,13 +169,25 @@ namespace gridfire{
*
* @throws std::runtime_error If the view is stale.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, engine::EngineStatus>
getSpeciesTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
) const override;
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
/**
* @brief Computes destruction timescales for all active species in the network.
*
* @param comp A Composition object containing the current composition of the system
* @param T9 Temperature in units of 10^9 K.
* @param rho Density in g/cm^3.
* @return Map from Species to their destruction timescales (s).
*
* @throws std::runtime_error If the view is stale.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, engine::EngineStatus>
getSpeciesDestructionTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -186,6 +206,12 @@ namespace gridfire{
*/
fourdst::composition::Composition update(const NetIn &netIn) override;
/**
* @brief Checks if the engine view is stale.
*
* @param netIn The current network input (unused).
* @return True if the view is stale and needs to be updated; false otherwise.
*/
[[deprecated]] bool isStale(const NetIn& netIn) override;
/**
@@ -202,14 +228,45 @@ namespace gridfire{
*/
[[nodiscard]] screening::ScreeningType getScreeningModel() const override;
/** @brief Maps a species from the full network to its index in the defined active network.
*
* @param species The species to map.
* @return The index of the species in the active network.
*
* @throws std::runtime_error If the species is not in the active set.
*/
[[nodiscard]] size_t getSpeciesIndex(const fourdst::atomic::Species &species) const override;
/**
* @brief Map from a NetIn object to a vector of molar abundances for the active species.
* @param netIn The NetIn object containing the full network abundances.
* @return A vector of molar abundances for the active species.
*/
[[nodiscard]] std::vector<double> mapNetInToMolarAbundanceVector(const NetIn &netIn) const override;
/**
* @brief Prime the engine view for calculations. This will delegate to the base engine.
* @param netIn The current network input.
* @return The PrimingReport from the base engine.
*/
[[nodiscard]] PrimingReport primeEngine(const NetIn &netIn) override;
fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
/**
* @brief Collects a Composition object from the base engine.
*
* @param comp The full Composition object.
* @param T9 The temperature in units of 10^9 K.
* @param rho The density in g/cm^3.
* @return A composition object representing the state of the engine stack and the current view.
*/
[[nodiscard]] fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
/**
* @brief Gets the status of a species in the active network.
*
* @param species The species for which to get the status.
* @return The SpeciesStatus indicating if the species is active, inactive, or not present.
*/
[[nodiscard]] SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species &species) const override;
protected:
bool m_isStale = true;

114
src/include/gridfire/engine/views/engine_multiscale.h
View File

@@ -3,14 +3,13 @@
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/views/engine_view_abstract.h"
#include "gridfire/engine/engine_graph.h"
#include "sundials/sundials_linearsolver.h"
#include "sundials/sundials_matrix.h"
#include "sundials/sundials_nvector.h"
#include "sundials/sundials_types.h"
#include "unsupported/Eigen/NonLinearOptimization"
namespace gridfire {
namespace gridfire::engine {
/**
* @class MultiscalePartitioningEngineView
* @brief An engine view that partitions the reaction network into multiple groups based on timescales.
@@ -119,12 +118,19 @@ namespace gridfire {
* @throws StaleEngineError If the QSE cache does not contain an entry for the given
* (T9, rho, Y_full). This indicates `update()` was not called recently enough.
*/
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
[[nodiscard]] std::expected<StepDerivatives<double>, engine::EngineStatus> calculateRHSAndEnergy(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
) const override;
/**
* @brief Calculates the energy generation rate derivatives with respect to abundances.
* @param comp The current composition.
* @param T9 The temperature in units of 10^9 K.
* @param rho The density in g/cm^3.
* @return The energy generation rate derivatives (dEps/dT and dEps/drho).
*/
[[nodiscard]] EnergyDerivatives calculateEpsDerivatives(
const fourdst::composition::CompositionAbstract &comp,
double T9,
@@ -327,7 +333,8 @@ namespace gridfire {
* @pre The engine must have a valid QSE cache entry for the given state.
* @throws StaleEngineError If the QSE cache misses.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesTimescales(
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, engine::EngineStatus>
getSpeciesTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -353,7 +360,8 @@ namespace gridfire {
* @pre The engine must have a valid QSE cache entry for the given state.
* @throws StaleEngineError If the QSE cache misses.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, engine::EngineStatus>
getSpeciesDestructionTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -542,13 +550,54 @@ namespace gridfire {
*/
[[nodiscard]] const std::vector<fourdst::atomic::Species>& getDynamicSpecies() const;
/**
* @brief Checks if a species is involved in the partitioned network.
*
* @param species The species to check.
* @return `true` if the species is in either the dynamic or algebraic sets, `false` otherwise.
*
* @par Purpose
* To allow external queries about species involvement in the partitioned network.
*
* @par How
* It checks for membership in both `m_dynamic_species` and `m_algebraic_species`.
*
* @pre `partitionNetwork()` must have been called.
*/
bool involvesSpecies(const fourdst::atomic::Species &species) const;
/**
* @brief Check if a species is involved in the QSE (algebraic) set.
* @param species The species to check.
* @return Boolean indicating if the species is in the algebraic set.
*/
bool involvesSpeciesInQSE(const fourdst::atomic::Species &species) const;
/**
* @brief Check if a species is involved in the dynamic set.
* @param species The species to check.
* @return Boolean indicating if the species is in the dynamic set.
*/
bool involvesSpeciesInDynamic(const fourdst::atomic::Species &species) const;
/**
* @brief Gets a normalized composition with QSE species equilibrated.
*
* @param comp The input composition.
* @param T9 Temperature in units of 10^9 K.
* @param rho Density in g/cm^3.
* @return A new `Composition` object with algebraic species set to their equilibrium values.
*
* @par Purpose
* To provide a way to get the equilibrated composition without modifying the internal state.
*
* @par How
* It calls `solveQSEAbundances()` to compute the equilibrium abundances for the algebraic species,
* then constructs a new `Composition` object reflecting these values.
*
* @pre The engine must have a valid QSE partition for the given state.
* @throws StaleEngineError If the QSE cache misses.
*/
fourdst::composition::Composition getNormalizedEquilibratedComposition(const fourdst::composition::CompositionAbstract& comp, double T9, double rho) const;
/**
@@ -563,9 +612,23 @@ namespace gridfire {
*/
fourdst::composition::Composition collectComposition(const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override;
/**
* @brief Gets the status of a species in the network.
*
* @param species The species to query.
* @return The `SpeciesStatus` indicating if the species is dynamic, algebraic, or not involved.
*
* @par Purpose
* To allow external queries about the role of a species in the partitioned network.
*
* @par How
* It checks for membership in `m_dynamic_species` and `m_algebraic_species` to determine
* the appropriate status.
*
* @pre `partitionNetwork()` must have been called.
*/
SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species &species) const override;
private:
/**
* @brief Struct representing a QSE group.
@@ -614,7 +677,16 @@ namespace gridfire {
*/
bool operator!=(const QSEGroup& other) const;
[[nodiscard]] [[maybe_unused]] std::string toString() const;
[[nodiscard]] [[maybe_unused]] std::string toString(bool verbose) const;
friend std::ostream& operator<<(std::ostream& os, const QSEGroup& group) {
os << group.toString(false);
return os;
}
bool contains(const fourdst::atomic::Species& species) const;
bool containsAlgebraic(const fourdst::atomic::Species &species) const;
bool containsSeed(const fourdst::atomic::Species &species) const;
};
class QSESolver {
@@ -642,7 +714,7 @@ namespace gridfire {
size_t solves() const;
void log_diagnostics() const;
void log_diagnostics(const QSEGroup &group, const fourdst::composition::Composition &comp) const;
private:
static int sys_func(
@@ -666,10 +738,15 @@ namespace gridfire {
fourdst::composition::Composition& comp;
const std::unordered_map<fourdst::atomic::Species, size_t>& qse_solve_species_index_map;
const std::vector<fourdst::atomic::Species>& qse_solve_species;
const QSESolver& instance;
};
private:
// Cache members
mutable size_t m_solves = 0;
mutable bool m_has_jacobian = false;
// Solver members
size_t m_N;
const DynamicEngine& m_engine;
std::vector<fourdst::atomic::Species> m_species;
@@ -692,6 +769,7 @@ namespace gridfire {
return LogManager::getInstance().getLogger("log");
}
};
struct FluxValidationResult {
@@ -743,7 +821,7 @@ namespace gridfire {
mutable std::unordered_map<uint64_t, fourdst::composition::Composition> m_composition_cache;
SUNContext m_sun_ctx = nullptr; // TODO: initialize and safely destroy this
SUNContext m_sun_ctx = nullptr;
private:
/**
@@ -770,6 +848,20 @@ namespace gridfire {
double rho
) const;
std::pair<bool, reaction::ReactionSet> group_is_a_qse_cluster(
const fourdst::composition::Composition &comp,
double T9,
double rho,
const QSEGroup &group
) const;
bool group_is_a_qse_pipeline(
const fourdst::composition::Composition &comp,
double T9,
double rho,
const QSEGroup &group
) const;
/**
* @brief Validates candidate QSE groups using flux analysis.
*

2
src/include/gridfire/engine/views/engine_priming.h
View File

@@ -10,7 +10,7 @@
#include <vector>
#include <string>
namespace gridfire {
namespace gridfire::engine {
/**
* @class NetworkPrimingEngineView

2
src/include/gridfire/engine/views/engine_view_abstract.h
View File

@@ -25,7 +25,7 @@
* Emily M. Boudreaux
*/
namespace gridfire {
namespace gridfire::engine {
/**
* @brief Concept for types allowed as engine bases in EngineView.