A reaction network engine that uses a graph-based representation. More...
#include <engine_graph.h>
Classes | |
| class | AtomicReverseRate |
| struct | constants |
| struct | PrecomputedReaction |
Public Member Functions | |
| GraphEngine (const fourdst::composition::Composition &composition, const BuildDepthType=NetworkBuildDepth::Full) | |
| Constructs a GraphEngine from a composition. | |
| GraphEngine (const fourdst::composition::Composition &composition, const partition::PartitionFunction &partitionFunction, const BuildDepthType buildDepth=NetworkBuildDepth::Full) | |
| GraphEngine (const reaction::LogicalReactionSet &reactions) | |
| Constructs a GraphEngine from a set of reactions. | |
| std::expected< StepDerivatives< double >, expectations::StaleEngineError > | calculateRHSAndEnergy (const std::vector< double > &Y, const double T9, const double rho) const override |
| Calculates the right-hand side (dY/dt) and energy generation rate. | |
| void | generateJacobianMatrix (const std::vector< double > &Y_dynamic, const double T9, const double rho) const override |
| Generates the Jacobian matrix for the current state. | |
| void | generateJacobianMatrix (const std::vector< double > &Y_dynamic, double T9, double rho, const SparsityPattern &sparsityPattern) const override |
| void | generateStoichiometryMatrix () override |
| Generates the stoichiometry matrix for the network. | |
| double | calculateMolarReactionFlow (const reaction::Reaction &reaction, const std::vector< double > &Y, const double T9, const double rho) const override |
| Calculates the molar reaction flow for a given reaction. | |
| const std::vector< fourdst::atomic::Species > & | getNetworkSpecies () const override |
| Gets the list of species in the network. | |
| const reaction::LogicalReactionSet & | getNetworkReactions () const override |
| Gets the set of logical reactions in the network. | |
| void | setNetworkReactions (const reaction::LogicalReactionSet &reactions) override |
| double | getJacobianMatrixEntry (const int i, const int j) const override |
| Gets an entry from the previously generated Jacobian matrix. | |
| int | getStoichiometryMatrixEntry (const int speciesIndex, const int reactionIndex) const override |
| Gets an entry from the stoichiometry matrix. | |
| std::expected< std::unordered_map< fourdst::atomic::Species, double >, expectations::StaleEngineError > | getSpeciesTimescales (const std::vector< double > &Y, double T9, double rho) const override |
| Computes timescales for all species in the network. | |
| std::expected< std::unordered_map< fourdst::atomic::Species, double >, expectations::StaleEngineError > | getSpeciesDestructionTimescales (const std::vector< double > &Y, double T9, double rho) const override |
| fourdst::composition::Composition | update (const NetIn &netIn) override |
| Update the internal state of the engine. | |
| bool | isStale (const NetIn &netIn) override |
| bool | involvesSpecies (const fourdst::atomic::Species &species) const |
| Checks if a given species is involved in the network. | |
| void | exportToDot (const std::string &filename) const |
| Exports the network to a DOT file for visualization. | |
| void | exportToCSV (const std::string &filename) const |
| Exports the network to a CSV file for analysis. | |
| void | setScreeningModel (screening::ScreeningType) override |
| Set the electron screening model. | |
| screening::ScreeningType | getScreeningModel () const override |
| Get the current electron screening model. | |
| void | setPrecomputation (bool precompute) |
| bool | isPrecomputationEnabled () const |
| const partition::PartitionFunction & | getPartitionFunction () const |
| double | calculateReverseRate (const reaction::Reaction &reaction, double T9) const |
| double | calculateReverseRateTwoBody (const reaction::Reaction &reaction, const double T9, const double forwardRate, const double expFactor) const |
| double | calculateReverseRateTwoBodyDerivative (const reaction::Reaction &reaction, const double T9, const double reverseRate) const |
| bool | isUsingReverseReactions () const |
| void | setUseReverseReactions (bool useReverse) |
| int | getSpeciesIndex (const fourdst::atomic::Species &species) const override |
| std::vector< double > | mapNetInToMolarAbundanceVector (const NetIn &netIn) const override |
| PrimingReport | primeEngine (const NetIn &netIn) override |
| BuildDepthType | getDepth () const override |
| void | rebuild (const fourdst::composition::Composition &comp, const BuildDepthType depth) override |
 Public Member Functions inherited from gridfire::Engine | |
