A reaction network engine that uses a graph-based representation. More...

#include <engine_graph.h>

Inheritance diagram for gridfire::engine::GraphEngine:

Collaboration diagram for gridfire::engine::GraphEngine:

Classes
class	AtomicReverseRate

struct	constants

struct	PrecomputationKernelResults

struct	PrecomputedReaction

Public Member Functions
	GraphEngine (const fourdst::composition::Composition &composition, BuildDepthType=NetworkBuildDepth::Full)
	Constructs a GraphEngine from a composition.

	GraphEngine (const fourdst::composition::Composition &composition, const partition::PartitionFunction &partitionFunction, BuildDepthType buildDepth=NetworkBuildDepth::Full)

	GraphEngine (const fourdst::composition::Composition &composition, const partition::PartitionFunction &partitionFunction, BuildDepthType buildDepth, NetworkConstructionFlags reactionTypes)

	GraphEngine (const reaction::ReactionSet &reactions)
	Constructs a GraphEngine from a set of reactions.

void	addReaction (const reaction::Reaction &reaction)

void	addReaction (const std::string &reaction_id)

std::unique_ptr< scratch::StateBlob >	constructStateBlob (const scratch::StateBlob *blob=nullptr) const override

std::expected< StepDerivatives< double >, engine::EngineStatus >	calculateRHSAndEnergy (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, bool trust) const override
	Calculates the right-hand side (dY/dt) and energy generation rate.

std::expected< StepDerivatives< double >, EngineStatus >	calculateRHSAndEnergy (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const reaction::ReactionSet &activeReactions) const
	Calculates the right-hand side (dY/dt) and energy generation rate for a subset of reactions.

