An engine view that partitions the reaction network into multiple groups based on timescales. More...

#include <engine_multiscale.h>

Inheritance diagram for gridfire::MultiscalePartitioningEngineView:

Classes
struct	CacheStats
	Struct for tracking cache statistics. More...

struct	EigenFunctor
	Functor for solving QSE abundances using Eigen's nonlinear optimization. More...

struct	QSEGroup
	Struct representing a QSE group. More...

Public Member Functions
	MultiscalePartitioningEngineView (GraphEngine &baseEngine)
	Constructs a MultiscalePartitioningEngineView.

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

std::expected< StepDerivatives< double >, expectations::StaleEngineError >	calculateRHSAndEnergy (const std::vector< double > &Y_full, double T9, double rho) const override
	Calculates the right-hand side (dY/dt) and energy generation.

void	generateJacobianMatrix (const std::vector< double > &Y_full, double T9, double rho) const override
	Generates the Jacobian matrix for the current state.

double	getJacobianMatrixEntry (int i_full, int j_full) const override
	Gets an entry from the previously generated Jacobian matrix.

void	generateStoichiometryMatrix () override
	Generates the stoichiometry matrix for the network.

int	getStoichiometryMatrixEntry (int speciesIndex, int reactionIndex) const override
	Gets an entry from the stoichiometry matrix.

double	calculateMolarReactionFlow (const reaction::Reaction &reaction, const std::vector< double > &Y_full, double T9, double rho) const override
	Calculates the molar reaction flow for a given reaction.

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

void	setNetworkReactions (const reaction::LogicalReactionSet &reactions) override
	Sets the set of logical reactions in the network.

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
	Computes destruction timescales for all species in the network.

fourdst::composition::Composition	update (const NetIn &netIn) override
	Updates the internal state of the engine, performing partitioning and QSE equilibration.

bool	isStale (const NetIn &netIn) override
	Checks if the engine's internal state is stale relative to the provided conditions.

void	setScreeningModel (screening::ScreeningType model) override
	Sets the electron screening model.

screening::ScreeningType	getScreeningModel () const override
	Gets the current electron screening model.

const DynamicEngine &	getBaseEngine () const override
	Gets the base engine.

std::vector< std::vector< size_t > >	analyzeTimescalePoolConnectivity (const std::vector< std::vector< size_t > > &timescale_pools, const std::vector< double > &Y, double T9, double rho) const
	Analyzes the connectivity of timescale pools.

void	partitionNetwork (const std::vector< double > &Y, double T9, double rho)
	Partitions the network into dynamic and algebraic (QSE) groups based on timescales.

void	partitionNetwork (const NetIn &netIn)
	Partitions the network based on timescales from a `NetIn` struct.

void	exportToDot (const std::string &filename, const std::vector< double > &Y, const double T9, const double rho) const
	Exports the network to a DOT file for visualization.

int	getSpeciesIndex (const fourdst::atomic::Species &species) const override
	Gets the index of a species in the full network.

std::vector< double >	mapNetInToMolarAbundanceVector (const NetIn &netIn) const override
	Maps a `NetIn` struct to a molar abundance vector for the full network.

PrimingReport	primeEngine (const NetIn &netIn) override
	Primes the engine with a specific species.

std::vector< fourdst::atomic::Species >	getFastSpecies () const
	Gets the fast species in the network.

const std::vector< fourdst::atomic::Species > &	getDynamicSpecies () const
	Gets the dynamic species in the network.

fourdst::composition::Composition	equilibrateNetwork (const std::vector< double > &Y, double T9, double rho)
	Equilibrates the network by partitioning and solving for QSE abundances.

fourdst::composition::Composition	equilibrateNetwork (const NetIn &netIn)
	Equilibrates the network using QSE from a `NetIn` struct.

Public Member Functions inherited from gridfire::DynamicEngine
virtual void	generateJacobianMatrix (const std::vector< double > &Y_dynamic, double T9, double rho, const SparsityPattern &sparsityPattern) const

virtual BuildDepthType	getDepth () const

virtual void	rebuild (const fourdst::composition::Composition &comp, BuildDepthType depth)

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

Public Member Functions inherited from gridfire::EngineView< DynamicEngine >
virtual	~EngineView ()=default
	Virtual destructor.

Private Types
typedef std::tuple< std::vector< fourdst::atomic::Species >, std::vector< size_t >, std::vector< fourdst::atomic::Species >, std::vector< size_t > >	QSEPartition
	Type alias for a QSE partition.

Private Member Functions
std::vector< std::vector< size_t > >	partitionByTimescale (const std::vector< double > &Y_full, double T9, double rho) const
	Partitions the network by timescale.

