GridFire v0.7.1_rc2 General Purpose Nuclear Network

Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
gridfire::engine::MultiscalePartitioningEngineView Class Referencefinal

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:
[legend]
Collaboration diagram for gridfire::engine::MultiscalePartitioningEngineView:
[legend]

## Classes
struct | FluxValidationResult
struct | QSEGroup
| Struct representing a QSE group. More...
class | QSESolver

## Public Member Functions
| MultiscalePartitioningEngineView (DynamicEngine &baseEngine)
| Constructs a MultiscalePartitioningEngineView.
| ~MultiscalePartitioningEngineView () override
const std::vector< fourdst::atomic::Species > & | getNetworkSpecies () const override
| Gets the list of species in the network.
std::expected< StepDerivatives< double >, engine::EngineStatus > | calculateRHSAndEnergy (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
| Calculates the right-hand side (dY/dt) and energy generation.
EnergyDerivatives | calculateEpsDerivatives (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
| Calculates the energy generation rate derivatives with respect to abundances.
NetworkJacobian | generateJacobianMatrix (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
| Generates the Jacobian matrix for the current state.
NetworkJacobian | generateJacobianMatrix (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 (const fourdst::composition::CompositionAbstract &comp, double T9, double rho, const SparsityPattern &sparsityPattern) const override
| Generates the Jacobian matrix using a sparsity pattern.
void | generateStoichiometryMatrix () override
| Generates the stoichiometry matrix for the network.
int | getStoichiometryMatrixEntry (const fourdst::atomic::Species &species, const reaction::Reaction &reaction) const override
| Gets an entry from the stoichiometry matrix.
double | calculateMolarReactionFlow (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 () const override
| Gets the set of logical reactions in the network.
void | setNetworkReactions (const reaction::ReactionSet &reactions) override
| Sets the set of logical reactions in the network.
std::expected< std::unordered_map< fourdst::atomic::Species, double >, engine::EngineStatus > | getSpeciesTimescales (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 >, engine::EngineStatus > | getSpeciesDestructionTimescales (const fourdst::composition::CompositionAbstract &comp, 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.
fourdst::composition::Composition | partitionNetwork (const NetIn &netIn)
| Partitions the network based on timescales from a `NetIn` struct.
void | exportToDot (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 (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.
bool | involvesSpecies (const fourdst::atomic::Species &species) const
| Checks if a species is involved in the partitioned network.
bool | involvesSpeciesInQSE (const fourdst::atomic::Species &species) const
| Check if a species is involved in the QSE (algebraic) set.
bool | involvesSpeciesInDynamic (const fourdst::atomic::Species &species) const
| Check if a species is involved in the dynamic set.
fourdst::composition::Composition | getNormalizedEquilibratedComposition (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const
| Gets a normalized composition with QSE species equilibrated.
fourdst::composition::Composition | collectComposition (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const override
| Collect the composition from this and sub engines.
SpeciesStatus | getSpeciesStatus (const fourdst::atomic::Species &species) const override
| Gets the status of a species in the network.
Public Member Functions inherited from gridfire::engine::DynamicEngine
virtual BuildDepthType | getDepth () const
| Get the depth of the network.
virtual void | rebuild (const fourdst::composition::CompositionAbstract &comp, BuildDepthType depth)
| Rebuild the network with a specified depth.
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.

## 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 (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 (const fourdst::composition::Composition &comp, double T9, double rho, const QSEGroup &group) const
bool | group_is_a_qse_pipeline (const fourdst::composition::Composition &comp, double T9, double rho, const QSEGroup &group) const
FluxValidationResult | validateGroupsWithFluxAnalysis (const std::vector< QSEGroup > &candidate_groups, const fourdst::composition::Composition &comp, double T9, double rho) const
| Validates candidate QSE groups using flux analysis.
fourdst::composition::Composition | solveQSEAbundances (const fourdst::composition::CompositionAbstract &comp, double T9, double rho) const
| Solves for the QSE abundances of the algebraic species in a given state.
size_t | identifyMeanSlowestPool (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 (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 (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 (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 (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 (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.
std::vector< QSEGroup > | m_qse_groups
| The list of identified equilibrium groups.
std::vector< std::unique_ptr< QSESolver > > | m_qse_solvers
| A set of solvers, one for each QSE group.
std::vector< fourdst::atomic::Species > | m_dynamic_species
| The simplified set of species presented to the solver (the "slow" species).
std::vector< fourdst::atomic::Species > | m_algebraic_species
| Species that are treated as algebraic (in QSE) in the QSE groups.
std::unordered_map< fourdst::atomic::Species, double > | m_algebraic_abundances
| Map from species to their calculated abundances in the QSE state.
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< uint64_t, fourdst::composition::Composition > | m_composition_cache
SUNContext | m_sun_ctx = nullptr

## 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:
  1. Timescale Analysis: Using `getSpeciesDestructionTimescales` from the base engine, all species are sorted by their characteristic timescales.
  2. Gap Detection: The sorted list of timescales is scanned for large gaps (e.g., several orders of magnitude) to create distinct "timescale pools".
  3. Connectivity Analysis: Each pool is analyzed for internal reaction connectivity to form cohesive groups.
  4. 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.
  5. 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
  gridfire::NetIn::composition
  fourdst::composition::Composition composition
  Composition of the network.
  Definition types.h:28

<DynamicEngine>

## 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.

## ◆ ~MultiscalePartitioningEngineView()

gridfire::engine::MultiscalePartitioningEngineView::~MultiscalePartitioningEngineView | ( |  | ) |
| override

## Member Function Documentation

## ◆ analyzeTimescalePoolConnectivity()

std::vector< std::vector< Species > > gridfire::engine::MultiscalePartitioningEngineView::analyzeTimescalePoolConnectivity | ( | 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

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

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

Calculates the energy generation rate derivatives with respect to abundances.

Parameters

  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 | ( | const reaction::Reaction & | reaction,
|  | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

Calculates the molar reaction flow for a given reaction.

Parameters

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

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

Parameters

  comp | The current composition.
  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::Engine.

## ◆ collectComposition()

fourdst::composition::Composition gridfire::engine::MultiscalePartitioningEngineView::collectComposition | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

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

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

  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.

## ◆ exportToDot()

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

Exports the network to a DOT file for visualization.

Parameters

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

Generates the Jacobian matrix for the current state.

Parameters

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho,
|  | const SparsityPattern & | sparsityPattern
| ) |  | const
| override virtual

Generates the Jacobian matrix using a sparsity pattern.

Parameters

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho,
|  | const std::vector< fourdst::atomic::Species > & | activeSpecies
| ) |  | const
| override virtual

Generates the Jacobian matrix for a subset of active species.

Parameters

  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.

## ◆ generateStoichiometryMatrix()

void gridfire::engine::MultiscalePartitioningEngineView::generateStoichiometryMatrix | ( |  | ) |
| override virtual

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

## ◆ getBaseEngine()

const DynamicEngine & gridfire::engine::MultiscalePartitioningEngineView::getBaseEngine | ( |  | ) | const
| override virtual

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

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

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.

## ◆ getNetworkReactions()

const reaction::ReactionSet & gridfire::engine::MultiscalePartitioningEngineView::getNetworkReactions | ( |  | ) | const
| override virtual

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 | ( |  | ) | const
| override virtual

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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const

Gets a normalized composition with QSE species equilibrated.

Parameters

  comp | The input composition.
  T9 | Temperature in units of 10^9 K.
  rho | Density in g/cm^3.

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 | ( |  | ) | const
| override virtual

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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

Computes destruction timescales for all species in the network.

Parameters

  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 | ( | const fourdst::atomic::Species & | species | ) | const
| override virtual

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

## ◆ getSpeciesStatus()

SpeciesStatus gridfire::engine::MultiscalePartitioningEngineView::getSpeciesStatus | ( | const fourdst::atomic::Species & | species | ) | const
| override virtual

Gets the status of a species in the network.

Parameters

  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 | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| override virtual

Computes timescales for all species in the network.

Parameters

  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.

## ◆ getStoichiometryMatrixEntry()

int gridfire::engine::MultiscalePartitioningEngineView::getStoichiometryMatrixEntry | ( | const fourdst::atomic::Species & | species,
|  | const reaction::Reaction & | reaction
| ) |  | const
| override virtual

Gets an entry from the stoichiometry matrix.

Parameters

  species | Species to look up stoichiometry for.
  reaction | Reaction to find.

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

## ◆ group_is_a_qse_cluster()

std::pair< bool, reaction::ReactionSet > gridfire::engine::MultiscalePartitioningEngineView::group_is_a_qse_cluster | ( | 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 | ( | const fourdst::composition::Composition & | comp,
|  | double | T9,
|  | double | rho,
|  | const QSEGroup & | group
| ) |  | const
| private

## ◆ identifyMeanSlowestPool()

size_t gridfire::engine::MultiscalePartitioningEngineView::identifyMeanSlowestPool | ( | 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

  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 | ( | const fourdst::atomic::Species & | species | ) | const

Checks if a species is involved in the partitioned network.

Parameters

  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 | ( | const fourdst::atomic::Species & | species | ) | const

Check if a species is involved in the dynamic set.

Parameters

  species | The species to check.

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

## ◆ involvesSpeciesInQSE()

bool gridfire::engine::MultiscalePartitioningEngineView::involvesSpeciesInQSE | ( | const fourdst::atomic::Species & | species | ) | const

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

Parameters

  species | The species to check.

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

## ◆ isStale()

bool gridfire::engine::MultiscalePartitioningEngineView::isStale | ( | const NetIn & | netIn | ) |
| override virtual

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

## ◆ mapNetInToMolarAbundanceVector()

std::vector< double > gridfire::engine::MultiscalePartitioningEngineView::mapNetInToMolarAbundanceVector | ( | const NetIn & | netIn | ) | const
| override virtual

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

## ◆ merge_coupled_groups()

std::vector< MultiscalePartitioningEngineView::QSEGroup > gridfire::engine::MultiscalePartitioningEngineView::merge_coupled_groups | ( | const std::vector< QSEGroup > & | groups,
|  | const std::vector< reaction::ReactionSet > & | groupReactions
| ) |  |
| static private

## ◆ partitionByTimescale()

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

Partitions the network by timescale.

Parameters

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

## ◆ primeEngine()

PrimingReport gridfire::engine::MultiscalePartitioningEngineView::primeEngine | ( | const NetIn & | netIn | ) |
| override virtual

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.

## ◆ pruneValidatedGroups()

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

## ◆ setNetworkReactions()

void gridfire::engine::MultiscalePartitioningEngineView::setNetworkReactions | ( | const reaction::ReactionSet & | reactions | ) |
| override virtual

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

## ◆ setScreeningModel()

void gridfire::engine::MultiscalePartitioningEngineView::setScreeningModel | ( | screening::ScreeningType | model | ) |
| override virtual

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

## ◆ solveQSEAbundances()

fourdst::composition::Composition gridfire::engine::MultiscalePartitioningEngineView::solveQSEAbundances | ( | const fourdst::composition::CompositionAbstract & | comp,
|  | double | T9,
|  | double | rho
| ) |  | const
| private

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

Parameters

  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.

## ◆ update()

fourdst::composition::Composition gridfire::engine::MultiscalePartitioningEngineView::update | ( | const NetIn & | netIn | ) |
| override virtual

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

1. 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.
2. If the cache misses, it calls `equilibrateNetwork()`.
3. `equilibrateNetwork()` in turn calls `partitionNetwork()` to define the dynamic and algebraic species sets.
4. It then calls `solveQSEAbundances()` to compute the equilibrium abundances.
5. The resulting equilibrium abundances for the algebraic species are stored in the `m_qse_abundance_cache`.
6. 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.

## ◆ validateGroupsWithFluxAnalysis()

MultiscalePartitioningEngineView::FluxValidationResult gridfire::engine::MultiscalePartitioningEngineView::validateGroupsWithFluxAnalysis | ( | 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

  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_activeReactionIndices

std::vector<size_t> gridfire::engine::MultiscalePartitioningEngineView::m_activeReactionIndices
| private

Indices of all reactions involving only active species.

## ◆ m_activeSpeciesIndices

std::vector<size_t> gridfire::engine::MultiscalePartitioningEngineView::m_activeSpeciesIndices
| private

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

## ◆ m_algebraic_abundances

std::unordered_map<fourdst::atomic::Species, double> gridfire::engine::MultiscalePartitioningEngineView::m_algebraic_abundances
| private

Map from species to their calculated abundances in the QSE state.

## ◆ m_algebraic_species

std::vector<fourdst::atomic::Species> gridfire::engine::MultiscalePartitioningEngineView::m_algebraic_species
| private

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

## ◆ m_baseEngine

DynamicEngine& gridfire::engine::MultiscalePartitioningEngineView::m_baseEngine
| private

The base engine to which this view delegates calculations.

## ◆ m_composition_cache

std::unordered_map<uint64_t, fourdst::composition::Composition> gridfire::engine::MultiscalePartitioningEngineView::m_composition_cache
| mutable private

## ◆ m_dynamic_species

std::vector<fourdst::atomic::Species> gridfire::engine::MultiscalePartitioningEngineView::m_dynamic_species
| private

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

## ◆ m_logger

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

Logger instance for logging messages.

## ◆ m_qse_groups

std::vector<QSEGroup> gridfire::engine::MultiscalePartitioningEngineView::m_qse_groups
| private

The list of identified equilibrium groups.

## ◆ m_qse_solvers

std::vector<std::unique_ptr<QSESolver> > gridfire::engine::MultiscalePartitioningEngineView::m_qse_solvers
| private

A set of solvers, one for each QSE group.

## ◆ m_sun_ctx

SUNContext gridfire::engine::MultiscalePartitioningEngineView::m_sun_ctx = nullptr
| private

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