EnergyDerivatives	calculateEpsDerivatives (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Calculates the derivatives of the energy generation rate with respect to temperature and density.

EnergyDerivatives	calculateEpsDerivatives (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const reaction::ReactionSet &activeReactions) const
	Calculates the derivatives of the energy generation rate with respect to temperature and density for a subset of reactions.

void	generate_jacobian_sparsity_pattern ()

NetworkJacobian	generateJacobianMatrix (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Generates the Jacobian matrix for the current state.

NetworkJacobian	generateJacobianMatrix (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const std::vector< fourdst::atomic::Species > &activeSpecies) const override
	Generates the Jacobian matrix for the current state with a specified set of active species. generally this will be much faster than the full matrix generation. Here we use forward mode to generate the Jacobian only for the active species.

NetworkJacobian	generateJacobianMatrix (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const SparsityPattern &sparsityPattern) const override
	Generates the Jacobian matrix for the current state with a specified sparsity pattern.

double	calculateMolarReactionFlow (scratch::StateBlob &, const reaction::Reaction &reaction, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Calculates the molar reaction flow for a given reaction.

const std::vector< fourdst::atomic::Species > &	getNetworkSpecies (scratch::StateBlob &ctx) const override
	Gets the list of species in the network.

const reaction::ReactionSet &	getNetworkReactions (scratch::StateBlob &) const override
	Gets the set of logical reactions in the network.

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus >	getSpeciesTimescales (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Computes timescales for all species in the network.

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus >	getSpeciesTimescales (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const reaction::ReactionSet &activeReactions) const
	Computes timescales for all species in the network considering a subset of reactions.

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus >	getSpeciesDestructionTimescales (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Computes destruction timescales for all species in the network.

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus >	getSpeciesDestructionTimescales (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const reaction::ReactionSet &activeReactions) const
	Computes destruction timescales for all species in the network considering a subset of reactions.

fourdst::composition::Composition	project (scratch::StateBlob &ctx, const NetIn &netIn) const override
	Updates the state of the network and the composition to be usable for the current network.

bool	involvesSpecies (scratch::StateBlob &ctx, const fourdst::atomic::Species &species) const
	Checks if a given species is involved in the network.

void	exportToDot (scratch::StateBlob &ctx, const std::string &filename) const
	Exports the network to a DOT file for visualization.

void	exportToCSV (scratch::StateBlob &ctx, const std::string &filename) const
	Exports the network to a CSV file for analysis.

screening::ScreeningType	getScreeningModel (scratch::StateBlob &ctx) const override
	Gets the current electron screening model.

bool	isPrecomputationEnabled (scratch::StateBlob &ctx) const
	Checks if precomputation of reaction rates is enabled.

const partition::PartitionFunction &	getPartitionFunction (scratch::StateBlob &ctx) const
	Gets the partition function used for reaction rate calculations.

double	calculateReverseRate (const reaction::Reaction &reaction, double T9, double rho, const fourdst::composition::CompositionAbstract &comp) const
	Calculates the reverse rate for a given reaction.

double	calculateReverseRateTwoBody (const reaction::Reaction &reaction, double T9, double forwardRate, double expFactor) const
	Calculates the reverse rate for a two-body reaction.

double	calculateReverseRateTwoBodyDerivative (const reaction::Reaction &reaction, double T9, double rho, const fourdst::composition::Composition &comp, double reverseRate) const
	Calculates the derivative of the reverse rate for a two-body reaction with respect to temperature.

bool	isUsingReverseReactions (scratch::StateBlob &ctx) const
	Checks if reverse reactions are enabled.

size_t	getSpeciesIndex (scratch::StateBlob &ctx, const fourdst::atomic::Species &species) const override
	Gets the index of a species in the network.

PrimingReport	primeEngine (scratch::StateBlob &ctx, const NetIn &netIn) const override
	Prepares the engine for calculations with initial conditions.

fourdst::composition::Composition	collectComposition (scratch::StateBlob &, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	This will return the input comp with the molar abundances of any species not registered in that but registered in the engine active species set to 0.0.

SpeciesStatus	getSpeciesStatus (scratch::StateBlob &, const fourdst::atomic::Species &species) const override
	Gets the status of a species in the network.

bool	get_store_intermediate_reaction_contributions () const

void	set_store_intermediate_reaction_contributions (const bool value)

std::optional< StepDerivatives< double > >	getMostRecentRHSCalculation (scratch::StateBlob &) const override

const CppAD::ADFun< double > &	getAuthoritativeADFun () const

template<IsArithmeticOrAD T>
StepDerivatives< T >	calculateAllDerivatives (const std::vector< T > &Y_in, const T T9, const T rho, const T Ye, const T mue, const std::function< std::optional< size_t >(const fourdst::atomic::Species &)> speciesLookup, const std::function< bool(const reaction::Reaction &)> &reactionLookup) const

Public Member Functions inherited from gridfire::engine::DynamicEngine
virtual reaction::ReactionSet	getInactiveNetworkReactions (scratch::StateBlob &ctx) const
	Get the set of inactive reactions in the network.

virtual double	getInactiveReactionMolarReactionFlow (scratch::StateBlob &ctx, const reaction::Reaction &reaction, const fourdst::composition::CompositionAbstract &comp, const double T9, const double rho) const

Public Member Functions inherited from gridfire::engine::Engine
virtual	~Engine ()=default
	Virtual destructor.

Private Types
enum class	JacobianMatrixState { UNINITIALIZED , STALE , READY_DENSE , READY_SPARSE }

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	recordADTape ()
	Records the AD tape for the right-hand side of the ODE.

void	collectAtomicReverseRateAtomicBases ()

void	precomputeNetwork ()

double	compute_reaction_flow (scratch::StateBlob &ctx, const std::vector< double > &local_abundances, const std::vector< double > &screening_factors, const std::vector< double > &bare_rates, const std::vector< double > &bare_reverse_rates, double rho, size_t reactionCounter, const reaction::Reaction &reaction, size_t reactionIndex, const PrecomputedReaction &precomputedReaction) const

std::pair< double, double >	compute_neutrino_fluxes (scratch::StateBlob &ctx, double netFlow, const reaction::Reaction &reaction) const

PrecomputationKernelResults	accumulate_flows_serial (scratch::StateBlob &ctx, const std::vector< double > &local_abundances, const std::vector< double > &screening_factors, const std::vector< double > &bare_rates, const std::vector< double > &bare_reverse_rates, double rho, const reaction::ReactionSet &activeReactions) const

StepDerivatives< double >	calculateAllDerivativesUsingPrecomputation (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, const std::vector< double > &bare_rates, const std::vector< double > &bare_reverse_rates, double T9, double rho, const reaction::ReactionSet &activeReactions) const

template<IsArithmeticOrAD T>
T	calculateMolarReactionFlow (const reaction::Reaction &reaction, const std::vector< T > &Y, T T9, T rho, T Ye, T mue, const std::function< std::optional< size_t >(const fourdst::atomic::Species &)> &speciesIDLookup) const
	Calculates the molar reaction flow for a given reaction.

template<IsArithmeticOrAD T>
T	calculateReverseMolarReactionFlow (T T9, T rho, std::vector< T > screeningFactors, const std::vector< T > &Y, size_t reactionIndex, const reaction::Reaction &reaction) const

template<IsArithmeticOrAD T>
StepDerivatives< T >	calculateAllDerivatives (const std::vector< T > &Y_in, T T9, T rho, T Ye, T mue, std::function< std::optional< size_t >(const fourdst::atomic::Species &)> speciesLookup, const std::function< bool(const reaction::Reaction &)> &reactionLookup) const
	Calculates all derivatives (dY/dt) and the energy generation rate.

Private Attributes
std::unordered_map< JacobianMatrixState, std::string >	m_jacobianMatrixStateNameMap

Config< config::GridFireConfig >	m_config

quill::Logger *	m_logger = LogManager::getInstance().getLogger("log")

constants	m_constants

rates::weak::WeakRateInterpolator	m_weakRateInterpolator
	Interpolator for weak reaction rates.

reaction::ReactionSet	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.

std::unordered_map< size_t, fourdst::atomic::Species >	m_indexToSpeciesMap
	Map from index to species in the stoichiometry matrix.

std::unique_ptr< partition::PartitionFunction >	m_partitionFunction
	Partition function for the network.

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.

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.

std::vector< PrecomputedReaction >	m_precomputed_reactions

std::unordered_map< uint64_t, size_t >	m_precomputed_reaction_index_map

bool	m_useReverseReactions = false
	Flag to enable or disable reverse reactions. If false, only forward reactions are considered.

bool	m_store_intermediate_reaction_contributions = false
	Flag to enable or disable storing intermediate reaction contributions for debugging.

BuildDepthType	m_depth

CppAD::ADFun< double >	m_authoritativeADFun

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

Member Enumeration Documentation

◆ JacobianMatrixState

enum class gridfire::engine::GraphEngine::JacobianMatrixState

strongprivate

Enumerator
UNINITIALIZED
STALE
READY_DENSE
READY_SPARSE

Constructor & Destructor Documentation

◆ GraphEngine() [1/4]

gridfire::engine::GraphEngine::GraphEngine	(	const fourdst::composition::Composition &	composition,
		BuildDepthType	buildDepth = NetworkBuildDepth::Full )

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/4]

gridfire::engine::GraphEngine::GraphEngine	(	const fourdst::composition::Composition &	composition,
		const partition::PartitionFunction &	partitionFunction,
		BuildDepthType	buildDepth = NetworkBuildDepth::Full )

explicit

◆ GraphEngine() [3/4]

gridfire::engine::GraphEngine::GraphEngine	(	const fourdst::composition::Composition &	composition,
		const partition::PartitionFunction &	partitionFunction,
		BuildDepthType	buildDepth,
		NetworkConstructionFlags	reactionTypes )

explicit

◆ GraphEngine() [4/4]

gridfire::engine::GraphEngine::GraphEngine ( const reaction::ReactionSet & reactions )

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

◆ accumulate_flows_serial()

GraphEngine::PrecomputationKernelResults gridfire::engine::GraphEngine::accumulate_flows_serial	(	scratch::StateBlob &	ctx,
		const std::vector< double > &	local_abundances,
		const std::vector< double > &	screening_factors,
		const std::vector< double > &	bare_rates,
		const std::vector< double > &	bare_reverse_rates,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

private

◆ addReaction() [1/2]

void gridfire::engine::GraphEngine::addReaction ( const reaction::Reaction & reaction )

◆ addReaction() [2/2]

void gridfire::engine::GraphEngine::addReaction ( const std::string & reaction_id )

◆ calculateAllDerivatives() [1/2]

template<IsArithmeticOrAD T>

StepDerivatives< T > gridfire::engine::GraphEngine::calculateAllDerivatives	(	const std::vector< T > &	Y_in,
		const T	T9,
		const T	rho,
		const T	Ye,
		const T	mue,
		const std::function< std::optional< size_t >(const fourdst::atomic::Species &)>	speciesLookup,
		const std::function< bool(const reaction::Reaction &)> &	reactionLookup ) const

◆ calculateAllDerivatives() [2/2]

template<IsArithmeticOrAD T>

StepDerivatives< T > gridfire::engine::GraphEngine::calculateAllDerivatives	(	const std::vector< T > &	Y_in,
		T	T9,
		T	rho,
		T	Ye,
		T	mue,
		std::function< std::optional< size_t >(const fourdst::atomic::Species &)>	speciesLookup,
		const std::function< bool(const reaction::Reaction &)> &	reactionLookup ) const

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 molar abundances for all species in the network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
Ye
mue
speciesLookup
reactionLookup

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()

StepDerivatives< double > gridfire::engine::GraphEngine::calculateAllDerivativesUsingPrecomputation	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		const std::vector< double > &	bare_rates,
		const std::vector< double > &	bare_reverse_rates,
		double	T9,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

nodiscardprivate

◆ calculateEpsDerivatives() [1/2]

EnergyDerivatives gridfire::engine::GraphEngine::calculateEpsDerivatives	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Calculates the derivatives of the energy generation rate with respect to temperature and density.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: EnergyDerivatives struct containing the derivatives.

This method computes the partial derivatives of the specific nuclear energy generation rate with respect to temperature (∂ε/∂T) and density (∂ε/∂ρ)

See also: EnergyDerivatives

Implements gridfire::engine::DynamicEngine.

◆ calculateEpsDerivatives() [2/2]

EnergyDerivatives gridfire::engine::GraphEngine::calculateEpsDerivatives	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

nodiscard

Calculates the derivatives of the energy generation rate with respect to temperature and density for a subset of reactions.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
activeReactions	The set of reactions to include in the calculation.

Returns: EnergyDerivatives struct containing the derivatives.

This method computes the partial derivatives of the specific nuclear energy generation rate with respect to temperature (∂ε/∂T) and density (∂ε/∂ρ) considering only the specified subset of reactions. This allows for flexible calculations with different reaction sets without modifying the engine's internal state.

See also: EnergyDerivatives

◆ calculateMolarReactionFlow() [1/2]

template<IsArithmeticOrAD T>

T gridfire::engine::GraphEngine::calculateMolarReactionFlow	(	const reaction::Reaction &	reaction,
		const std::vector< T > &	Y,
		T	T9,
		T	rho,
		T	Ye,
		T	mue,
		const std::function< std::optional< size_t >(const fourdst::atomic::Species &)> &	speciesIDLookup ) const

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 molar abundances for all species in the network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
Ye
mue
speciesIDLookup

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.

◆ calculateMolarReactionFlow() [2/2]

double gridfire::engine::GraphEngine::calculateMolarReactionFlow	(	scratch::StateBlob &	ctx,
		const reaction::Reaction &	reaction,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Calculates the molar reaction flow for a given reaction.

Parameters

reaction	The reaction for which to calculate the flow.
comp	Composition object containing 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::engine::DynamicEngine.

◆ calculateReverseMolarReactionFlow()

template<IsArithmeticOrAD T>

T gridfire::engine::GraphEngine::calculateReverseMolarReactionFlow	(	T	T9,
		T	rho,
		std::vector< T >	screeningFactors,
		const std::vector< T > &	Y,
		size_t	reactionIndex,
		const reaction::Reaction &	reaction ) const

private

◆ calculateReverseRate()

double gridfire::engine::GraphEngine::calculateReverseRate	(	const reaction::Reaction &	reaction,
		double	T9,
		double	rho,
		const fourdst::composition::CompositionAbstract &	comp ) const

nodiscard

Calculates the reverse rate for a given reaction.

Parameters

reaction	The reaction for which to calculate the reverse rate.
T9	Temperature in units of 10^9 K.
rho
comp	Composition object containing current abundances.

Returns: Reverse rate for the reaction (e.g., mol/g/s).

This method computes the reverse rate based on the forward rate and thermodynamic properties of the reaction.

◆ calculateReverseRateTwoBody()

double gridfire::engine::GraphEngine::calculateReverseRateTwoBody	(	const reaction::Reaction &	reaction,
		double	T9,
		double	forwardRate,
		double	expFactor ) const

nodiscard

Calculates the reverse rate for a two-body reaction.

Parameters

reaction	The reaction for which to calculate the reverse rate.
T9	Temperature in units of 10^9 K.
forwardRate	The forward rate of the reaction.
expFactor	Exponential factor for the reaction.

Returns: Reverse rate for the two-body reaction (e.g., mol/g/s).

This method computes the reverse rate using the forward rate and thermodynamic properties of the reaction.

◆ calculateReverseRateTwoBodyDerivative()

double gridfire::engine::GraphEngine::calculateReverseRateTwoBodyDerivative	(	const reaction::Reaction &	reaction,
		double	T9,
		double	rho,
		const fourdst::composition::Composition &	comp,
		double	reverseRate ) const

nodiscard

Calculates the derivative of the reverse rate for a two-body reaction with respect to temperature.

Parameters

reaction	The reaction for which to calculate the derivative.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
comp	Composition object containing current abundances.
reverseRate	The reverse rate of the reaction.

Returns: Derivative of the reverse rate with respect to temperature.

This method computes the derivative of the reverse rate using automatic differentiation.

◆ calculateRHSAndEnergy() [1/2]

std::expected< StepDerivatives< double >, EngineStatus > gridfire::engine::GraphEngine::calculateRHSAndEnergy	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		bool	trust ) const

nodiscardoverridevirtual

Calculates the right-hand side (dY/dt) and energy generation rate.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
trust

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::Engine.

◆ calculateRHSAndEnergy() [2/2]

std::expected< StepDerivatives< double >, EngineStatus > gridfire::engine::GraphEngine::calculateRHSAndEnergy	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

nodiscard

Calculates the right-hand side (dY/dt) and energy generation rate for a subset of reactions.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
activeReactions	The set of reactions to include in the calculation.

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 considering only the specified subset of reactions. This allows for flexible calculations with different reaction sets without modifying the engine's internal state.

See also: StepDerivatives

◆ collectAtomicReverseRateAtomicBases()

void gridfire::engine::GraphEngine::collectAtomicReverseRateAtomicBases ( )

private

◆ collectComposition()

fourdst::composition::Composition gridfire::engine::GraphEngine::collectComposition	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

overridevirtual

This will return the input comp with the molar abundances of any species not registered in that but registered in the engine active species set to 0.0.

Note: Effectively this method does not change input composition; rather it ensures that all species which can be tracked by an instance of GraphEngine are registered in the composition object.; If a species is in the input comp but not in the network

Parameters

comp	Input Composition
T9
rho
T9
rho

Returns: A new composition where all members of the active species set are registered. And any members not in comp have a molar abundance set to 0.

Exceptions

BadCollectionError If the input composition contains species not present in the network species set

Implements gridfire::engine::DynamicEngine.

◆ collectNetworkSpecies()

void gridfire::engine::GraphEngine::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.

◆ compute_neutrino_fluxes()

std::pair< double, double > gridfire::engine::GraphEngine::compute_neutrino_fluxes	(	scratch::StateBlob &	ctx,
		double	netFlow,
		const reaction::Reaction &	reaction ) const

private

◆ compute_reaction_flow()

double gridfire::engine::GraphEngine::compute_reaction_flow	(	scratch::StateBlob &	ctx,
		const std::vector< double > &	local_abundances,
		const std::vector< double > &	screening_factors,
		const std::vector< double > &	bare_rates,
		const std::vector< double > &	bare_reverse_rates,
		double	rho,
		size_t	reactionCounter,
		const reaction::Reaction &	reaction,
		size_t	reactionIndex,
		const PrecomputedReaction &	precomputedReaction ) const

private

◆ constructStateBlob()

std::unique_ptr< scratch::StateBlob > gridfire::engine::GraphEngine::constructStateBlob ( const scratch::StateBlob * blob = nullptr ) const

overridevirtual

Implements gridfire::engine::DynamicEngine.

◆ exportToCSV()

void gridfire::engine::GraphEngine::exportToCSV	(	scratch::StateBlob &	ctx,
		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:

engine.exportToCSV("network.csv");

gridfire::engine

Definition dynamic_engine_diagnostics.h:39

◆ exportToDot()

void gridfire::engine::GraphEngine::exportToDot	(	scratch::StateBlob &	ctx,
		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:

engine.exportToDot("network.dot");

◆ generate_jacobian_sparsity_pattern()

void gridfire::engine::GraphEngine::generate_jacobian_sparsity_pattern ( )

◆ generateJacobianMatrix() [1/3]

NetworkJacobian gridfire::engine::GraphEngine::generateJacobianMatrix	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Generates the Jacobian matrix for the current state.

Parameters

comp	Composition object containing 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::engine::DynamicEngine.

◆ generateJacobianMatrix() [2/3]

NetworkJacobian gridfire::engine::GraphEngine::generateJacobianMatrix	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const SparsityPattern &	sparsityPattern ) const

nodiscardoverridevirtual

Generates the Jacobian matrix for the current state with a specified sparsity pattern.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
sparsityPattern	The sparsity pattern to use for the Jacobian matrix.

This method computes and stores 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 also: getJacobianMatrixEntry()

Implements gridfire::engine::DynamicEngine.

◆ generateJacobianMatrix() [3/3]

NetworkJacobian gridfire::engine::GraphEngine::generateJacobianMatrix	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const std::vector< fourdst::atomic::Species > &	activeSpecies ) const

nodiscardoverridevirtual

Generates the Jacobian matrix for the current state with a specified set of active species. generally this will be much faster than the full matrix generation. Here we use forward mode to generate the Jacobian only for the active species.

Parameters

comp	The Composition object containing current abundances.
T9	The temperature in units of 10^9 K.
rho	The density in g/cm^3.
activeSpecies	A vector of Species objects representing the active species.

See also: getJacobianMatrixEntry(); generateJacobianMatrix()

Implements gridfire::engine::DynamicEngine.

◆ get_store_intermediate_reaction_contributions()

bool gridfire::engine::GraphEngine::get_store_intermediate_reaction_contributions ( ) const

inlinenodiscard

◆ getAuthoritativeADFun()

const CppAD::ADFun< double > & gridfire::engine::GraphEngine::getAuthoritativeADFun ( ) const

inlinenodiscard

◆ getMostRecentRHSCalculation()

std::optional< StepDerivatives< double > > gridfire::engine::GraphEngine::getMostRecentRHSCalculation ( scratch::StateBlob & ctx ) const

nodiscardoverridevirtual

Implements gridfire::engine::DynamicEngine.

◆ getNetworkReactions()

const reaction::ReactionSet & gridfire::engine::GraphEngine::getNetworkReactions ( scratch::StateBlob & ctx ) const

nodiscardoverridevirtual

Gets the set of logical reactions in the network.

Returns: Reference to the LogicalReactionSet containing all reactions.

Implements gridfire::engine::DynamicEngine.

◆ getNetworkSpecies()

const std::vector< fourdst::atomic::Species > & gridfire::engine::GraphEngine::getNetworkSpecies ( scratch::StateBlob & ctx ) const

nodiscardoverridevirtual

Gets the list of species in the network.

Returns: Vector of Species objects representing all network species.

Implements gridfire::engine::Engine.

◆ getPartitionFunction()

const partition::PartitionFunction & gridfire::engine::GraphEngine::getPartitionFunction ( scratch::StateBlob & ctx ) const

nodiscard

Gets the partition function used for reaction rate calculations.

Returns: Reference to the PartitionFunction object.

This method provides access to the partition function used in the engine, which is essential for calculating thermodynamic properties and reaction rates.

◆ getScreeningModel()

screening::ScreeningType gridfire::engine::GraphEngine::getScreeningModel ( scratch::StateBlob & ctx ) const

nodiscardoverridevirtual

Gets the current electron screening model.

Returns: The currently active screening model type.

Example usage:

screening::ScreeningType currentModel = engine.getScreeningModel();

gridfire::screening::ScreeningType

ScreeningType

Enumerates the available plasma screening models.

Definition screening_types.h:15

Implements gridfire::engine::DynamicEngine.

◆ getSpeciesDestructionTimescales() [1/2]

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus > gridfire::engine::GraphEngine::getSpeciesDestructionTimescales	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Computes destruction timescales for all species in the network.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: 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.

Implements gridfire::engine::DynamicEngine.

◆ getSpeciesDestructionTimescales() [2/2]

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus > gridfire::engine::GraphEngine::getSpeciesDestructionTimescales	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

nodiscard

Computes destruction timescales for all species in the network considering a subset of reactions.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
activeReactions	The set of reactions to include in the calculation.

Returns: Map from Species to their destruction timescales (s).

This method estimates the destruction timescale for each species, considering only the specified subset of reactions. This allows for flexible calculations with different reaction sets without modifying the engine's internal state.

◆ getSpeciesIndex()

size_t gridfire::engine::GraphEngine::getSpeciesIndex	(	scratch::StateBlob &	ctx,
		const fourdst::atomic::Species &	species ) const

nodiscardoverridevirtual

Gets the index of a species in the network.

Parameters

species The species for which to get the index.

Returns: Index of the species in the network, or -1 if not found.

This method returns the index of the given species in the network's species vector. If the species is not found, it returns -1.

Implements gridfire::engine::DynamicEngine.

◆ getSpeciesStatus()

SpeciesStatus gridfire::engine::GraphEngine::getSpeciesStatus	(	scratch::StateBlob &	ctx,
		const fourdst::atomic::Species &	species ) const

nodiscardoverridevirtual

Gets the status of a species in the network.

Parameters

species The species for which to get the status.

Returns: 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).

Implements gridfire::engine::DynamicEngine.

◆ getSpeciesTimescales() [1/2]

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus > gridfire::engine::GraphEngine::getSpeciesTimescales	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Computes timescales for all species in the network.

Parameters

comp	Composition object containing 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::engine::DynamicEngine.

◆ getSpeciesTimescales() [2/2]

std::expected< std::unordered_map< fourdst::atomic::Species, double >, EngineStatus > gridfire::engine::GraphEngine::getSpeciesTimescales	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		const reaction::ReactionSet &	activeReactions ) const

nodiscard

Computes timescales for all species in the network considering a subset of reactions.

Parameters

comp	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
activeReactions	The set of reactions to include in the calculation.

Returns: Map from Species to their characteristic timescales (s).

This method estimates the timescale for abundance change of each species, considering only the specified subset of reactions. This allows for flexible calculations with different reaction sets without modifying the engine's internal state.

◆ involvesSpecies()

bool gridfire::engine::GraphEngine::involvesSpecies	(	scratch::StateBlob &	ctx,
		const fourdst::atomic::Species &	species ) const

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()

bool gridfire::engine::GraphEngine::isPrecomputationEnabled ( scratch::StateBlob & ctx ) const

nodiscard

Checks if precomputation of reaction rates is enabled.

Returns: True if precomputation is enabled, false otherwise.

This method allows checking the current state of precomputation for reaction rates in the engine.

◆ isUsingReverseReactions()

bool gridfire::engine::GraphEngine::isUsingReverseReactions ( scratch::StateBlob & ctx ) const

nodiscard

Checks if reverse reactions are enabled.

Returns: True if reverse reactions are enabled, false otherwise.

This method allows checking whether the engine is configured to use reverse reactions in its calculations.

◆ populateReactionIDMap()

void gridfire::engine::GraphEngine::populateReactionIDMap ( )

private

Populates the reaction ID map.

This method populates the reaction ID map, which maps reaction IDs to REACLIBReaction objects.

◆ populateSpeciesToIndexMap()

void gridfire::engine::GraphEngine::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()

void gridfire::engine::GraphEngine::precomputeNetwork ( )

private

◆ primeEngine()

PrimingReport gridfire::engine::GraphEngine::primeEngine	(	scratch::StateBlob &	ctx,
		const NetIn &	netIn ) const

nodiscardoverridevirtual

Prepares the engine for calculations with initial conditions.

Parameters

netIn The input conditions for the network.

Returns: PrimingReport containing information about the priming process.

This method initializes the engine with the provided input conditions, setting up reactions, species, and precomputing necessary data.

Implements gridfire::engine::DynamicEngine.

◆ project()

fourdst::composition::Composition gridfire::engine::GraphEngine::project	(	scratch::StateBlob &	ctx,
		const NetIn &	netIn ) const

overridevirtual

Updates the state of the network and the composition to be usable for the current network.

For graph engine all this does is ensure that the returned composition has all the species in the network registered. if a species was already in the composition is will keep its abundance, otherwise it will be added with zero abundance.

Parameters

netIn The input netIn to use, this includes the composition, temperature, and density

Returns: The updated composition that includes all species in the network.

Implements gridfire::engine::DynamicEngine.

◆ recordADTape()

void gridfire::engine::GraphEngine::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.

◆ set_store_intermediate_reaction_contributions()

void gridfire::engine::GraphEngine::set_store_intermediate_reaction_contributions ( const bool value )

inline

◆ syncInternalMaps()

void gridfire::engine::GraphEngine::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.

Member Data Documentation

◆ m_atomicReverseRates

std::vector<std::unique_ptr<AtomicReverseRate> > gridfire::engine::GraphEngine::m_atomicReverseRates

private

◆ m_authoritativeADFun

CppAD::ADFun<double> gridfire::engine::GraphEngine::m_authoritativeADFun

private

◆ m_config

Config<config::GridFireConfig> gridfire::engine::GraphEngine::m_config

private

◆ m_constants

constants gridfire::engine::GraphEngine::m_constants

private

◆ m_depth

BuildDepthType gridfire::engine::GraphEngine::m_depth

private

◆ m_full_jacobian_sparsity_pattern

CppAD::sparse_rc<std::vector<size_t> > gridfire::engine::GraphEngine::m_full_jacobian_sparsity_pattern

private

Full sparsity pattern for the Jacobian matrix.

◆ m_full_sparsity_set

std::set<std::pair<size_t, size_t> > gridfire::engine::GraphEngine::m_full_sparsity_set

private

For quick lookups of the base sparsity pattern.

◆ m_indexToSpeciesMap

std::unordered_map<size_t, fourdst::atomic::Species> gridfire::engine::GraphEngine::m_indexToSpeciesMap

private

Map from index to species in the stoichiometry matrix.

◆ m_jacobianMatrixStateNameMap

std::unordered_map<JacobianMatrixState, std::string> gridfire::engine::GraphEngine::m_jacobianMatrixStateNameMap

private

Initial value:

= {
            {JacobianMatrixState::UNINITIALIZED, "Uninitialized"},
            {JacobianMatrixState::STALE, "Stale"},
            {JacobianMatrixState::READY_DENSE, "Ready (dense)"},
            {JacobianMatrixState::READY_SPARSE, "Ready (sparse)"},
        }

◆ m_logger

quill::Logger* gridfire::engine::GraphEngine::m_logger = LogManager::getInstance().getLogger("log")

private

◆ m_networkSpecies

std::vector<fourdst::atomic::Species> gridfire::engine::GraphEngine::m_networkSpecies

private

Vector of unique species in the network.

◆ m_networkSpeciesMap

std::unordered_map<std::string_view, fourdst::atomic::Species> gridfire::engine::GraphEngine::m_networkSpeciesMap

private

Map from species name to Species object.

◆ m_partitionFunction

std::unique_ptr<partition::PartitionFunction> gridfire::engine::GraphEngine::m_partitionFunction

private

Partition function for the network.

◆ m_precomputed_reaction_index_map

std::unordered_map<uint64_t, size_t> gridfire::engine::GraphEngine::m_precomputed_reaction_index_map

private

◆ m_precomputed_reactions

std::vector<PrecomputedReaction> gridfire::engine::GraphEngine::m_precomputed_reactions

private

◆ m_reactionIDMap

std::unordered_map<std::string_view, reaction::Reaction*> gridfire::engine::GraphEngine::m_reactionIDMap

private

Map from reaction ID to REACLIBReaction. //PERF: This makes copies of REACLIBReaction and could be a performance bottleneck.

◆ m_reactions

reaction::ReactionSet gridfire::engine::GraphEngine::m_reactions

private

Set of REACLIB reactions in the network.

◆ m_screeningModel

std::unique_ptr<screening::ScreeningModel> gridfire::engine::GraphEngine::m_screeningModel = screening::selectScreeningModel(m_screeningType)

private

◆ m_screeningType

screening::ScreeningType gridfire::engine::GraphEngine::m_screeningType = screening::ScreeningType::BARE

private

Screening type for the reaction network. Default to no screening.

◆ m_speciesToIndexMap

std::unordered_map<fourdst::atomic::Species, size_t> gridfire::engine::GraphEngine::m_speciesToIndexMap

private

Map from species to their index in the stoichiometry matrix.

◆ m_store_intermediate_reaction_contributions

bool gridfire::engine::GraphEngine::m_store_intermediate_reaction_contributions = false

private

Flag to enable or disable storing intermediate reaction contributions for debugging.

◆ m_usePrecomputation

bool gridfire::engine::GraphEngine::m_usePrecomputation = true

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

bool gridfire::engine::GraphEngine::m_useReverseReactions = false

private

Flag to enable or disable reverse reactions. If false, only forward reactions are considered.

◆ m_weakRateInterpolator

rates::weak::WeakRateInterpolator gridfire::engine::GraphEngine::m_weakRateInterpolator

private

Interpolator for weak reaction rates.

The documentation for this class was generated from the following files:

src/include/gridfire/engine/engine_graph.h
src/lib/engine/engine_graph.cpp

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ JacobianMatrixState

Constructor & Destructor Documentation

◆ GraphEngine() [1/4]

◆ GraphEngine() [2/4]

◆ GraphEngine() [3/4]

◆ GraphEngine() [4/4]

Member Function Documentation

◆ accumulate_flows_serial()

◆ addReaction() [1/2]

◆ addReaction() [2/2]

◆ calculateAllDerivatives() [1/2]

◆ calculateAllDerivatives() [2/2]

◆ calculateAllDerivativesUsingPrecomputation()

◆ calculateEpsDerivatives() [1/2]

◆ calculateEpsDerivatives() [2/2]

◆ calculateMolarReactionFlow() [1/2]

◆ calculateMolarReactionFlow() [2/2]

◆ calculateReverseMolarReactionFlow()

◆ calculateReverseRate()

◆ calculateReverseRateTwoBody()

◆ calculateReverseRateTwoBodyDerivative()

◆ calculateRHSAndEnergy() [1/2]

◆ calculateRHSAndEnergy() [2/2]

◆ collectAtomicReverseRateAtomicBases()

◆ collectComposition()

◆ collectNetworkSpecies()

◆ compute_neutrino_fluxes()

◆ compute_reaction_flow()

◆ constructStateBlob()

◆ exportToCSV()

◆ exportToDot()

◆ generate_jacobian_sparsity_pattern()

◆ generateJacobianMatrix() [1/3]

◆ generateJacobianMatrix() [2/3]

◆ generateJacobianMatrix() [3/3]

◆ get_store_intermediate_reaction_contributions()

◆ getAuthoritativeADFun()

◆ getMostRecentRHSCalculation()

◆ getNetworkReactions()

◆ getNetworkSpecies()

◆ getPartitionFunction()

◆ getScreeningModel()

◆ getSpeciesDestructionTimescales() [1/2]

◆ getSpeciesDestructionTimescales() [2/2]

◆ getSpeciesIndex()

◆ getSpeciesStatus()

◆ getSpeciesTimescales() [1/2]

◆ getSpeciesTimescales() [2/2]

◆ involvesSpecies()

◆ isPrecomputationEnabled()

◆ isUsingReverseReactions()

◆ populateReactionIDMap()

◆ populateSpeciesToIndexMap()

◆ precomputeNetwork()

◆ primeEngine()

◆ project()

◆ recordADTape()

◆ set_store_intermediate_reaction_contributions()

◆ syncInternalMaps()

Member Data Documentation

◆ m_atomicReverseRates

◆ m_authoritativeADFun

◆ m_config

◆ m_constants

◆ m_depth

◆ m_full_jacobian_sparsity_pattern

◆ m_full_sparsity_set

◆ m_indexToSpeciesMap

◆ m_jacobianMatrixStateNameMap

◆ m_logger

◆ m_networkSpecies

◆ m_networkSpeciesMap

◆ m_partitionFunction