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

102
src/include/gridfire/engine/diagnostics/dynamic_engine_diagnostics.h
View File

@@ -1,3 +1,31 @@
/**
* @file dynamic_engine_diagnostics.h
* @brief Diagnostics utilities for DynamicEngine instances.
*
* These free functions provide diagnostic tools for analyzing and reporting
* on the behavior of DynamicEngine instances in GridFire. They include
* functions for identifying limiting species, inspecting species balance,
* and evaluating Jacobian stiffness. Generally these functions are expensive to call
* and should be avoided in performance-critical code paths or during large simulations.
* These are primarily intended for debugging and analysis during development.
*
* @section Functions
* - report_limiting_species: Identifies species that are limiting the
* accuracy of the integration based on specified tolerances.
* - inspect_species_balance: Analyzes the production and destruction rates
* of a specified species to identify imbalances.
* - inspect_jacobian_stiffness: Evaluates the stiffness of the Jacobian
* matrix to identify potential numerical issues.
* - save_jacobian_to_file: Saves the Jacobian matrix to a file for
* external analysis.
*
* @note Each of these functions, aside from save_jacobian_to_file, may return results in JSON format for easy
* integration with other tools and workflows. If the `json` parameter is set
* then the output will be formatted as JSON; otherwise, it will be printed
* to standard output and `std::nullopt` will be returned.
*/
#pragma once
#include "gridfire/engine/engine_abstract.h"
@@ -5,43 +33,77 @@
#include <vector>
#include <string>
namespace gridfire::diagnostics {
void report_limiting_species(
const DynamicEngine& engine,
const std::vector<double>& Y_full,
const std::vector<double>& E_full,
#include "nlohmann/json.hpp"
namespace gridfire::engine::diagnostics {
/**
* @brief Report the species that are limiting the accuracy of the integration. This is useful for identifying
* species that may be limiting the timestepping due to their high relative errors compared to the specified tolerances.
* @param engine Constant reference to the DynamicEngine instance.
* @param Y_full Vector of the current species molar abundances sorted in the same order as the dynamic engine species list.
* @param E_full Vector of the current species molar abundance errors sorted in the same order as the dynamic engine species list.
* @param relTol Relative tolerance for the integration.
* @param absTol Absolute tolerance for the integration.
* @param top_n The number of top limiting species to report. Default is 10.
* @param json Flag indicating whether to return the results in JSON format. If false, results are printed to standard output.
* @return std::optional<nlohmann::json> JSON object containing the limiting species report if `json` is true; otherwise, std::nullopt.
*/
std::optional<nlohmann::json> report_limiting_species(
const DynamicEngine &engine,
const std::vector<double> &Y_full,
const std::vector<double> &E_full,
double relTol,
double absTol,
size_t top_n = 10
size_t top_n = 10,
bool json = false
);
void inspect_species_balance(
/**
* @brief Inspect the production and destruction balance of a specific species in the reaction network. This function analyzes the reactions that create and destroy the specified species,
* providing insights into potential imbalances that may affect the accuracy of the simulation.
* @param engine Constant reference to the DynamicEngine instance.
* @param species_name The name of the species to inspect.
* @param comp The current composition of the system as a fourdst::composition::Composition object.
* @param T9 The temperature in GK (10^9 K).
* @param rho The density in g/cm^3.
* @param json Flag indicating whether to return the results in JSON format. If false, results are printed to standard output.
* @return std::optional<nlohmann::json> JSON object containing the species balance report if `json` is true; otherwise, std::nullopt.
*/
std::optional<nlohmann::json> inspect_species_balance(
const DynamicEngine& engine,
const std::string& species_name,
const fourdst::composition::Composition &comp,
double T9,
double rho
double rho,
bool json
);
void inspect_jacobian_stiffness(
const DynamicEngine& engine,
const fourdst::composition::Composition &comp,
double T9,
double rho
);
void inspect_jacobian_stiffness(
const DynamicEngine& engine,
/**
* @brief Inspect the stiffness of the Jacobian matrix for the reaction network at the given temperature and density. This function evaluates the diagonal and off-diagonal elements of the Jacobian to identify potential numerical issues related to stiffness.
* @param engine Constant reference to the DynamicEngine instance.
* @param comp The current composition of the system as a fourdst::composition::Composition object.
* @param T9 The temperature in GK (10^9 K).
* @param rho The density in g/cm^3.
* @param json Flag indicating whether to return the results in JSON format. If false, results are printed to standard output.
* @return std::optional<nlohmann::json> JSON object containing the Jacobian stiffness report if `json` is true; otherwise, std::nullopt.
*/
std::optional<nlohmann::json> inspect_jacobian_stiffness(
const DynamicEngine &engine,
const fourdst::composition::Composition &comp,
double T9,
double rho,
bool save,
const std::optional<std::string>& filename
bool json
);
/**
* @brief Save the Jacobian matrix to a file for external analysis.
* @param jacobian Constant reference to the NetworkJacobian instance to be saved.
* @param filename The name of the file where the Jacobian will be saved.
*/
void save_jacobian_to_file(
const NetworkJacobian& jacobian,
const std::string& filename
);
}
}

136
src/include/gridfire/engine/engine_abstract.h
View File

@@ -1,7 +1,7 @@
#pragma once
#include "gridfire/reaction/reaction.h"
#include "gridfire/network.h"
#include "gridfire/types/types.h"
#include "gridfire/screening/screening_abstract.h"
#include "gridfire/screening/screening_types.h"
@@ -9,8 +9,6 @@
#include "gridfire/engine/types/building.h"
#include "gridfire/engine/types/jacobian.h"
#include "gridfire/expectations/expected_engine.h"
#include "fourdst/composition/composition_abstract.h"
#include <vector>
@@ -31,16 +29,8 @@
* Emily M. Boudreaux
*/
namespace gridfire {
namespace gridfire::engine {
/**
* @brief Concept for types allowed in engine calculations.
*
* This concept restricts template parameters to either double or CppAD::AD<double>,
* enabling both standard and automatic differentiation types.
*/
template<typename T>
concept IsArithmeticOrAD = std::is_same_v<T, double> || std::is_same_v<T, CppAD::AD<double>>;
/**
* @brief Structure holding derivatives and energy generation for a network step.
@@ -68,8 +58,14 @@ namespace gridfire {
StepDerivatives() : dydt(), nuclearEnergyGenerationRate(T(0.0)) {}
};
using SparsityPattern = std::vector<std::pair<size_t, size_t>>;
using SparsityPattern = std::vector<std::pair<size_t, size_t>>; ///< Type alias for sparsity pattern representation.
/**
* @brief Structure holding derivatives of energy generation rate with respect to T and rho.
*
* This struct encapsulates the partial derivatives of the specific nuclear energy
* generation rate with respect to temperature and density.
*/
struct EnergyDerivatives {
double dEps_dT = 0.0; ///< Partial derivative of energy generation rate with respect to temperature.
double dEps_dRho = 0.0;///< Partial derivative of energy generation rate with respect to density.
@@ -80,6 +76,35 @@ namespace gridfire {
}
};
/**
* @brief Enumeration of possible engine statuses.
*
* This enum defines the various states an engine can be in after performing
* calculations, such as being up-to-date (OKAY), needing an update (STALE),
* or encountering an error (ERROR).
*/
enum class EngineStatus {
OKAY,
STALE,
ERROR,
COUNT
};
/**
* @brief Convert EngineStatus enum to string representation.
*
* @param status The EngineStatus value to convert.
* @return A string_view representing the name of the EngineStatus.
*/
constexpr std::string_view EngineStatus_to_string(const EngineStatus status) {
constexpr std::array<std::string_view, static_cast<size_t>(EngineStatus::COUNT)> names = {
"OKAY",
"STALE",
"ERROR"
};
return names[static_cast<size_t>(status)];
}
/**
* @brief Abstract base class for a reaction network engine.
*
@@ -123,7 +148,7 @@ namespace gridfire {
* time derivatives of all species and the specific nuclear energy generation
* rate for the current state.
*/
[[nodiscard]] virtual std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
[[nodiscard]] virtual std::expected<StepDerivatives<double>, EngineStatus> calculateRHSAndEnergy(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -142,7 +167,7 @@ namespace gridfire {
*
* Intended usage: Derive from this class to implement engines that support
* advanced solver features such as implicit integration, sensitivity analysis,
* QSE (Quasi-Steady-State Equilibrium) handling, and more.
* QSE (Quasi-Steady-State Equilibrium) handling, and more. Generally this will be the main engine type
*/
class DynamicEngine : public Engine {
public:
@@ -162,6 +187,18 @@ namespace gridfire {
double rho
) const = 0;
/**
* @brief Generate the Jacobian matrix for the current state using a subset of active species.
*
* @param comp Composition object containing current abundances.
* @param T9 Temperature in units of 10^9 K.
* @param rho Density in g/cm^3.
* @param activeSpecies The set of species to include in the Jacobian calculation.
*
* This method must compute and store the Jacobian matrix (∂(dY/dt)_i/∂Y_j)
* for the current state, considering only the specified subset of active species.
* The matrix can then be accessed via getJacobianMatrixEntry().
*/
[[nodiscard]] virtual NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
@@ -169,6 +206,22 @@ namespace gridfire {
const std::vector<fourdst::atomic::Species>& activeSpecies
) const = 0;
/**
* @brief Generate the Jacobian matrix for the current state with a specified sparsity pattern.
*
* @param comp Composition object containing current abundances.
* @param T9 Temperature in units of 10^9 K.
* @param rho Density in g/cm^3.
* @param sparsityPattern The sparsity pattern to use for the Jacobian matrix.
*
* This method must compute and store the Jacobian matrix (∂(dY/dt)_i/∂Y_j)
* for the current state using automatic differentiation, taking into
* account the provided sparsity pattern. The matrix can then be accessed
* via `getJacobianMatrixEntry()`.
*
* @see getJacobianMatrixEntry()
*/
[[nodiscard]] virtual NetworkJacobian generateJacobianMatrix(
const fourdst::composition::CompositionAbstract &comp,
double T9,
@@ -242,6 +295,15 @@ namespace gridfire {
*/
[[nodiscard]] virtual const reaction::ReactionSet& getNetworkReactions() const = 0;
/**
* @brief Set the reactions for the network.
*
* @param reactions The set of reactions to use in the network.
*
* This method replaces the current set of reactions in the network
* with the provided set. It marks the engine as stale, requiring
* regeneration of matrices and recalculation of rates.
*/
virtual void setNetworkReactions(const reaction::ReactionSet& reactions) = 0;
/**
@@ -255,13 +317,24 @@ namespace gridfire {
* This method estimates the timescale for abundance change of each species,
* 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(
[[nodiscard]] virtual std::expected<std::unordered_map<fourdst::atomic::Species, double>, EngineStatus> getSpeciesTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
) const = 0;
[[nodiscard]] virtual std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
/**
* @brief Compute destruction timescales for all 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 estimates the destruction timescale for each species,
* which can be useful for understanding reaction flows and equilibrium states.
*/
[[nodiscard]] virtual std::expected<std::unordered_map<fourdst::atomic::Species, double>, EngineStatus> getSpeciesDestructionTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho
@@ -289,6 +362,26 @@ namespace gridfire {
*/
virtual fourdst::composition::Composition update(const NetIn &netIn) = 0;
/**
* @brief Check if the engine's internal state is stale.
*
* @param netIn A struct containing the current network input, such as
* temperature, density, and composition.
* @return True if the engine's state is stale and needs to be updated; false otherwise.
*
* This method allows derived classes to determine if their internal state
* is out-of-date with respect to the provided network conditions. If the engine
* is stale, it may require a call to `update()` before performing calculations.
*
* @par Usage Example:
* @code
* NetIn input = { ... };
* if (myEngine.isStale(input)) {
* // Update the engine before proceeding
* }
* @endcode
*/
[[nodiscard]]
virtual bool isStale(const NetIn& netIn) = 0;
/**
@@ -405,6 +498,15 @@ namespace gridfire {
double rho
) const = 0;
/**
* @brief Get the status of a species in the network.
*
* @param species The species to check.
* @return SpeciesStatus indicating whether the species is active, inactive, or culled.
*
* This method allows querying the current status of a specific species
* within the engine's network.
*/
[[nodiscard]] virtual SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species& species) const = 0;
};

32
src/include/gridfire/engine/engine_graph.h
View File

@@ -5,7 +5,7 @@
#include "fourdst/logging/logging.h"
#include "fourdst/config/config.h"
#include "gridfire/network.h"
#include "gridfire/types/types.h"
#include "gridfire/reaction/reaction.h"
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/screening/screening_abstract.h"
@@ -33,7 +33,7 @@
// this makes extra copies of the species, which is not ideal and could be optimized further.
// Even more relevant is the member m_reactionIDMap which makes copies of a REACLIBReaction for each reaction ID.
// REACLIBReactions are quite large data structures, so this could be a performance bottleneck.
namespace gridfire {
namespace gridfire::engine {
/**
* @brief Alias for CppAD AD type for double precision.
*
@@ -150,7 +150,7 @@ namespace gridfire {
*
* @see StepDerivatives
*/
[[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
@@ -172,7 +172,7 @@ namespace gridfire {
*
* @see StepDerivatives
*/
[[nodiscard]] std::expected<StepDerivatives<double>, expectations::StaleEngineError> calculateRHSAndEnergy(
[[nodiscard]] std::expected<StepDerivatives<double>, EngineStatus> calculateRHSAndEnergy(
const fourdst::composition::CompositionAbstract& comp,
double T9,
double rho,
@@ -372,7 +372,8 @@ namespace gridfire {
* This method estimates the timescale for abundance change of each species,
* which can be used for timestep control or diagnostics.
*/
[[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
@@ -391,7 +392,7 @@ namespace gridfire {
* considering only the specified subset of reactions. This allows for flexible
* calculations with different reaction sets without modifying the engine's internal state.
*/
[[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,
@@ -410,7 +411,8 @@ namespace gridfire {
* This method estimates the destruction timescale for each species,
* which can be useful for understanding reaction flows and equilibrium states.
*/
[[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
@@ -429,7 +431,7 @@ namespace gridfire {
* considering only the specified subset of reactions. This allows for flexible
* calculations with different reaction sets without modifying the engine's internal state.
*/
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, expectations::StaleEngineError> getSpeciesDestructionTimescales(
[[nodiscard]] std::expected<std::unordered_map<fourdst::atomic::Species, double>, EngineStatus> getSpeciesDestructionTimescales(
const fourdst::composition::CompositionAbstract &comp,
double T9,
double rho,
@@ -450,6 +452,7 @@ namespace gridfire {
const NetIn &netIn
) override;
/**
* @brief Checks if the engine view is stale and needs to be updated.
*
@@ -739,6 +742,16 @@ 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 for which to get the status.
* @return SpeciesStatus indicating the status of the species.
*
* This method checks if the given species is part of the network and
* returns its status (e.g., Active, Inactive, NotFound).
*/
[[nodiscard]]
SpeciesStatus getSpeciesStatus(const fourdst::atomic::Species &species) const override;
@@ -854,6 +867,9 @@ namespace gridfire {
mutable CppAD::ADFun<double> m_rhsADFun; ///< CppAD function for the right-hand side of the ODE.
mutable CppAD::ADFun<double> m_epsADFun; ///< CppAD function for the energy generation rate.
mutable CppAD::sparse_jac_work m_jac_work; ///< Work object for sparse Jacobian calculations.
bool m_has_been_primed = false; ///< Flag indicating if the engine has been primed.
CppAD::sparse_rc<std::vector<size_t>> m_full_jacobian_sparsity_pattern; ///< Full sparsity pattern for the Jacobian matrix.
std::set<std::pair<size_t, size_t>> m_full_sparsity_set; ///< For quick lookups of the base sparsity pattern

56
src/include/gridfire/engine/procedures/construction.h
View File

@@ -1,3 +1,7 @@
/**
* @file construction.h
* @brief Functions for constructing nuclear reaction networks.
*/
#pragma once
#include "gridfire/reaction/reaction.h"
@@ -9,9 +13,14 @@
#include "gridfire/reaction/weak/weak_interpolator.h"
namespace gridfire {
namespace gridfire::engine {
/**
* @brief Flags to specify which types of nuclear reactions to include when constructing a reaction network.
*
* These flags allow fine-grained control over the inclusion of strong and weak nuclear reactions
* (beta decay, electron/positron capture) from various sources (Reaclib, WRL) during network construction.
* They can be combined using bitwise operations to create custom reaction sets.
*/
enum class NetworkConstructionFlags : uint32_t {
NONE = 0,
@@ -34,22 +43,63 @@ namespace gridfire {
ALL = STRONG | WRL_WEAK
};
/** @brief Helper function to convert NetworkConstructionFlags to their underlying integer type.
*
* This function facilitates bitwise operations on NetworkConstructionFlags by converting them
* to their underlying integer representation.
*
* @param f The NetworkConstructionFlags value to convert.
* @return The underlying integer representation of the flag.
*/
constexpr auto to_underlying(NetworkConstructionFlags f) noexcept {
return static_cast<std::underlying_type_t<NetworkConstructionFlags>>(f);
}
/** @brief Bitwise OR operator for NetworkConstructionFlags.
*
* This operator allows combining two NetworkConstructionFlags values using the bitwise OR operation.
*
* @param lhs The left-hand side NetworkConstructionFlags value.
* @param rhs The right-hand side NetworkConstructionFlags value.
* @return A new NetworkConstructionFlags value representing the combination of the two inputs.
*/
inline NetworkConstructionFlags operator|(const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs) {
return static_cast<NetworkConstructionFlags>(to_underlying(lhs) | to_underlying(rhs));
}
/** @brief Bitwise AND operator for NetworkConstructionFlags.
*
* This operator allows checking for common flags between two NetworkConstructionFlags values
* using the bitwise AND operation.
*
* @param lhs The left-hand side NetworkConstructionFlags value.
* @param rhs The right-hand side NetworkConstructionFlags value.
* @return A new NetworkConstructionFlags value representing the intersection of the two inputs.
*/
inline NetworkConstructionFlags operator&(const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs) {
return static_cast<NetworkConstructionFlags>(to_underlying(lhs) & to_underlying(rhs));
}
/** @brief Checks if a specific flag is set within a NetworkConstructionFlags value.
*
* This function determines whether a particular flag is present in a given NetworkConstructionFlags value.
*
* @param flags The NetworkConstructionFlags value to check.
* @param flag_to_check The specific flag to look for.
* @return True if the flag is set; otherwise, false.
*/
inline bool has_flag(const NetworkConstructionFlags flags, const NetworkConstructionFlags flag_to_check) {
return (flags & flag_to_check) != NetworkConstructionFlags::NONE;
}
/** @brief Converts NetworkConstructionFlags to a human-readable string.
*
* This function generates a comma-separated string representation of the set flags
* within a NetworkConstructionFlags value. If no flags are set, it returns "No reactions".
*
* @param flags The NetworkConstructionFlags value to convert.
* @return A string listing the set flags or "No reactions" if none are set.
*/
inline std::string NetworkConstructionFlagsToString(NetworkConstructionFlags flags) {
std::stringstream ss;
constexpr std::array<NetworkConstructionFlags, 6> bases_flags_array = {

4
src/include/gridfire/engine/procedures/priming.h
View File

@@ -2,12 +2,12 @@
#include "gridfire/engine/engine_abstract.h"
#include "gridfire/engine/engine_graph.h"
#include "gridfire/network.h"
#include "gridfire/types/types.h"
#include "fourdst/atomic/atomicSpecies.h"
namespace gridfire {
namespace gridfire::engine {
/**
* @brief Primes absent species in the network to their equilibrium abundances.

10
src/include/gridfire/engine/types/building.h
View File

@@ -1,8 +1,16 @@
/**
* @file building.h
* @brief Defines types related to building reaction networks in the GridFire engine.
*
* This file contains the enumeration and variant type used to specify the depth of reaction
* network construction within the GridFire simulation engine.
*
*/
#pragma once
#include <variant>
namespace gridfire {
namespace gridfire::engine {
/**
* @enum NetworkBuildDepth

25
src/include/gridfire/engine/types/engine_types.h
View File

@@ -1,9 +1,18 @@
#pragma once
#include "gridfire/engine/types/building.h"
#include "gridfire/engine/types/reporting.h"
namespace gridfire {
namespace gridfire::engine {
/**
* @enum EngineTypes
* @brief Enumeration of different engine types available in GridFire.
*
* Values:
* - GRAPH_ENGINE: The standard graph-based engine.
* - ADAPTIVE_ENGINE_VIEW: An engine that adapts based on certain criteria.
* - MULTISCALE_PARTITIONING_ENGINE_VIEW: An engine that partitions the system at multiple scales.
* - PRIMING_ENGINE_VIEW: An engine that uses a priming strategy for simulations.
* - DEFINED_ENGINE_VIEW: An engine defined by user specifications.
* - FILE_DEFINED_ENGINE_VIEW: An engine defined through external files.
*/
enum class EngineTypes {
GRAPH_ENGINE,
ADAPTIVE_ENGINE_VIEW,
@@ -13,7 +22,13 @@ namespace gridfire {
FILE_DEFINED_ENGINE_VIEW
};
inline std::string engine_type_to_string(const EngineTypes type) {
/**
* @brief Converts an EngineTypes enum value to its corresponding string representation.
*
* @param type The EngineTypes enum value to convert.
* @return A string_view representing the name of the engine type.
*/
constexpr std::string_view engine_type_to_string(const EngineTypes type) {
switch (type) {
case EngineTypes::GRAPH_ENGINE:
return "GraphEngine";

127
src/include/gridfire/engine/types/jacobian.h
View File

@@ -1,69 +1,175 @@
/**
* @file jacobian.h
* @brief Wrapper for handling the network Jacobian matrix in GridFire. Currently uses Eigen's SparseMatrix.
*/
#pragma once
#include "fourdst/atomic/atomicSpecies.h"
#include "fourdst/composition/composition_abstract.h"
#include "quill/Logger.h"
#include <Eigen/SparseCore>
#include <Eigen/SparseQR>
#include <tuple>
#include <functional>
#include <unordered_map>
#include <optional>
namespace gridfire {
constexpr double MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN = 1e-100;
using JacobianEntry = std::pair<std::pair<fourdst::atomic::Species, fourdst::atomic::Species>, double>;
namespace gridfire::engine {
constexpr double MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN = 1e-100; ///< Minimum abundance for a species to contribute to the Jacobian
using JacobianEntry = std::pair<std::pair<fourdst::atomic::Species, fourdst::atomic::Species>, double>; ///< Represents an entry in the Jacobian matrix
/**
* @class NetworkJacobian
* @brief A wrapper class for handling the network Jacobian matrix.
*
* This class encapsulates an Eigen::SparseMatrix to represent the Jacobian matrix of a reaction network.
* It provides methods for accessing and modifying matrix entries using species identifiers, as well as
* utility functions for analyzing the matrix (e.g., checking for singularity, counting non-zero entries).
*/
class NetworkJacobian {
public:
/**
* @brief Constructs a NetworkJacobian with the given sparse matrix and species index mapping function.
*
* @param jacobianMatrix The sparse matrix representing the Jacobian.
* @param indexToSpeciesFunc A function that maps matrix indices to species identifiers.
*/
explicit NetworkJacobian(
const Eigen::SparseMatrix<double>& jacobianMatrix,
const std::function<fourdst::atomic::Species(size_t)> &indexToSpeciesFunc
);
/**
* @brief Copy constructor for NetworkJacobian.
*
* @param jacobian The NetworkJacobian instance to copy from.
*/
NetworkJacobian(const NetworkJacobian& jacobian);
/**
* @brief Copy assignment operator for NetworkJacobian.
*
* @param jacobian The NetworkJacobian instance to copy from.
* @return Reference to the assigned NetworkJacobian instance.
*/
NetworkJacobian(NetworkJacobian&& jacobian) noexcept;
/**
* @brief Move constructor for NetworkJacobian.
*
* @param jacobian The NetworkJacobian instance to move from.
* @return Reference to the assigned NetworkJacobian instance.
*/
NetworkJacobian& operator=(NetworkJacobian&& jacobian) noexcept;
/**
* @brief Accesses the value at the specified row and column corresponding to the given species.
* @param row Species for the row
* @param col Species for the column
* @return value at the specified position
*/
double operator()(
const fourdst::atomic::Species& row,
const fourdst::atomic::Species& col
) const;
/**
* @brief Accesses the value at the specified row and column indices.
* @param i Row index
* @param j Column index
* @return value at the specified position
*/
double operator()(
size_t i,
size_t j
) const;
/**
* @brief Sets the value at the specified row and column corresponding to the given species.
* @param row Row species
* @param col Column species
* @param value Value to set
*/
void set(
const fourdst::atomic::Species& row,
const fourdst::atomic::Species& col,
double value
);
/**
* @brief Sets the value at the specified row and column indices.
* @param i Row index
* @param j Column index
* @param value Value to set
*/
void set(
size_t i,
size_t j,
double value
);
/**
* @brief Sets the value in the Jacobian matrix based on a JacobianEntry.
* @param entry The JacobianEntry containing row species, column species, and value.
*/
void set(
const JacobianEntry &entry
);
/**
* @brief Retrieves the shape of the Jacobian matrix as a tuple (rows, columns).
* @return A tuple containing the number of rows and columns.
*/
std::tuple<size_t, size_t> shape() const;
/**
* @brief Retrieves the rank of the Jacobian matrix.
* @return The rank of the matrix.
* @note Rank is computed using QR decomposition and cached for efficiency. The rank is computed the first time
* this method is called and stored for subsequent calls. If any set operation is performed on the matrix, the cached rank is invalidated.
*/
size_t rank() const;
/**
* @brief Get the number of non-zero entries in the Jacobian matrix.
* @return The number of non-zero entries.
*/
size_t nnz() const;
/**
* @brief Checks if the Jacobian matrix is singular.
* @return True if the matrix is singular, false otherwise.
*/
bool singular() const;
/**
* @brief Retrieves all entries in the Jacobian matrix that are infinite.
* @return A vector of JacobianEntry representing infinite entries.
*/
[[nodiscard]] std::vector<JacobianEntry> infs() const;
/**
* @brief Retrieves all entries in the Jacobian matrix that are NaN (Not a Number).
* @return A vector of JacobianEntry representing NaN entries.
*/
[[nodiscard]] std::vector<JacobianEntry> nans() const;
/**
* @brief Provides access to the underlying sparse matrix data.
* @return The Eigen::SparseMatrix representing the Jacobian.
*/
[[nodiscard]] Eigen::SparseMatrix<double> data() const;
/**
* @brief Provides access to the species-to-index mapping.
* @return A constant reference to the species-to-index mapping.
*/
[[nodiscard]] const std::unordered_map<fourdst::atomic::Species, size_t>& mapping() const;
/**
* @brief Exports the Jacobian matrix to a CSV file.
* @param filename The name of the CSV file to export to.
*/
void to_csv(const std::string& filename) const;
private:
@@ -73,6 +179,19 @@ namespace gridfire {
mutable std::optional<size_t> m_rank = std::nullopt;
};
/**
* @brief Regularizes the given Jacobian matrix based on the provided composition.
*
* This function applies regularization techniques to the Jacobian matrix to improve its numerical stability.
* Specifically any (row, column) entries corresponding to species who's abundance is below a threshold of
* MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN in the provided composition will be set to zero if those entries
* were either infinite or NaN.
*
* @param jacobian The NetworkJacobian to be regularized.
* @param comp The composition used for regularization.
* @param logger Optional logger for logging regularization steps and information.
* @return A new NetworkJacobian instance representing the regularized Jacobian matrix.
*/
NetworkJacobian regularize_jacobian(
const NetworkJacobian& jacobian,
const fourdst::composition::CompositionAbstract& comp,

23
src/include/gridfire/engine/types/reporting.h
View File

@@ -2,14 +2,11 @@
#include <map>
#include <string>
#include <vector>
#include <utility>
#include <ostream>
#include <sstream>
#include "fourdst/composition/composition.h"
#include "fourdst/atomic/atomicSpecies.h"
namespace gridfire {
namespace gridfire::engine {
/**
* @enum PrimingReportStatus
@@ -28,6 +25,7 @@ namespace gridfire {
*/
enum class PrimingReportStatus {
SUCCESS,
ALREADY_PRIMED,
SOLVER_FAILURE,
};
@@ -40,6 +38,7 @@ namespace gridfire {
inline std::map<PrimingReportStatus, std::string> PrimingReportStatusStrings = {
{PrimingReportStatus::SUCCESS, "SUCCESS"},
{PrimingReportStatus::SOLVER_FAILURE, "SOLVER_FAILURE"},
{PrimingReportStatus::ALREADY_PRIMED, "ALREADY_PRIMED"},
};
/**
@@ -78,6 +77,16 @@ namespace gridfire {
}
};
/**
* @enum SpeciesStatus
* @brief Enumerates the status of a species in the simulation.
*
* These status codes indicate the current state of a species:
* - ACTIVE: The species is actively participating in reactions.
* - EQUILIBRIUM: The species is in equilibrium and not changing concentration.
* - INACTIVE_FLOW: The species is present but not currently flowing.
* - NOT_PRESENT: The species is not present in the system.
*/
enum class SpeciesStatus {
ACTIVE,
EQUILIBRIUM,
@@ -85,6 +94,12 @@ namespace gridfire {
NOT_PRESENT
};
/**
* @brief Convert a SpeciesStatus enum value to its string representation.
*
* @param status The SpeciesStatus value to convert.
* @return A string representing the SpeciesStatus.
*/
inline std::string SpeciesStatus_to_string(const SpeciesStatus status) {
switch (status) {
case SpeciesStatus::ACTIVE:

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.