std::unordered_map< size_t, std::vector< size_t > >	buildConnectivityGraph (const std::unordered_set< size_t > &fast_reaction_indices) const
	Builds a connectivity graph from a set of fast reaction indices.

std::vector< QSEGroup >	validateGroupsWithFluxAnalysis (const std::vector< QSEGroup > &candidate_groups, const std::vector< double > &Y, double T9, double rho) const
	Validates candidate QSE groups using flux analysis.

std::vector< double >	solveQSEAbundances (const std::vector< double > &Y_full, double T9, double rho)
	Solves for the QSE abundances of the algebraic species in a given state.

size_t	identifyMeanSlowestPool (const std::vector< std::vector< size_t > > &pools, const std::vector< double > &Y, double T9, double rho) const
	Identifies the pool with the slowest mean timescale.

std::unordered_map< size_t, std::vector< size_t > >	buildConnectivityGraph (const std::vector< size_t > &species_pool) const
	Builds a connectivity graph from a species pool.

std::vector< QSEGroup >	constructCandidateGroups (const std::vector< std::vector< size_t > > &candidate_pools, const std::vector< double > &Y, double T9, double rho) const
	Constructs candidate QSE groups from connected timescale pools.

Private Attributes
quill::Logger *	m_logger = LogManager::getInstance().getLogger("log")
	Logger instance for logging messages.

GraphEngine &	m_baseEngine
	The base engine to which this view delegates calculations.

std::vector< QSEGroup >	m_qse_groups
	The list of identified equilibrium groups.

std::vector< fourdst::atomic::Species >	m_dynamic_species
	The simplified set of species presented to the solver (the "slow" species).

std::vector< size_t >	m_dynamic_species_indices
	Indices mapping the dynamic species back to the base engine's full species list.

std::vector< fourdst::atomic::Species >	m_algebraic_species
	Species that are treated as algebraic (in QSE) in the QSE groups.

std::vector< size_t >	m_algebraic_species_indices
	Indices of algebraic species in the full network.

std::vector< size_t >	m_activeSpeciesIndices
	Indices of all species considered active in the current partition (dynamic + algebraic).

std::vector< size_t >	m_activeReactionIndices
	Indices of all reactions involving only active species.

std::unordered_map< QSECacheKey, std::vector< double > >	m_qse_abundance_cache
	Cache for QSE abundances based on T9, rho, and Y.

CacheStats	m_cacheStats
	Statistics for the QSE abundance cache.

Detailed Description

An engine view that partitions the reaction network into multiple groups based on timescales.

@purpose This class is designed to accelerate the integration of stiff nuclear reaction networks. It identifies species that react on very short timescales ("fast" species) and treats them as being in Quasi-Steady-State Equilibrium (QSE). Their abundances are solved for algebraically, removing their stiff differential equations from the system. The remaining "slow" or "dynamic" species are integrated normally. This significantly improves the stability and performance of the solver.

@how The core logic resides in the partitionNetwork() and equilibrateNetwork() methods. The partitioning process involves:

Timescale Analysis: Using getSpeciesDestructionTimescales from the base engine, all species are sorted by their characteristic timescales.
Gap Detection: The sorted list of timescales is scanned for large gaps (e.g., several orders of magnitude) to create distinct "timescale pools".
Connectivity Analysis: Each pool is analyzed for internal reaction connectivity to form cohesive groups.
Flux Validation: Candidate QSE groups are validated by comparing the total reaction flux within the group to the flux leaving the group. A high internal-to-external flux ratio indicates a valid QSE group.
QSE Solve: For valid QSE groups, solveQSEAbundances uses a Levenberg-Marquardt nonlinear solver (Eigen::LevenbergMarquardt) to find the equilibrium abundances of the "algebraic" species, holding the "seed" species constant.

All calculations are cached using QSECacheKey to avoid re-partitioning and re-solving for similar thermodynamic conditions.

Usage Example:: // 1. Create a base engine (e.g., GraphEngine)

gridfire::GraphEngine baseEngine(composition);

// 2. Wrap it with the MultiscalePartitioningEngineView

gridfire::MultiscalePartitioningEngineView multiscaleEngine(baseEngine);

// 3. Before integration, update the view to partition the network

// and find the initial equilibrium state.

NetIn initialConditions = { .composition = composition, .temperature = 1e8, .density = 1e3 };

fourdst::composition::Composition equilibratedComp = multiscaleEngine.update(initialConditions);

// 4. Use the multiscaleEngine for integration. It will use the cached QSE solution.

// The integrator will call calculateRHSAndEnergy, etc. on the multiscaleEngine.

auto Y_initial = multiscaleEngine.mapNetInToMolarAbundanceVector({equilibratedComp, ...});

