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

#include <engine_multiscale.h>

Inheritance diagram for gridfire::engine::MultiscalePartitioningEngineView:

Collaboration diagram for gridfire::engine::MultiscalePartitioningEngineView:

Classes
struct	FluxValidationResult

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

class	QSESolver

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

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

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

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

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

NetworkJacobian	generateJacobianMatrix (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const std::vector< fourdst::atomic::Species > &activeSpecies) const override
	Generates the Jacobian matrix for a subset of active species.

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

double	calculateMolarReactionFlow (scratch::StateBlob &ctx, 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 reaction::ReactionSet &	getNetworkReactions (scratch::StateBlob &ctx) const override
	Gets the set of logical reactions in the network.

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

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

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

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

fourdst::composition::Composition	partitionNetwork (scratch::StateBlob &ctx, const NetIn &netIn) const
	Partitions the network based on timescales from a `NetIn` struct.

void	exportToDot (scratch::StateBlob &ctx, const std::string &filename, const fourdst::composition::Composition &comp, double T9, double rho) const
	Exports the network to a DOT file for visualization.

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

PrimingReport	primeEngine (scratch::StateBlob &ctx, const NetIn &netIn) const override
	Primes the engine with a specific species.

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

fourdst::composition::Composition	getNormalizedEquilibratedComposition (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, double T9, double rho, bool trust) const
	Gets a normalized composition with QSE species equilibrated.

fourdst::composition::Composition	collectComposition (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
	Collect the composition from this and sub engines.

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

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

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

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.

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

Static Public Member Functions
static const std::vector< fourdst::atomic::Species > &	getDynamicSpecies (scratch::StateBlob &ctx)
	Gets the dynamic species in the network.

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

static bool	involvesSpeciesInQSE (scratch::StateBlob &ctx, const fourdst::atomic::Species &species)
	Check if a species is involved in the QSE (algebraic) set.

static bool	involvesSpeciesInDynamic (scratch::StateBlob &ctx, const fourdst::atomic::Species &species)
	Check if a species is involved in the dynamic set.

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< fourdst::atomic::Species > >	partitionByTimescale (scratch::StateBlob &ctx, const fourdst::composition::Composition &comp, double T9, double rho) const
	Partitions the network by timescale.

std::pair< bool, reaction::ReactionSet >	group_is_a_qse_cluster (scratch::StateBlob &ctx, const fourdst::composition::Composition &comp, double T9, double rho, const QSEGroup &group) const

bool	group_is_a_qse_pipeline (scratch::StateBlob &ctx, const fourdst::composition::Composition &comp, double T9, double rho, const QSEGroup &group) const

FluxValidationResult	validateGroupsWithFluxAnalysis (scratch::StateBlob &ctx, const std::vector< QSEGroup > &candidate_groups, const fourdst::composition::Composition &comp, double T9, double rho) const
	Validates candidate QSE groups using flux analysis.

auto	solveQSEAbundances (scratch::StateBlob &ctx, const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const -> fourdst::composition::Composition
	Solves for the QSE abundances of the algebraic species in a given state.

size_t	identifyMeanSlowestPool (scratch::StateBlob &ctx, const std::vector< std::vector< fourdst::atomic::Species > > &pools, const fourdst::composition::Composition &comp, double T9, double rho) const
	Identifies the pool with the slowest mean timescale.

std::unordered_map< fourdst::atomic::Species, std::vector< fourdst::atomic::Species > >	buildConnectivityGraph (scratch::StateBlob &ctx, const std::vector< fourdst::atomic::Species > &species_pool, const fourdst::composition::Composition &comp, double T9, double rho) const
	Builds a connectivity graph from a species pool.

std::vector< QSEGroup >	constructCandidateGroups (scratch::StateBlob &ctx, const std::vector< std::vector< fourdst::atomic::Species > > &candidate_pools, const fourdst::composition::Composition &comp, double T9, double rho) const
	Constructs candidate QSE groups from connected timescale pools.

std::vector< std::vector< fourdst::atomic::Species > >	analyzeTimescalePoolConnectivity (scratch::StateBlob &ctx, const std::vector< std::vector< fourdst::atomic::Species > > &timescale_pools, const fourdst::composition::Composition &comp, double T9, double rho) const
	Analyzes the connectivity of timescale pools.

std::vector< QSEGroup >	pruneValidatedGroups (scratch::StateBlob &ctx, const std::vector< QSEGroup > &groups, const std::vector< reaction::ReactionSet > &groupReactions, const fourdst::composition::Composition &comp, double T9, double rho) const

Static Private Member Functions
static std::vector< QSEGroup >	merge_coupled_groups (scratch::StateBlob &ctx, const std::vector< QSEGroup > &groups, const std::vector< reaction::ReactionSet > &groupReactions)

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

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

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::NetIn
Definition types.h:27

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::engine::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::engine::MultiscalePartitioningEngineView::MultiscalePartitioningEngineView ( DynamicEngine & 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< Species > > gridfire::engine::MultiscalePartitioningEngineView::analyzeTimescalePoolConnectivity	(	scratch::StateBlob &	ctx,
		const std::vector< std::vector< fourdst::atomic::Species > > &	timescale_pools,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Analyzes the connectivity of timescale pools.

Parameters

ctx	The scratch data for thread-local storage.
timescale_pools	A vector of vectors of species indices, where each inner vector represents a timescale pool.
comp
T9
rho

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

std::unordered_map< Species, std::vector< Species > > gridfire::engine::MultiscalePartitioningEngineView::buildConnectivityGraph	(	scratch::StateBlob &	ctx,
		const std::vector< fourdst::atomic::Species > &	species_pool,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Builds a connectivity graph from a species pool.

Parameters

ctx	The scratch data for thread-local storage.
species_pool	A vector of species indices representing a species pool.
comp
T9
rho

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.

◆ calculateEpsDerivatives()

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

nodiscardoverridevirtual

Calculates the energy generation rate derivatives with respect to abundances.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
T9	The temperature in units of 10^9 K.
rho	The density in g/cm^3.

Returns: The energy generation rate derivatives (dEps/dT and dEps/drho).

Implements gridfire::engine::DynamicEngine.

◆ calculateMolarReactionFlow()

double gridfire::engine::MultiscalePartitioningEngineView::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

ctx	The scratch data for thread-local storage.
reaction	The reaction for which to calculate the flow.
comp	The current composition.
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::engine::DynamicEngine.

◆ calculateRHSAndEnergy()

std::expected< StepDerivatives< double >, EngineStatus > gridfire::engine::MultiscalePartitioningEngineView::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.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
trust

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

◆ collectComposition()

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

overridevirtual

Collect the composition from this and sub engines.

This method operates by injecting the current equilibrium abundances for algebraic species into the composition object so that they can be bubbled up to the caller.

Parameters

ctx	The scratch data for thread-local storage.
comp	Input Composition
T9
rho

Returns: New composition which is comp + any edits from lower levels + the equilibrium abundances of all algebraic species.

Exceptions

BadCollectionError if there is a species in the algebraic species set which does not show up in the reported composition from the base engine.:w

Implements gridfire::engine::DynamicEngine.

◆ constructCandidateGroups()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::engine::MultiscalePartitioningEngineView::constructCandidateGroups	(	scratch::StateBlob &	ctx,
		const std::vector< std::vector< fourdst::atomic::Species > > &	candidate_pools,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Constructs candidate QSE groups from connected timescale pools.

Parameters

ctx	The scratch data for thread-local storage.
candidate_pools	A vector of vectors of species indices, where each inner vector represents a connected pool of species with similar fast timescales.
comp	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.

◆ constructStateBlob()

std::unique_ptr< scratch::StateBlob > gridfire::engine::MultiscalePartitioningEngineView::constructStateBlob ( const scratch::StateBlob * blob ) const

nodiscardoverridevirtual

Implements gridfire::engine::DynamicEngine.

◆ exportToDot()

void gridfire::engine::MultiscalePartitioningEngineView::exportToDot	(	scratch::StateBlob &	ctx,
		const std::string &	filename,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

Exports the network to a DOT file for visualization.

Parameters

ctx	The scratch data for thread-local storage.
filename	The name of the DOT file to create.
comp	Composition object
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() [1/3]

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

nodiscardoverridevirtual

Generates the Jacobian matrix for the current state.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
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::engine::DynamicEngine.

◆ generateJacobianMatrix() [2/3]

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

nodiscardoverridevirtual

Generates the Jacobian matrix using a sparsity pattern.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
sparsityPattern	The sparsity pattern to use for the Jacobian.

Purpose: To compute the Jacobian matrix while leveraging a known sparsity pattern for efficiency. This is effectively a lower level version of the active species method.

How: It first checks the QSE cache. On a hit, it delegates to the base engine's generateJacobianMatrix method with the provided sparsity pattern.

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

Postcondition: The base engine's internal Jacobian is updated according to the sparsity pattern.

Exceptions

exceptions::StaleEngineError If the QSE cache misses.

Implements gridfire::engine::DynamicEngine.

◆ generateJacobianMatrix() [3/3]

NetworkJacobian gridfire::engine::MultiscalePartitioningEngineView::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 a subset of active species.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
activeSpecies	The subset of species to include in the Jacobian.

Purpose: To compute a reduced Jacobian matrix for implicit solvers that only consider a subset of species.

How: Similar to the full Jacobian generation, it first checks the QSE cache. On a hit, it calls the base engine's generateJacobianMatrix with the specified active species. The returned Jacobian still reflects the full network, but only for the active species subset.

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

Postcondition: The base engine's internal Jacobian is updated for the active species.

Exceptions

exceptions::StaleEngineError If the QSE cache misses.

Implements gridfire::engine::DynamicEngine.

◆ getBaseEngine()

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

nodiscardoverridevirtual

Gets the base engine.

Returns: A const reference to the base engine.

Implements gridfire::engine::EngineView< DynamicEngine >.

◆ getDynamicSpecies()

const std::vector< Species > & gridfire::engine::MultiscalePartitioningEngineView::getDynamicSpecies ( scratch::StateBlob & ctx )

staticnodiscard

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::engine::MultiscalePartitioningEngineView::getFastSpecies ( scratch::StateBlob & ctx ) 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.

◆ getMostRecentRHSCalculation()

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

nodiscardoverridevirtual

Implements gridfire::engine::DynamicEngine.

◆ getNetworkReactions()

const reaction::ReactionSet & gridfire::engine::MultiscalePartitioningEngineView::getNetworkReactions ( scratch::StateBlob & ctx ) 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::engine::DynamicEngine.

◆ getNetworkSpecies()

const std::vector< Species > & gridfire::engine::MultiscalePartitioningEngineView::getNetworkSpecies ( scratch::StateBlob & ctx ) 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::Engine.

◆ getNormalizedEquilibratedComposition()

fourdst::composition::Composition gridfire::engine::MultiscalePartitioningEngineView::getNormalizedEquilibratedComposition	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho,
		bool	trust ) const

Gets a normalized composition with QSE species equilibrated.

Parameters

ctx	The scratch data for thread-local storage.
comp	The input composition.
T9	Temperature in units of 10^9 K.
rho	Density in g/cm^3.
trust

Returns: A new Composition object with algebraic species set to their equilibrium values.

Purpose: To provide a way to get the equilibrated composition without modifying the internal state.

How: It calls solveQSEAbundances() to compute the equilibrium abundances for the algebraic species, then constructs a new Composition object reflecting these values.

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

Exceptions

StaleEngineError If the QSE cache misses.

◆ getScreeningModel()

screening::ScreeningType gridfire::engine::MultiscalePartitioningEngineView::getScreeningModel ( scratch::StateBlob & ctx ) 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::engine::DynamicEngine.

◆ getSpeciesDestructionTimescales()

std::expected< std::unordered_map< Species, double >, EngineStatus > gridfire::engine::MultiscalePartitioningEngineView::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

ctx	The scratch data for thread-local storage.
comp	The current composition.
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::engine::DynamicEngine.

◆ getSpeciesIndex()

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

nodiscardoverridevirtual

Gets the index of a species in the full network.

Parameters

ctx	The scratch data for thread-local storage.
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::engine::DynamicEngine.

◆ getSpeciesStatus()

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

overridevirtual

Gets the status of a species in the network.

Parameters

ctx	The scratch data for thread-local storage.
species	The species to query.

Returns: The SpeciesStatus indicating if the species is dynamic, algebraic, or not involved.

Purpose: To allow external queries about the role of a species in the partitioned network.

How: It checks for membership in m_dynamic_species and m_algebraic_species to determine the appropriate status.

Precondition: partitionNetwork() must have been called.

Implements gridfire::engine::DynamicEngine.

◆ getSpeciesTimescales()

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

nodiscardoverridevirtual

Computes timescales for all species in the network.

Parameters

ctx	The scratch data for thread-local storage.
comp	The current composition.
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::engine::DynamicEngine.

◆ group_is_a_qse_cluster()

std::pair< bool, reaction::ReactionSet > gridfire::engine::MultiscalePartitioningEngineView::group_is_a_qse_cluster	(	scratch::StateBlob &	ctx,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho,
		const QSEGroup &	group ) const

private

◆ group_is_a_qse_pipeline()

bool gridfire::engine::MultiscalePartitioningEngineView::group_is_a_qse_pipeline	(	scratch::StateBlob &	ctx,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho,
		const QSEGroup &	group ) const

private

◆ identifyMeanSlowestPool()

size_t gridfire::engine::MultiscalePartitioningEngineView::identifyMeanSlowestPool	(	scratch::StateBlob &	ctx,
		const std::vector< std::vector< fourdst::atomic::Species > > &	pools,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Identifies the pool with the slowest mean timescale.

Parameters

ctx	The scratch data for thread-local storage.
pools	A vector of vectors of species indices, where each inner vector represents a timescale pool.
comp	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.

◆ involvesSpecies()

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

static

Checks if a species is involved in the partitioned network.

Parameters

ctx	The scratch data for thread-local storage.
species	The species to check.

Returns: true if the species is in either the dynamic or algebraic sets, false otherwise.

Purpose: To allow external queries about species involvement in the partitioned network.

How: It checks for membership in both m_dynamic_species and m_algebraic_species.

Precondition: partitionNetwork() must have been called.

◆ involvesSpeciesInDynamic()

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

static

Check if a species is involved in the dynamic set.

Parameters

ctx	The scratch data for thread-local storage.
species	The species to check.

Returns: Boolean indicating if the species is in the dynamic set.

◆ involvesSpeciesInQSE()

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

static

Check if a species is involved in the QSE (algebraic) set.

Parameters

ctx	The scratch data for thread-local storage.
species	The species to check.

Returns: Boolean indicating if the species is in the algebraic set.

◆ merge_coupled_groups()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::engine::MultiscalePartitioningEngineView::merge_coupled_groups	(	scratch::StateBlob &	ctx,
		const std::vector< QSEGroup > &	groups,
		const std::vector< reaction::ReactionSet > &	groupReactions )

staticprivate

◆ partitionByTimescale()

std::vector< std::vector< Species > > gridfire::engine::MultiscalePartitioningEngineView::partitionByTimescale	(	scratch::StateBlob &	ctx,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Partitions the network by timescale.

Parameters

ctx	The scratch data for thread-local storage.
comp	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()

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

Partitions the network based on timescales from a NetIn struct.

Parameters

ctx	The scratch data for thread-local storage.
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.

◆ primeEngine()

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

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::engine::DynamicEngine.

◆ project()

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

overridevirtual

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

Parameters

ctx	The scratch data for thread-local storage.
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::engine::DynamicEngine.

◆ pruneValidatedGroups()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::engine::MultiscalePartitioningEngineView::pruneValidatedGroups	(	scratch::StateBlob &	ctx,
		const std::vector< QSEGroup > &	groups,
		const std::vector< reaction::ReactionSet > &	groupReactions,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

◆ solveQSEAbundances()

fourdst::composition::Composition gridfire::engine::MultiscalePartitioningEngineView::solveQSEAbundances	(	scratch::StateBlob &	ctx,
		const fourdst::composition::CompositionAbstract &	comp,
		double	T9,
		double	rho ) const -> fourdst::composition::Composition

private

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

Parameters

ctx	The scratch data for thread-local storage.
comp	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.

◆ validateGroupsWithFluxAnalysis()

MultiscalePartitioningEngineView::FluxValidationResult gridfire::engine::MultiscalePartitioningEngineView::validateGroupsWithFluxAnalysis	(	scratch::StateBlob &	ctx,
		const std::vector< QSEGroup > &	candidate_groups,
		const fourdst::composition::Composition &	comp,
		double	T9,
		double	rho ) const

private

Validates candidate QSE groups using flux analysis.

Parameters

ctx	The scratch data for thread-local storage.
candidate_groups	A vector of candidate QSE groups.
comp	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_baseEngine

DynamicEngine& gridfire::engine::MultiscalePartitioningEngineView::m_baseEngine

private

The base engine to which this view delegates calculations.

◆ m_logger

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

private

Logger instance for logging messages.

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

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ QSEPartition

Constructor & Destructor Documentation

◆ MultiscalePartitioningEngineView()

Member Function Documentation

◆ analyzeTimescalePoolConnectivity()

◆ buildConnectivityGraph()

◆ calculateEpsDerivatives()

◆ calculateMolarReactionFlow()

◆ calculateRHSAndEnergy()

◆ collectComposition()

◆ constructCandidateGroups()

◆ constructStateBlob()

◆ exportToDot()

◆ generateJacobianMatrix() [1/3]

◆ generateJacobianMatrix() [2/3]

◆ generateJacobianMatrix() [3/3]

◆ getBaseEngine()

◆ getDynamicSpecies()

◆ getFastSpecies()

◆ getMostRecentRHSCalculation()

◆ getNetworkReactions()

◆ getNetworkSpecies()

◆ getNormalizedEquilibratedComposition()

◆ getScreeningModel()

◆ getSpeciesDestructionTimescales()

◆ getSpeciesIndex()

◆ getSpeciesStatus()

◆ getSpeciesTimescales()

◆ group_is_a_qse_cluster()

◆ group_is_a_qse_pipeline()

◆ identifyMeanSlowestPool()

◆ involvesSpecies()

◆ involvesSpeciesInDynamic()

◆ involvesSpeciesInQSE()

◆ merge_coupled_groups()

◆ partitionByTimescale()

◆ partitionNetwork()

◆ primeEngine()

◆ project()

◆ pruneValidatedGroups()

◆ solveQSEAbundances()

◆ validateGroupsWithFluxAnalysis()

Member Data Documentation

◆ m_baseEngine

◆ m_logger