| virtual | ~Engine ()=default |
| Virtual destructor. | |
Static Public Member Functions | |
| static std::unordered_map< fourdst::atomic::Species, int > | getNetReactionStoichiometry (const reaction::Reaction &reaction) |
| Gets the net stoichiometry for a given reaction. | |
Private Member Functions | |
| void | syncInternalMaps () |
| Synchronizes the internal maps. | |
| void | collectNetworkSpecies () |
| Collects the unique species in the network. | |
| void | populateReactionIDMap () |
| Populates the reaction ID map. | |
| void | populateSpeciesToIndexMap () |
| Populates the species-to-index map. | |
| void | reserveJacobianMatrix () const |
| Reserves space for the Jacobian matrix. | |
| void | recordADTape () |
| Records the AD tape for the right-hand side of the ODE. | |
| void | collectAtomicReverseRateAtomicBases () |
| void | precomputeNetwork () |
| bool | validateConservation () const |
| Validates mass and charge conservation across all reactions. | |
| StepDerivatives< double > | calculateAllDerivativesUsingPrecomputation (const std::vector< double > &Y_in, const std::vector< double > &bare_rates, const std::vector< double > &bare_reverse_rates, double T9, double rho) const |
| template<IsArithmeticOrAD T> | |
| T | calculateMolarReactionFlow (const reaction::Reaction &reaction, const std::vector< T > &Y, const T T9, const T rho) const |
| Calculates the molar reaction flow for a given reaction. | |
| template<IsArithmeticOrAD T> | |
| T | calculateReverseMolarReactionFlow (T T9, T rho, std::vector< T > screeningFactors, std::vector< T > Y, size_t reactionIndex, const reaction::LogicalReaction &reaction) const |
| template<IsArithmeticOrAD T> | |
| StepDerivatives< T > | calculateAllDerivatives (const std::vector< T > &Y_in, T T9, T rho) const |
| Calculates all derivatives (dY/dt) and the energy generation rate. | |
| StepDerivatives< double > | calculateAllDerivatives (const std::vector< double > &Y_in, const double T9, const double rho) const |
| Calculates all derivatives (dY/dt) and the energy generation rate (double precision). | |
| StepDerivatives< ADDouble > | calculateAllDerivatives (const std::vector< ADDouble > &Y_in, const ADDouble &T9, const ADDouble &rho) const |
| Calculates all derivatives (dY/dt) and the energy generation rate (automatic differentiation). | |
Private Attributes | |
| Config & | m_config = Config::getInstance() |
| quill::Logger * | m_logger = LogManager::getInstance().getLogger("log") |
| constants | m_constants |
| reaction::LogicalReactionSet | m_reactions |
| Set of REACLIB reactions in the network. | |
| std::unordered_map< std::string_view, reaction::Reaction * > | m_reactionIDMap |
| Map from reaction ID to REACLIBReaction. //PERF: This makes copies of REACLIBReaction and could be a performance bottleneck. | |
| std::vector< fourdst::atomic::Species > | m_networkSpecies |
| Vector of unique species in the network. | |
| std::unordered_map< std::string_view, fourdst::atomic::Species > | m_networkSpeciesMap |
| Map from species name to Species object. | |
| std::unordered_map< fourdst::atomic::Species, size_t > | m_speciesToIndexMap |
| Map from species to their index in the stoichiometry matrix. | |
| boost::numeric::ublas::compressed_matrix< int > | m_stoichiometryMatrix |
| Stoichiometry matrix (species x reactions). | |
| boost::numeric::ublas::compressed_matrix< double > | m_jacobianMatrix |
| Jacobian matrix (species x species). | |
| CppAD::ADFun< double > | m_rhsADFun |
| CppAD function for the right-hand side of the ODE. | |
| CppAD::sparse_jac_work | m_jac_work |
| Work object for sparse Jacobian calculations. | |
| CppAD::sparse_rc< std::vector< size_t > > | m_full_jacobian_sparsity_pattern |
| Full sparsity pattern for the Jacobian matrix. | |
| std::vector< std::unique_ptr< AtomicReverseRate > > | m_atomicReverseRates |
| screening::ScreeningType | m_screeningType = screening::ScreeningType::BARE |
| Screening type for the reaction network. Default to no screening. | |
| std::unique_ptr< screening::ScreeningModel > | m_screeningModel = screening::selectScreeningModel(m_screeningType) |
| bool | m_usePrecomputation = true |
| Flag to enable or disable using precomputed reactions for efficiency. Mathematically, this should not change the results. Generally end users should not need to change this. | |
| bool | m_useReverseReactions = true |
| Flag to enable or disable reverse reactions. If false, only forward reactions are considered. | |
| BuildDepthType | m_depth |
| std::vector< PrecomputedReaction > | m_precomputedReactions |
| Precomputed reactions for efficiency. | |
| std::unique_ptr< partition::PartitionFunction > | m_partitionFunction |
| Partition function for the network. | |
Detailed Description
A reaction network engine that uses a graph-based representation.
The GraphEngine class implements the DynamicEngine interface using a graph-based representation of the reaction network. It uses sparse matrices for efficient storage and computation of the stoichiometry and Jacobian matrices. Automatic differentiation (AD) is used to calculate the Jacobian matrix.
The engine supports:
- Calculation of the right-hand side (dY/dt) and energy generation rate.
- Generation and access to the Jacobian matrix.
- Generation and access to the stoichiometry matrix.
- Calculation of molar reaction flows.
- Access to the set of logical reactions in the network.
- Computation of timescales for each species.
- Exporting the network to DOT and CSV formats for visualization and analysis.
- See also
- engine_abstract.h
Constructor & Destructor Documentation
◆ GraphEngine() [1/3]
|
explicit |
Constructs a GraphEngine from a composition.
- Parameters
-
composition The composition of the material.
This constructor builds the reaction network from the given composition using the build_reaclib_nuclear_network function.
- See also
- build_reaclib_nuclear_network
◆ GraphEngine() [2/3]
|
explicit |
◆ GraphEngine() [3/3]
|
explicit |
Constructs a GraphEngine from a set of reactions.
- Parameters
-
reactions The set of reactions to use in the network.
This constructor uses the given set of reactions to construct the reaction network.
Member Function Documentation
◆ calculateAllDerivatives() [1/3]
|
nodiscardprivate |
Calculates all derivatives (dY/dt) and the energy generation rate (automatic differentiation).
- Parameters
-
Y_in Vector of current abundances for all species. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- StepDerivatives<ADDouble> containing dY/dt and energy generation rate.
This method calculates the time derivatives of all species and the specific nuclear energy generation rate for the current state using automatic differentiation.
◆ calculateAllDerivatives() [2/3]
|
nodiscardprivate |
Calculates all derivatives (dY/dt) and the energy generation rate (double precision).
- Parameters
-
Y_in Vector of current abundances for all species. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- StepDerivatives<double> containing dY/dt and energy generation rate.
This method calculates the time derivatives of all species and the specific nuclear energy generation rate for the current state using double precision arithmetic.
◆ calculateAllDerivatives() [3/3]
|
nodiscardprivate |
Calculates all derivatives (dY/dt) and the energy generation rate.
- Template Parameters
-
T The numeric type to use for the calculation.
- Parameters
-
Y_in Vector of current abundances for all species. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- StepDerivatives<T> containing dY/dt and energy generation rate.
This method calculates the time derivatives of all species and the specific nuclear energy generation rate for the current state.
◆ calculateAllDerivativesUsingPrecomputation()
|
nodiscardprivate |
◆ calculateMolarReactionFlow() [1/2]
|
nodiscardoverridevirtual |
Calculates the molar reaction flow for a given reaction.
- Parameters
-
reaction The reaction for which to calculate the flow. Y Vector of current abundances. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- Molar flow rate for the reaction (e.g., mol/g/s).
This method computes the net rate at which the given reaction proceeds under the current state.
Implements gridfire::DynamicEngine.
◆ calculateMolarReactionFlow() [2/2]
|
private |
Calculates the molar reaction flow for a given reaction.
- Template Parameters
-
T The numeric type to use for the calculation.
- Parameters
-
reaction The reaction for which to calculate the flow. Y Vector of current abundances. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- Molar flow rate for the reaction (e.g., mol/g/s).
This method computes the net rate at which the given reaction proceeds under the current state.
◆ calculateReverseMolarReactionFlow()
|
private |
◆ calculateReverseRate()
|
nodiscard |
◆ calculateReverseRateTwoBody()
|
nodiscard |
◆ calculateReverseRateTwoBodyDerivative()
|
nodiscard |
◆ calculateRHSAndEnergy()
|
nodiscardoverridevirtual |
Calculates the right-hand side (dY/dt) and energy generation rate.
- Parameters
-
Y Vector of current abundances for all species. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- StepDerivatives<double> containing dY/dt and energy generation rate.
This method calculates the time derivatives of all species and the specific nuclear energy generation rate for the current state.
- See also
- StepDerivatives
Implements gridfire::Engine.
◆ collectAtomicReverseRateAtomicBases()
|
private |
◆ collectNetworkSpecies()
|
private |
Collects the unique species in the network.
This method collects the unique species in the network from the reactants and products of all reactions.
◆ exportToCSV()
| void gridfire::GraphEngine::exportToCSV | ( | const std::string & | filename | ) | const |
Exports the network to a CSV file for analysis.
- Parameters
-
filename The name of the CSV file to create.
This method generates a CSV file containing information about the reactions in the network, including the reactants, products, Q-value, and reaction rate coefficients.
- Exceptions
-
std::runtime_error If the file cannot be opened for writing.
Example usage:
◆ exportToDot()
| void gridfire::GraphEngine::exportToDot | ( | const std::string & | filename | ) | const |
Exports the network to a DOT file for visualization.
- Parameters
-
filename The name of the DOT file to create.
This method generates a DOT file that can be used to visualize the reaction network as a graph. The DOT file can be converted to a graphical image using Graphviz.
- Exceptions
-
std::runtime_error If the file cannot be opened for writing.
Example usage:
◆ generateJacobianMatrix() [1/2]
|
overridevirtual |
Generates the Jacobian matrix for the current state.
- Parameters
-
Y_dynamic Vector of current abundances. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
This method computes and stores the Jacobian matrix (∂(dY/dt)_i/∂Y_j) for the current state using automatic differentiation. The matrix can then be accessed via getJacobianMatrixEntry().
- See also
- getJacobianMatrixEntry()
Implements gridfire::DynamicEngine.
◆ generateJacobianMatrix() [2/2]
|
overridevirtual |
Reimplemented from gridfire::DynamicEngine.
◆ generateStoichiometryMatrix()
|
overridevirtual |
Generates the stoichiometry matrix for the network.
This method computes and stores the stoichiometry matrix, which encodes the net change of each species in each reaction.
Implements gridfire::DynamicEngine.
◆ getDepth()
|
nodiscardoverridevirtual |
Reimplemented from gridfire::DynamicEngine.
◆ getJacobianMatrixEntry()
|
nodiscardoverridevirtual |
Gets an entry from the previously generated Jacobian matrix.
- Parameters
-
i Row index (species index). j Column index (species index).
- Returns
- Value of the Jacobian matrix at (i, j).
The Jacobian must have been generated by generateJacobianMatrix() before calling this.
- See also
- generateJacobianMatrix()
Implements gridfire::DynamicEngine.
◆ getNetReactionStoichiometry()
|
staticnodiscard |
Gets the net stoichiometry for a given reaction.
- Parameters
-
reaction The reaction for which to get the stoichiometry.
- Returns
- Map of species to their stoichiometric coefficients.
◆ getNetworkReactions()
|
nodiscardoverridevirtual |
Gets the set of logical reactions in the network.
- Returns
- Reference to the LogicalReactionSet containing all reactions.
Implements gridfire::DynamicEngine.
◆ getNetworkSpecies()
|
nodiscardoverridevirtual |
Gets the list of species in the network.
- Returns
- Vector of Species objects representing all network species.
Implements gridfire::Engine.
◆ getPartitionFunction()
|
nodiscard |
◆ getScreeningModel()
|
nodiscardoverridevirtual |
Get the current electron screening model.
- Returns
- The currently active screening model type.
- Usage Example:
- screening::ScreeningType currentModel = myEngine.getScreeningModel();ScreeningTypeEnumerates the available plasma screening models.Definition screening_types.h:15
Implements gridfire::DynamicEngine.
◆ getSpeciesDestructionTimescales()
|
nodiscardoverridevirtual |
Implements gridfire::DynamicEngine.
◆ getSpeciesIndex()
|
nodiscardoverridevirtual |
Implements gridfire::DynamicEngine.
◆ getSpeciesTimescales()
|
nodiscardoverridevirtual |
Computes timescales for all species in the network.
- Parameters
-
Y Vector of current abundances. T9 Temperature in units of 10^9 K. rho Density in g/cm^3.
- Returns
- Map from Species to their characteristic timescales (s).
This method estimates the timescale for abundance change of each species, which can be used for timestep control or diagnostics.
Implements gridfire::DynamicEngine.
◆ getStoichiometryMatrixEntry()
|
nodiscardoverridevirtual |
Gets an entry from the stoichiometry matrix.
- Parameters
-
speciesIndex Index of the species. reactionIndex Index of the reaction.
- Returns
- Stoichiometric coefficient for the species in the reaction.
The stoichiometry matrix must have been generated by generateStoichiometryMatrix().
- See also
- generateStoichiometryMatrix()
Implements gridfire::DynamicEngine.
◆ involvesSpecies()
|
nodiscard |
Checks if a given species is involved in the network.
- Parameters
-
species The species to check.
- Returns
- True if the species is involved in the network, false otherwise.
◆ isPrecomputationEnabled()
|
nodiscard |
◆ isStale()
|
overridevirtual |
Implements gridfire::DynamicEngine.
◆ isUsingReverseReactions()
|
nodiscard |
◆ mapNetInToMolarAbundanceVector()
|
nodiscardoverridevirtual |
Implements gridfire::DynamicEngine.
◆ populateReactionIDMap()
|
private |
Populates the reaction ID map.
This method populates the reaction ID map, which maps reaction IDs to REACLIBReaction objects.
◆ populateSpeciesToIndexMap()
|
private |
Populates the species-to-index map.
This method populates the species-to-index map, which maps species to their index in the stoichiometry matrix.
◆ precomputeNetwork()
|
private |
◆ primeEngine()
|
nodiscardoverridevirtual |
Implements gridfire::DynamicEngine.
◆ rebuild()
|
overridevirtual |
Reimplemented from gridfire::DynamicEngine.
◆ recordADTape()
|
private |
Records the AD tape for the right-hand side of the ODE.
This method records the AD tape for the right-hand side of the ODE, which is used to calculate the Jacobian matrix using automatic differentiation.
- Exceptions
-
std::runtime_error If there are no species in the network.
◆ reserveJacobianMatrix()
|
private |
Reserves space for the Jacobian matrix.
This method reserves space for the Jacobian matrix, which is used to store the partial derivatives of the right-hand side of the ODE with respect to the species abundances.
◆ setNetworkReactions()
|
overridevirtual |
Implements gridfire::DynamicEngine.
◆ setPrecomputation()
| void gridfire::GraphEngine::setPrecomputation | ( | bool | precompute | ) |
◆ setScreeningModel()
|
overridevirtual |
Set the electron screening model.
- Parameters
-
model The type of screening model to use for reaction rate calculations.
This method allows changing the screening model at runtime. Screening corrections account for the electrostatic shielding of nuclei by electrons, which affects reaction rates in dense stellar plasmas.
- Usage Example:
- myEngine.setScreeningModel(screening::ScreeningType::WEAK);@ WEAKWeak screening model (Salpeter, 1954).Definition screening_types.h:35
- Postcondition
- The engine will use the specified screening model for subsequent rate calculations.
Implements gridfire::DynamicEngine.
◆ setUseReverseReactions()
| void gridfire::GraphEngine::setUseReverseReactions | ( | bool | useReverse | ) |
◆ syncInternalMaps()
|
private |
Synchronizes the internal maps.
This method synchronizes the internal maps used by the engine, including the species map, reaction ID map, and species-to-index map. It also generates the stoichiometry matrix and records the AD tape.
◆ update()
|
overridevirtual |
Update the internal state of the engine.
- Parameters
-
netIn A struct containing the current network input, such as temperature, density, and composition.
This method is intended to be implemented by derived classes to update their internal state based on the provided network conditions. For example, an adaptive engine might use this to re-evaluate which reactions and species are active. For other engines that do not support manually updating, this method might do nothing.
- Usage Example:
- Postcondition
- The internal state of the engine is updated to reflect the new conditions.
Implements gridfire::DynamicEngine.
◆ validateConservation()
|
nodiscardprivate |
Validates mass and charge conservation across all reactions.
- Returns
- True if all reactions conserve mass and charge, false otherwise.
This method checks that all reactions in the network conserve mass and charge. If any reaction does not conserve mass or charge, an error message is logged and false is returned.
Member Data Documentation
◆ m_atomicReverseRates
|
private |
◆ m_config
|
private |
◆ m_constants
|
private |
◆ m_depth
|
private |
◆ m_full_jacobian_sparsity_pattern
|
private |
Full sparsity pattern for the Jacobian matrix.
◆ m_jac_work
|
mutableprivate |
Work object for sparse Jacobian calculations.
◆ m_jacobianMatrix
|
mutableprivate |
Jacobian matrix (species x species).
◆ m_logger
|
private |
◆ m_networkSpecies
|
private |
Vector of unique species in the network.
◆ m_networkSpeciesMap
|
private |
Map from species name to Species object.
◆ m_partitionFunction
|
private |
Partition function for the network.
◆ m_precomputedReactions
|
private |
Precomputed reactions for efficiency.
◆ m_reactionIDMap
|
private |
Map from reaction ID to REACLIBReaction. //PERF: This makes copies of REACLIBReaction and could be a performance bottleneck.
◆ m_reactions
|
private |
Set of REACLIB reactions in the network.
◆ m_rhsADFun
|
mutableprivate |
CppAD function for the right-hand side of the ODE.
◆ m_screeningModel
|
private |
◆ m_screeningType
|
private |
Screening type for the reaction network. Default to no screening.
◆ m_speciesToIndexMap
|
private |
Map from species to their index in the stoichiometry matrix.
◆ m_stoichiometryMatrix
|
private |
Stoichiometry matrix (species x reactions).
◆ m_usePrecomputation
|
private |
Flag to enable or disable using precomputed reactions for efficiency. Mathematically, this should not change the results. Generally end users should not need to change this.
◆ m_useReverseReactions
|
private |
Flag to enable or disable reverse reactions. If false, only forward reactions are considered.
The documentation for this class was generated from the following files:
- src/include/gridfire/engine/engine_graph.h
- src/lib/engine/engine_graph.cpp