auto derivatives = multiscaleEngine.calculateRHSAndEnergy(Y_initial, T9, rho);

gridfire::GraphEngine
A reaction network engine that uses a graph-based representation.
Definition engine_graph.h:100

gridfire::MultiscalePartitioningEngineView
An engine view that partitions the reaction network into multiple groups based on timescales.
Definition engine_multiscale.h:174

gridfire::NetIn
Definition network.h:53

Member Typedef Documentation

◆ QSEPartition

typedef std::tuple<std::vector<fourdst::atomic::Species>, std::vector<size_t>, std::vector<fourdst::atomic::Species>, std::vector<size_t> > gridfire::MultiscalePartitioningEngineView::QSEPartition

private

Type alias for a QSE partition.

A QSE partition is a tuple containing the fast species, their indices, the slow species, and their indices.

Constructor & Destructor Documentation

◆ MultiscalePartitioningEngineView()

gridfire::MultiscalePartitioningEngineView::MultiscalePartitioningEngineView ( GraphEngine & baseEngine )

explicit

Constructs a MultiscalePartitioningEngineView.

Parameters

baseEngine The underlying GraphEngine to which this view delegates calculations. It must be a GraphEngine and not a more general DynamicEngine because this view relies on its specific implementation details.

Member Function Documentation

◆ analyzeTimescalePoolConnectivity()

std::vector< std::vector< size_t > > gridfire::MultiscalePartitioningEngineView::analyzeTimescalePoolConnectivity	(	const std::vector< std::vector< size_t > > &	timescale_pools,
		const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

Analyzes the connectivity of timescale pools.

Parameters

timescale_pools	A vector of vectors of species indices, where each inner vector represents a timescale pool.
Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A vector of vectors of species indices, where each inner vector represents a single connected component.

@purpose To merge timescale pools that are strongly connected by reactions, forming cohesive groups for QSE analysis.

@how For each pool, it builds a reaction connectivity graph using buildConnectivityGraph. It then finds the connected components within that graph using a Breadth-First Search (BFS). The resulting components from all pools are collected and returned.

◆ buildConnectivityGraph() [1/2]

std::unordered_map< size_t, std::vector< size_t > > gridfire::MultiscalePartitioningEngineView::buildConnectivityGraph ( const std::unordered_set< size_t > & fast_reaction_indices ) const

private

Builds a connectivity graph from a set of fast reaction indices.

Parameters

fast_reaction_indices A set of indices for reactions considered "fast".

Returns: An unordered map representing the adjacency list of the connectivity graph, where keys are species indices and values are vectors of connected species indices.

@purpose To represent the reaction pathways among a subset of reactions.

@how It iterates through the specified fast reactions. For each reaction, it creates a two-way edge in the graph between every reactant and every product, signifying that mass can flow between them.

◆ buildConnectivityGraph() [2/2]

std::unordered_map< size_t, std::vector< size_t > > gridfire::MultiscalePartitioningEngineView::buildConnectivityGraph ( const std::vector< size_t > & species_pool ) const

private

Builds a connectivity graph from a species pool.

Parameters

species_pool A vector of species indices representing a species pool.

Returns: An unordered map representing the adjacency list of the connectivity graph.

@purpose To find reaction connections within a specific group of species.

@how It iterates through all reactions in the base engine. If a reaction involves at least two distinct species from the input species_pool (one as a reactant and one as a product), it adds edges between all reactants and products from that reaction that are also in the pool.

◆ calculateMolarReactionFlow()

double gridfire::MultiscalePartitioningEngineView::calculateMolarReactionFlow	(	const reaction::Reaction &	reaction,
		const std::vector< double > &	Y_full,
		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.
Y_full	Vector of current molar abundances for the full network.
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).

@purpose To compute the net rate of a single reaction.

@how It first checks the QSE cache. On a hit, it retrieves the cached equilibrium abundances for the algebraic species. It creates a mutable copy of Y_full, overwrites the algebraic species abundances with the cached equilibrium values, and then calls the base engine's calculateMolarReactionFlow with this modified abundance vector.

Precondition: The engine must have a valid QSE cache entry for the given state.

Exceptions

StaleEngineError If the QSE cache misses.

Implements gridfire::DynamicEngine.

◆ calculateRHSAndEnergy()

std::expected< StepDerivatives< double >, expectations::StaleEngineError > gridfire::MultiscalePartitioningEngineView::calculateRHSAndEnergy	(	const std::vector< double > &	Y_full,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

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

Parameters

Y_full	Vector of current molar abundances for all species in the base engine.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A std::expected containing StepDerivatives<double> on success, or a StaleEngineError if the engine's QSE cache does not contain a solution for the given state.

@purpose To compute the time derivatives for the ODE solver. This implementation modifies the derivatives from the base engine to enforce the QSE condition.

@how It first performs a lookup in the QSE abundance cache (m_qse_abundance_cache). If a cache hit occurs, it calls the base engine's calculateRHSAndEnergy. It then manually sets the time derivatives (dydt) of all identified algebraic species to zero, effectively removing their differential equations from the system being solved.

Precondition: The engine must have been updated via update() or equilibrateNetwork() for the current thermodynamic conditions, so that a valid entry exists in the QSE cache.

Postcondition: The returned derivatives will have dydt=0 for all algebraic species.

Exceptions

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.

Implements gridfire::Engine.

◆ constructCandidateGroups()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::MultiscalePartitioningEngineView::constructCandidateGroups	(	const std::vector< std::vector< size_t > > &	candidate_pools,
		const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

private

Constructs candidate QSE groups from connected timescale pools.

Parameters

candidate_pools	A vector of vectors of species indices, where each inner vector represents a connected pool of species with similar fast timescales.
Y	Vector of current molar abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A vector of QSEGroup structs, ready for flux validation.

@how For each input pool, it identifies "bridge" reactions that connect the pool to species outside the pool. The reactants of these bridge reactions that are not in the pool are identified as "seed" species. The original pool members are the "algebraic" species. It then bundles the seed and algebraic species into a QSEGroup struct.

Precondition: The candidate_pools should be connected components from analyzeTimescalePoolConnectivity.

Postcondition: A list of candidate QSEGroup objects is returned.

◆ equilibrateNetwork() [1/2]

fourdst::composition::Composition gridfire::MultiscalePartitioningEngineView::equilibrateNetwork ( const NetIn & netIn )

Equilibrates the network using QSE from a NetIn struct.

Parameters

netIn A struct containing the current network input.

Returns: The equilibrated composition.

@purpose A convenience overload for equilibrateNetwork.

@how It unpacks the netIn struct into Y, T9, and rho and then calls the primary equilibrateNetwork method.

◆ equilibrateNetwork() [2/2]

fourdst::composition::Composition gridfire::MultiscalePartitioningEngineView::equilibrateNetwork	(	const std::vector< double > &	Y,
		double	T9,
		double	rho )

Equilibrates the network by partitioning and solving for QSE abundances.

Parameters

Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A new composition object with the equilibrated abundances.

@purpose A convenience method to run the full QSE analysis and get an equilibrated composition object as a result.

@how It first calls partitionNetwork() with the given state to define the QSE groups. Then, it calls solveQSEAbundances() to compute the new equilibrium abundances for the algebraic species. Finally, it packs the resulting full abundance vector into a new fourdst::composition::Composition object and returns it.

Precondition: The input state (Y, T9, rho) must be a valid physical state.

Postcondition: The engine's internal partition is updated. A new composition object is returned.

◆ exportToDot()

void gridfire::MultiscalePartitioningEngineView::exportToDot	(	const std::string &	filename,
		const std::vector< double > &	Y,
		const double	T9,
		const double	rho ) const

Exports the network to a DOT file for visualization.

Parameters

filename	The name of the DOT file to create.
Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

@purpose To visualize the partitioned network graph.

@how This method delegates the DOT file export to the base engine. It does not currently add any partitioning information to the output graph.

◆ generateJacobianMatrix()

void gridfire::MultiscalePartitioningEngineView::generateJacobianMatrix	(	const std::vector< double > &	Y_full,
		double	T9,
		double	rho ) const

overridevirtual

Generates the Jacobian matrix for the current state.

Parameters

Y_full	Vector of current molar abundances.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

@purpose To compute the Jacobian matrix required by implicit ODE solvers.

@how It first performs a QSE cache lookup. On a hit, it delegates the full Jacobian calculation to the base engine. While this view could theoretically return a modified, sparser Jacobian reflecting the QSE constraints, the current implementation returns the full Jacobian from the base engine. The solver is expected to handle the algebraic constraints (e.g., via dydt=0 from calculateRHSAndEnergy).

Precondition: The engine must have a valid QSE cache entry for the given state.

Postcondition: The base engine's internal Jacobian is updated.

Exceptions

exceptions::StaleEngineError If the QSE cache misses, as it cannot proceed without a valid partition.

Implements gridfire::DynamicEngine.

◆ generateStoichiometryMatrix()

void gridfire::MultiscalePartitioningEngineView::generateStoichiometryMatrix ( )

overridevirtual

Generates the stoichiometry matrix for the network.

@purpose To prepare the stoichiometry matrix for later queries.

@how This method delegates directly to the base engine's generateStoichiometryMatrix(). The stoichiometry is based on the full, unpartitioned network.

Implements gridfire::DynamicEngine.

◆ getBaseEngine()

const DynamicEngine & gridfire::MultiscalePartitioningEngineView::getBaseEngine ( ) const

overridevirtual

Gets the base engine.

Returns: A const reference to the base engine.

Implements gridfire::EngineView< DynamicEngine >.

◆ getDynamicSpecies()

const std::vector< Species > & gridfire::MultiscalePartitioningEngineView::getDynamicSpecies ( ) const

nodiscard

Gets the dynamic species in the network.

Returns: A const reference to the vector of species identified as "dynamic" or "slow".

@purpose To allow external queries of the partitioning results.

@how It returns a const reference to the m_dynamic_species member vector.

Precondition: partitionNetwork() must have been called.

◆ getFastSpecies()

std::vector< Species > gridfire::MultiscalePartitioningEngineView::getFastSpecies ( ) const

nodiscard

Gets the fast species in the network.

Returns: A vector of species identified as "fast" or "algebraic" by the partitioning.

@purpose To allow external queries of the partitioning results.

@how It returns a copy of the m_algebraic_species member vector.

Precondition: partitionNetwork() must have been called.

◆ getJacobianMatrixEntry()

double gridfire::MultiscalePartitioningEngineView::getJacobianMatrixEntry	(	int	i_full,
		int	j_full ) const

nodiscardoverridevirtual

Gets an entry from the previously generated Jacobian matrix.

Parameters

i_full	Row index (species index) in the full network.
j_full	Column index (species index) in the full network.

Returns: Value of the Jacobian matrix at (i_full, j_full).

@purpose To provide Jacobian entries to an implicit solver.

@how This method directly delegates to the base engine's getJacobianMatrixEntry. It does not currently modify the Jacobian to reflect the QSE algebraic constraints, as these are handled by setting dY/dt = 0 in calculateRHSAndEnergy.

Precondition: generateJacobianMatrix() must have been called for the current state.

Implements gridfire::DynamicEngine.

◆ getNetworkReactions()

const reaction::LogicalReactionSet & gridfire::MultiscalePartitioningEngineView::getNetworkReactions ( ) const

nodiscardoverridevirtual

Gets the set of logical reactions in the network.

Returns: A const reference to the LogicalReactionSet from the base engine, containing all reactions in the full network.

Implements gridfire::DynamicEngine.

◆ getNetworkSpecies()

const std::vector< Species > & gridfire::MultiscalePartitioningEngineView::getNetworkSpecies ( ) const

nodiscardoverridevirtual

Gets the list of species in the network.

Returns: A const reference to the vector of Species objects representing all species in the underlying base engine. This view does not alter the species list itself, only how their abundances are evolved.

Implements gridfire::Engine.

◆ getScreeningModel()

screening::ScreeningType gridfire::MultiscalePartitioningEngineView::getScreeningModel ( ) const

nodiscardoverridevirtual

Gets the current electron screening model.

Returns: The currently active screening model type.

@how This method delegates directly to the base engine's getScreeningModel().

Implements gridfire::DynamicEngine.

◆ getSpeciesDestructionTimescales()

std::expected< std::unordered_map< fourdst::atomic::Species, double >, expectations::StaleEngineError > gridfire::MultiscalePartitioningEngineView::getSpeciesDestructionTimescales	(	const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Computes destruction timescales for all species in the network.

Parameters

Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A std::expected containing a map from Species to their characteristic destruction timescales (s) on success, or a StaleEngineError on failure.

@purpose To get the timescale for species destruction, which is used as the primary metric for network partitioning.

@how It delegates the calculation to the base engine. For any species identified as algebraic (in QSE), it manually sets their timescale to 0.0.

Precondition: The engine must have a valid QSE cache entry for the given state.

Exceptions

StaleEngineError If the QSE cache misses.

Implements gridfire::DynamicEngine.

◆ getSpeciesIndex()

int gridfire::MultiscalePartitioningEngineView::getSpeciesIndex ( const fourdst::atomic::Species & species ) const

nodiscardoverridevirtual

Gets the index of a species in the full network.

Parameters

species The species to get the index of.

Returns: The index of the species in the base engine's network.

@how This method delegates directly to the base engine's getSpeciesIndex().

Implements gridfire::DynamicEngine.

◆ getSpeciesTimescales()

std::expected< std::unordered_map< Species, double >, expectations::StaleEngineError > gridfire::MultiscalePartitioningEngineView::getSpeciesTimescales	(	const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

nodiscardoverridevirtual

Computes timescales for all species in the network.

Parameters

Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A std::expected containing a map from Species to their characteristic timescales (s) on success, or a StaleEngineError on failure.

@purpose To get the characteristic timescale Y / (dY/dt) for each species.

@how It delegates the calculation to the base engine. For any species identified as algebraic (in QSE), it manually sets their timescale to 0.0 to signify that they equilibrate instantaneously on the timescale of the solver.

Precondition: The engine must have a valid QSE cache entry for the given state.

Exceptions

StaleEngineError If the QSE cache misses.

Implements gridfire::DynamicEngine.

◆ getStoichiometryMatrixEntry()

int gridfire::MultiscalePartitioningEngineView::getStoichiometryMatrixEntry	(	int	speciesIndex,
		int	reactionIndex ) const

nodiscardoverridevirtual

Gets an entry from the stoichiometry matrix.

Parameters

speciesIndex	Index of the species in the full network.
reactionIndex	Index of the reaction in the full network.

Returns: Stoichiometric coefficient for the species in the reaction.

@purpose To query the stoichiometric relationship between a species and a reaction.

@how This method delegates directly to the base engine's getStoichiometryMatrixEntry().

Precondition: generateStoichiometryMatrix() must have been called.

Implements gridfire::DynamicEngine.

◆ identifyMeanSlowestPool()

size_t gridfire::MultiscalePartitioningEngineView::identifyMeanSlowestPool	(	const std::vector< std::vector< size_t > > &	pools,
		const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

private

Identifies the pool with the slowest mean timescale.

Parameters

pools	A vector of vectors of species indices, where each inner vector represents a timescale pool.
Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: The index of the pool with the largest (slowest) mean destruction timescale.

@purpose To identify the core set of dynamic species that will not be part of any QSE group.

@how It calculates the geometric mean of the destruction timescales for all species in each pool and returns the index of the pool with the maximum mean timescale.

◆ isStale()

bool gridfire::MultiscalePartitioningEngineView::isStale ( const NetIn & netIn )

overridevirtual

Checks if the engine's internal state is stale relative to the provided conditions.

Parameters

netIn A struct containing the current network input.

Returns: true if the engine is stale, false otherwise.

@purpose To determine if update() needs to be called.

@how It creates a QSECacheKey from the netIn data and checks for its existence in the m_qse_abundance_cache. A cache miss indicates the engine is stale because it does not have a valid QSE partition for the current conditions. It also queries the base engine's isStale() method.

Implements gridfire::DynamicEngine.

◆ mapNetInToMolarAbundanceVector()

std::vector< double > gridfire::MultiscalePartitioningEngineView::mapNetInToMolarAbundanceVector ( const NetIn & netIn ) const

nodiscardoverridevirtual

Maps a NetIn struct to a molar abundance vector for the full network.

Parameters

netIn A struct containing the current network input.

Returns: A vector of molar abundances corresponding to the species order in the base engine.

@how This method delegates directly to the base engine's mapNetInToMolarAbundanceVector().

Implements gridfire::DynamicEngine.

◆ partitionByTimescale()

std::vector< std::vector< size_t > > gridfire::MultiscalePartitioningEngineView::partitionByTimescale	(	const std::vector< double > &	Y_full,
		double	T9,
		double	rho ) const

private

Partitions the network by timescale.

Parameters

Y_full	Vector of current molar abundances for all species.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A vector of vectors of species indices, where each inner vector represents a timescale pool.

@purpose To group species into "pools" based on their destruction timescales.

@how It retrieves all species destruction timescales from the base engine, sorts them, and then iterates through the sorted list, creating a new pool whenever it detects a gap between consecutive timescales that is larger than a predefined threshold (e.g., a factor of 100).

◆ partitionNetwork() [1/2]

void gridfire::MultiscalePartitioningEngineView::partitionNetwork ( const NetIn & netIn )

Partitions the network based on timescales from a NetIn struct.

Parameters

netIn A struct containing the current network input.

@purpose A convenience overload for partitionNetwork.

@how It unpacks the netIn struct into Y, T9, and rho and then calls the primary partitionNetwork method.

◆ partitionNetwork() [2/2]

void gridfire::MultiscalePartitioningEngineView::partitionNetwork	(	const std::vector< double > &	Y,
		double	T9,
		double	rho )

Partitions the network into dynamic and algebraic (QSE) groups based on timescales.

Parameters

Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

@purpose To perform the core partitioning logic that identifies which species are "fast" (and can be treated algebraically) and which are "slow" (and must be integrated dynamically).

@how

partitionByTimescale: Gets species destruction timescales from the base engine, sorts them, and looks for large gaps to create timescale "pools".
identifyMeanSlowestPool: The pool with the slowest average timescale is designated as the core set of dynamic species.
analyzeTimescalePoolConnectivity: The other (faster) pools are analyzed for reaction connectivity to form cohesive groups.
constructCandidateGroups: These connected groups are processed to identify "seed" species (dynamic species that feed the group) and "algebraic" species (the rest).
validateGroupsWithFluxAnalysis: The groups are validated by ensuring their internal reaction flux is much larger than the flux connecting them to the outside network.

Precondition: The input state (Y, T9, rho) must be a valid physical state.

Postcondition: The internal member variables m_qse_groups, m_dynamic_species, and m_algebraic_species (and their index maps) are populated with the results of the partitioning.

◆ primeEngine()

PrimingReport gridfire::MultiscalePartitioningEngineView::primeEngine ( const NetIn & netIn )

nodiscardoverridevirtual

Primes the engine with a specific species.

Parameters

netIn A struct containing the current network input.

Returns: A PrimingReport struct containing information about the priming process.

@purpose To prepare the network for ignition or specific pathway studies.

@how This method delegates directly to the base engine's primeEngine(). The multiscale view does not currently interact with the priming process.

Implements gridfire::DynamicEngine.

◆ setNetworkReactions()

void gridfire::MultiscalePartitioningEngineView::setNetworkReactions ( const reaction::LogicalReactionSet & reactions )

overridevirtual

Sets the set of logical reactions in the network.

Parameters

reactions The set of logical reactions to use.

@purpose To modify the reaction network.

@how This operation is not supported by the MultiscalePartitioningEngineView as it would invalidate the partitioning logic. It logs a critical error and throws an exception. Network modifications should be done on the base engine before it is wrapped by this view.

Exceptions

exceptions::UnableToSetNetworkReactionsError Always.

Implements gridfire::DynamicEngine.

◆ setScreeningModel()

void gridfire::MultiscalePartitioningEngineView::setScreeningModel ( screening::ScreeningType model )

overridevirtual

Sets the electron screening model.

Parameters

model The type of screening model to use for reaction rate calculations.

@how This method delegates directly to the base engine's setScreeningModel().

Implements gridfire::DynamicEngine.

◆ solveQSEAbundances()

std::vector< double > gridfire::MultiscalePartitioningEngineView::solveQSEAbundances	(	const std::vector< double > &	Y_full,
		double	T9,
		double	rho )

private

Solves for the QSE abundances of the algebraic species in a given state.

Parameters

Y_full	Vector of current molar abundances for all species in the base engine.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A vector of molar abundances for the algebraic species.

@purpose To find the equilibrium abundances of the algebraic species that satisfy the QSE conditions.

@how It uses the Levenberg-Marquardt algorithm via Eigen's LevenbergMarquardt class. The problem is defined by the EigenFunctor which computes the residuals and Jacobian for the QSE equations.

Precondition: The input state (Y_full, T9, rho) must be a valid physical state.

Postcondition: The algebraic species in the QSE cache are updated with the new equilibrium abundances.

◆ update()

fourdst::composition::Composition gridfire::MultiscalePartitioningEngineView::update ( const NetIn & netIn )

overridevirtual

Updates the internal state of the engine, performing partitioning and QSE equilibration.

Parameters

netIn A struct containing the current network input: temperature, density, and composition.

Returns: The new composition after QSE species have been brought to equilibrium.

@purpose This is the main entry point for preparing the multiscale engine for use. It triggers the network partitioning and solves for the initial QSE abundances, caching the result.

@how

It first checks the QSE cache. If a valid entry already exists for the input state, it returns the input composition, as no work is needed.
If the cache misses, it calls equilibrateNetwork().
equilibrateNetwork() in turn calls partitionNetwork() to define the dynamic and algebraic species sets.
It then calls solveQSEAbundances() to compute the equilibrium abundances.
The resulting equilibrium abundances for the algebraic species are stored in the m_qse_abundance_cache.
A new fourdst::composition::Composition object reflecting the equilibrated state is created and returned.

Precondition: The netIn struct should contain a valid physical state.

Postcondition: The engine is partitioned (m_dynamic_species, m_algebraic_species, etc. are populated). The m_qse_abundance_cache is populated with the QSE solution for the given state. The returned composition reflects the new equilibrium.

Implements gridfire::DynamicEngine.

◆ validateGroupsWithFluxAnalysis()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::MultiscalePartitioningEngineView::validateGroupsWithFluxAnalysis	(	const std::vector< QSEGroup > &	candidate_groups,
		const std::vector< double > &	Y,
		double	T9,
		double	rho ) const

private

Validates candidate QSE groups using flux analysis.

Parameters

candidate_groups	A vector of candidate QSE groups.
Y	Vector of current molar abundances for the full network.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.

Returns: A vector of validated QSE groups that meet the flux criteria.

@purpose To ensure that a candidate QSE group is truly in equilibrium by checking that the reaction fluxes within the group are much larger than the fluxes leaving the group.

@how For each candidate group, it calculates the sum of all internal reaction fluxes and the sum of all external (bridge) reaction fluxes. If the ratio of internal to external flux exceeds a configurable threshold, the group is considered valid and is added to the returned vector.

Member Data Documentation

◆ m_activeReactionIndices

std::vector<size_t> gridfire::MultiscalePartitioningEngineView::m_activeReactionIndices

private

Indices of all reactions involving only active species.

◆ m_activeSpeciesIndices

std::vector<size_t> gridfire::MultiscalePartitioningEngineView::m_activeSpeciesIndices

private

Indices of all species considered active in the current partition (dynamic + algebraic).

◆ m_algebraic_species

std::vector<fourdst::atomic::Species> gridfire::MultiscalePartitioningEngineView::m_algebraic_species

private

Species that are treated as algebraic (in QSE) in the QSE groups.

◆ m_algebraic_species_indices

std::vector<size_t> gridfire::MultiscalePartitioningEngineView::m_algebraic_species_indices

private

Indices of algebraic species in the full network.

◆ m_baseEngine

GraphEngine& gridfire::MultiscalePartitioningEngineView::m_baseEngine

private

The base engine to which this view delegates calculations.

◆ m_cacheStats

CacheStats gridfire::MultiscalePartitioningEngineView::m_cacheStats

mutableprivate

Statistics for the QSE abundance cache.

◆ m_dynamic_species

std::vector<fourdst::atomic::Species> gridfire::MultiscalePartitioningEngineView::m_dynamic_species

private

The simplified set of species presented to the solver (the "slow" species).

◆ m_dynamic_species_indices

std::vector<size_t> gridfire::MultiscalePartitioningEngineView::m_dynamic_species_indices

private

Indices mapping the dynamic species back to the base engine's full species list.

◆ m_logger

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

private

Logger instance for logging messages.

◆ m_qse_abundance_cache

std::unordered_map<QSECacheKey, std::vector<double> > gridfire::MultiscalePartitioningEngineView::m_qse_abundance_cache

mutableprivate

Cache for QSE abundances based on T9, rho, and Y.

@purpose This is the core of the caching mechanism. It stores the results of QSE solves to avoid re-computation. The key is a QSECacheKey which hashes the thermodynamic state, and the value is the vector of solved molar abundances for the algebraic species.

◆ m_qse_groups

std::vector<QSEGroup> gridfire::MultiscalePartitioningEngineView::m_qse_groups

private

The list of identified equilibrium groups.

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

src/include/gridfire/engine/views/engine_multiscale.h
src/lib/engine/views/engine_multiscale.cpp

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ QSEPartition

Constructor & Destructor Documentation

◆ MultiscalePartitioningEngineView()

Member Function Documentation

◆ analyzeTimescalePoolConnectivity()

◆ buildConnectivityGraph() [1/2]

◆ buildConnectivityGraph() [2/2]

◆ calculateMolarReactionFlow()

◆ calculateRHSAndEnergy()

◆ constructCandidateGroups()

◆ equilibrateNetwork() [1/2]

◆ equilibrateNetwork() [2/2]

◆ exportToDot()

◆ generateJacobianMatrix()

◆ generateStoichiometryMatrix()

◆ getBaseEngine()

◆ getDynamicSpecies()

◆ getFastSpecies()

◆ getJacobianMatrixEntry()

◆ getNetworkReactions()

◆ getNetworkSpecies()

◆ getScreeningModel()

◆ getSpeciesDestructionTimescales()

◆ getSpeciesIndex()

◆ getSpeciesTimescales()

◆ getStoichiometryMatrixEntry()

◆ identifyMeanSlowestPool()

◆ isStale()

◆ mapNetInToMolarAbundanceVector()

◆ partitionByTimescale()

◆ partitionNetwork() [1/2]

◆ partitionNetwork() [2/2]

◆ primeEngine()

◆ setNetworkReactions()

◆ setScreeningModel()

◆ solveQSEAbundances()

◆ update()

◆ validateGroupsWithFluxAnalysis()

Member Data Documentation

◆ m_activeReactionIndices

◆ m_activeSpeciesIndices

◆ m_algebraic_species

◆ m_algebraic_species_indices

◆ m_baseEngine

◆ m_cacheStats

◆ m_dynamic_species

◆ m_dynamic_species_indices

◆ m_logger

◆ m_qse_abundance_cache

◆ m_qse_groups