gridfire::engine Namespace Reference

Namespaces
namespace	diagnostics

Classes
class	AdaptiveEngineView
	An engine view that dynamically adapts the reaction network based on runtime conditions. More...
class	DefinedEngineView
class	DynamicEngine
	Abstract class for engines supporting Jacobian and stoichiometry operations. More...
struct	EnergyDerivatives
	Structure holding derivatives of energy generation rate with respect to T and rho. More...
class	Engine
	Abstract base class for a reaction network engine. More...
class	EngineView
	Abstract base class for a "view" of a reaction network engine. More...
class	FileDefinedEngineView
class	GraphEngine
	A reaction network engine that uses a graph-based representation. More...
class	MultiscalePartitioningEngineView
	An engine view that partitions the reaction network into multiple groups based on timescales. More...
class	NetworkJacobian
	A wrapper class for handling the network Jacobian matrix. More...
class	NetworkPrimingEngineView
	Provides a view of a DynamicEngine filtered to reactions involving a specified priming species. More...
struct	PrimingReport
	Captures the result of a network priming operation. More...
class	Reaction
	Represents a single nuclear reaction from a specific data source. More...
class	ReactionSet
struct	StepDerivatives
	Structure holding derivatives and energy generation for a network step. More...

Concepts
concept	EngineType
	Concept for types allowed as engine bases in EngineView.

Typedefs
using	SparsityPattern = std::vector<std::pair<size_t, size_t>>
	Type alias for sparsity pattern representation.
typedef CppAD::AD< double >	ADDouble
	Alias for CppAD AD type for double precision.
using	BuildDepthType = std::variant<NetworkBuildDepth, int>
	Variant specifying either a predefined NetworkBuildDepth or a custom integer depth.
using	JacobianEntry = std::pair<std::pair<fourdst::atomic::Species, fourdst::atomic::Species>, double>
	Represents an entry in the Jacobian matrix.

Enumerations
enum class	EngineStatus { OKAY , STALE , ERROR , COUNT }
	Enumeration of possible engine statuses. More...
enum class	NetworkConstructionFlags : uint32_t {   NONE = 0 , STRONG = 1 << 0 , BETA_MINUS = 1 << 1 , BETA_PLUS = 1 << 2 ,   ELECTRON_CAPTURE = 1 << 3 , POSITRON_CAPTURE = 1 << 4 , REACLIB_WEAK = 1 << 5 , WRL_WEAK = BETA_MINUS | BETA_PLUS | ELECTRON_CAPTURE | POSITRON_CAPTURE ,   REACLIB = STRONG | REACLIB_WEAK , DEFAULT = REACLIB , ALL = STRONG | WRL_WEAK }
	Flags to specify which types of nuclear reactions to include when constructing a reaction network. More...
enum class	NetworkBuildDepth {   Full = -1 , Shallow = 1 , SecondOrder = 2 , ThirdOrder = 3 ,   FourthOrder = 4 , FifthOrder = 5 }
	Specifies supported depths for building the reaction network. More...
enum class	EngineTypes {   GRAPH_ENGINE , ADAPTIVE_ENGINE_VIEW , MULTISCALE_PARTITIONING_ENGINE_VIEW , PRIMING_ENGINE_VIEW ,   DEFINED_ENGINE_VIEW , FILE_DEFINED_ENGINE_VIEW }
	Enumeration of different engine types available in GridFire. More...
enum class	PrimingReportStatus { SUCCESS , ALREADY_PRIMED , SOLVER_FAILURE }
	Enumerates outcome codes for a network priming operation. More...
enum class	SpeciesStatus { ACTIVE , EQUILIBRIUM , INACTIVE_FLOW , NOT_PRESENT }
	Enumerates the status of a species in the simulation. More...

Functions
constexpr std::string_view	EngineStatus_to_string (const EngineStatus status)
	Convert EngineStatus enum to string representation.
constexpr auto	to_underlying (NetworkConstructionFlags f) noexcept
	Helper function to convert NetworkConstructionFlags to their underlying integer type.
NetworkConstructionFlags	operator| (const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs)
	Bitwise OR operator for NetworkConstructionFlags.
NetworkConstructionFlags	operator& (const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs)
	Bitwise AND operator for NetworkConstructionFlags.
bool	has_flag (const NetworkConstructionFlags flags, const NetworkConstructionFlags flag_to_check)
	Checks if a specific flag is set within a NetworkConstructionFlags value.
std::string	NetworkConstructionFlagsToString (NetworkConstructionFlags flags)
	Converts NetworkConstructionFlags to a human-readable string.
reaction::ReactionSet	build_nuclear_network (const fourdst::composition::CompositionAbstract &composition, const rates::weak::WeakRateInterpolator &weakInterpolator, BuildDepthType maxLayers=NetworkBuildDepth::Full, NetworkConstructionFlags ReactionTypes=NetworkConstructionFlags::DEFAULT)
	Builds a nuclear reaction network from the Reaclib library based on an initial composition.
PrimingReport	primeNetwork (const NetIn &netIn, GraphEngine &engine, const std::optional< std::vector< reaction::ReactionType > > &ignoredReactionTypes)
	Primes absent species in the network to their equilibrium abundances.
double	calculateDestructionRateConstant (const DynamicEngine &engine, const fourdst::atomic::Species &species, const fourdst::composition::Composition &composition, double T9, double rho, const std::optional< std::vector< reaction::ReactionType > > &reactionTypesToIgnore)
	Computes the destruction rate constant for a specific species.
double	calculateCreationRate (const DynamicEngine &engine, const fourdst::atomic::Species &species, const fourdst::composition::Composition &composition, double T9, double rho, const std::optional< std::vector< reaction::ReactionType > > &reactionTypesToIgnore)
	Computes the creation rate for a specific species.
constexpr std::string_view	engine_type_to_string (const EngineTypes type)
	Converts an EngineTypes enum value to its corresponding string representation.
NetworkJacobian	regularize_jacobian (const NetworkJacobian &jacobian, const fourdst::composition::CompositionAbstract &comp, std::optional< quill::Logger * > logger=std::nullopt)
	Regularizes the given Jacobian matrix based on the provided composition.
std::string	SpeciesStatus_to_string (const SpeciesStatus status)
	Convert a SpeciesStatus enum value to its string representation.
NetworkJacobian	regularize_jacobian (const NetworkJacobian &jacobian, const fourdst::composition::CompositionAbstract &comp, const std::optional< quill::Logger * > logger)

Variables
static constexpr double	MIN_DENSITY_THRESHOLD = 1e-18
	Minimum density threshold below which reactions are ignored.
static constexpr double	MIN_ABUNDANCE_THRESHOLD = 1e-18
	Minimum abundance threshold below which species are ignored.
static constexpr double	MIN_JACOBIAN_THRESHOLD = 1e-24
	Minimum value for Jacobian matrix entries.
constexpr double	MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN = 1e-100
	Minimum abundance for a species to contribute to the Jacobian.
std::map< PrimingReportStatus, std::string >	PrimingReportStatusStrings
	Mapping from PrimingReportStatus codes to human-readable strings.

Typedef Documentation

ADDouble

typedef CppAD::AD<double> gridfire::engine::ADDouble

Alias for CppAD AD type for double precision.

This alias simplifies the use of the CppAD automatic differentiation type.

BuildDepthType

using gridfire::engine::BuildDepthType = std::variant<NetworkBuildDepth, int>

Variant specifying either a predefined NetworkBuildDepth or a custom integer depth.

Precondition

If using the integer alternative, the value must be >= 0 or -1 to indicate a full build.

Postcondition

The network builder will interpret and apply the specified depth to control reaction expansion.

JacobianEntry

using gridfire::engine::JacobianEntry = std::pair<std::pair<fourdst::atomic::Species, fourdst::atomic::Species>, double>

Represents an entry in the Jacobian matrix.

SparsityPattern

using gridfire::engine::SparsityPattern = std::vector<std::pair<size_t, size_t>>

Type alias for sparsity pattern representation.

Enumeration Type Documentation

EngineStatus

enum class gridfire::engine::EngineStatus

strong

Enumeration of possible engine statuses.

This enum defines the various states an engine can be in after performing calculations, such as being up-to-date (OKAY), needing an update (STALE), or encountering an error (ERROR).

Enumerator
OKAY
STALE
ERROR
COUNT

EngineTypes

enum class gridfire::engine::EngineTypes

strong

Enumeration of different engine types available in GridFire.

Values:

• GRAPH_ENGINE: The standard graph-based engine.
• ADAPTIVE_ENGINE_VIEW: An engine that adapts based on certain criteria.
• MULTISCALE_PARTITIONING_ENGINE_VIEW: An engine that partitions the system at multiple scales.
• PRIMING_ENGINE_VIEW: An engine that uses a priming strategy for simulations.
• DEFINED_ENGINE_VIEW: An engine defined by user specifications.
• FILE_DEFINED_ENGINE_VIEW: An engine defined through external files.

Enumerator
GRAPH_ENGINE
ADAPTIVE_ENGINE_VIEW
MULTISCALE_PARTITIONING_ENGINE_VIEW
PRIMING_ENGINE_VIEW
DEFINED_ENGINE_VIEW
FILE_DEFINED_ENGINE_VIEW

NetworkBuildDepth

enum class gridfire::engine::NetworkBuildDepth

strong

Specifies supported depths for building the reaction network.

Values:

• Full: Build the complete network (infinite depth).
• Shallow: Build only direct reactions (depth = 1).
• SecondOrder: Include reactions up to second order (depth = 2).
• ThirdOrder: Include reactions up to third order (depth = 3).
• FourthOrder: Include reactions up to fourth order (depth = 4).
• FifthOrder: Include reactions up to fifth order (depth = 5).

Note

For custom build depths, see BuildDepthType.

Enumerator
Full
Shallow
SecondOrder
ThirdOrder
FourthOrder
FifthOrder

NetworkConstructionFlags

enum class gridfire::engine::NetworkConstructionFlags : uint32_t

strong

Flags to specify which types of nuclear reactions to include when constructing a reaction network.

These flags allow fine-grained control over the inclusion of strong and weak nuclear reactions (beta decay, electron/positron capture) from various sources (Reaclib, WRL) during network construction. They can be combined using bitwise operations to create custom reaction sets.

Enumerator
NONE
STRONG
BETA_MINUS
BETA_PLUS
ELECTRON_CAPTURE
POSITRON_CAPTURE
REACLIB_WEAK
WRL_WEAK
REACLIB
DEFAULT
ALL

PrimingReportStatus

enum class gridfire::engine::PrimingReportStatus

strong

Enumerates outcome codes for a network priming operation.

These status codes indicate the reason for success or failure of the priming process:

• FULL_SUCCESS: Priming completed successfully with all species processed.
• NO_SPECIES_TO_PRIME: There were no species eligible for priming.
• MAX_ITERATIONS_REACHED: The algorithm reached its iteration limit without converging.
• FAILED_TO_FINALIZE_COMPOSITION: Unable to build a valid Composition object at end.
• FAILED_TO_FIND_CREATION_CHANNEL: No reaction path found to create the priming species.
• FAILED_TO_FIND_PRIMING_REACTIONS: No reactions containing the priming species were found.
• BASE_NETWORK_TOO_SHALLOW: The provided base network depth was insufficient for priming.

See also

PrimingReport for data associated with each status.

Enumerator
SUCCESS
ALREADY_PRIMED
SOLVER_FAILURE

SpeciesStatus

enum class gridfire::engine::SpeciesStatus

strong

Enumerates the status of a species in the simulation.

These status codes indicate the current state of a species:

• ACTIVE: The species is actively participating in reactions.
• EQUILIBRIUM: The species is in equilibrium and not changing concentration.
• INACTIVE_FLOW: The species is present but not currently flowing.
• NOT_PRESENT: The species is not present in the system.

Enumerator
ACTIVE
EQUILIBRIUM
INACTIVE_FLOW
NOT_PRESENT

Function Documentation

build_nuclear_network()

ReactionSet gridfire::engine::build_nuclear_network	(	const fourdst::composition::CompositionAbstract &	composition,
		const rates::weak::WeakRateInterpolator &	weakInterpolator,
		BuildDepthType	maxLayers = NetworkBuildDepth::Full,
		NetworkConstructionFlags	ReactionTypes = NetworkConstructionFlags::DEFAULT )

Builds a nuclear reaction network from the Reaclib library based on an initial composition.

Constructs a layered reaction network by collecting reactions up to the specified depth from the Reaclib dataset. Starting species are those with non-zero mass fractions in the input composition. Layers expand by including products of collected reactions until the depth limit. Optionally selects reverse reactions instead of forward.

See implementation in construction.cpp for details on the layering algorithm, logging, and performance.

Parameters

composition	Mapping of isotopic species to their mass fractions; species with positive mass fraction seed the network.
weakInterpolator	Interpolator to build weak rates from. Must be constructed and owned by the caller.
maxLayers	Variant specifying either a predefined NetworkBuildDepth or a custom integer depth; negative depth (Full) collects all reactions, zero is invalid.
ReactionTypes

Precondition

composition must have at least one species with positive mass fraction.

Resolved integer depth from maxLayers must not be zero.

Postcondition

Returned network includes only reactions satisfying the depth and reverse criteria.

Returns

A LogicalReactionSet encapsulating the collected reactions for graph-based engines.

Exceptions

std::logic_error

If the resolved network depth is zero (no reactions can be collected).

calculateCreationRate()

double gridfire::engine::calculateCreationRate	(	const DynamicEngine &	engine,
		const fourdst::atomic::Species &	species,
		const fourdst::composition::Composition &	composition,
		double	T9,
		double	rho,
		const std::optional< std::vector< reaction::ReactionType > > &	reactionTypesToIgnore )

Computes the creation rate for a specific species.

Sums molar reaction flows for all reactions where the species appears as a product (positive stoichiometry).

Parameters

engine	Engine providing the current set of network reactions and flow calculations.
species	The atomic species whose creation rate is computed.
composition	Composition object containing current abundances.
T9	Temperature in units of 10^9 K.
rho	Density of the medium.
reactionTypesToIgnore	types of reactions to ignore during calculation.

Precondition

Y.size() matches engine.getNetworkReactions().size() mapping species order.

Postcondition

Returned creation rate is non-negative.

Returns

Sum of stoichiometry-weighted creation flows for the species.

calculateDestructionRateConstant()

double gridfire::engine::calculateDestructionRateConstant	(	const DynamicEngine &	engine,
		const fourdst::atomic::Species &	species,
		const fourdst::composition::Composition &	composition,
		double	T9,
		double	rho,
		const std::optional< std::vector< reaction::ReactionType > > &	reactionTypesToIgnore )

Computes the destruction rate constant for a specific species.

Calculates the sum of molar reaction flows for all reactions where the species is a reactant (negative stoichiometry) after scaling its abundance to unity.

Parameters

engine	Engine providing the current set of network reactions and flow calculations.
species	The atomic species whose destruction rate is computed.
composition	Current composition providing abundances for all species.
T9	Temperature in units of 10^9 K.
rho	Density of the medium.
reactionTypesToIgnore	types of reactions to ignore during calculation.

Precondition

Y.size() matches engine.getNetworkReactions().size() mapping species order.

Postcondition

Returned rate constant is non-negative.

Returns

Sum of absolute stoichiometry-weighted destruction flows for the species.

engine_type_to_string()

std::string_view gridfire::engine::engine_type_to_string ( const EngineTypes type )

constexpr

Converts an EngineTypes enum value to its corresponding string representation.

Parameters

type	The EngineTypes enum value to convert.

Returns

A string_view representing the name of the engine type.

EngineStatus_to_string()

std::string_view gridfire::engine::EngineStatus_to_string ( const EngineStatus status )

constexpr

Convert EngineStatus enum to string representation.

Parameters

status

The EngineStatus value to convert.

Returns

A string_view representing the name of the EngineStatus.

has_flag()

bool gridfire::engine::has_flag ( const NetworkConstructionFlags flags, const NetworkConstructionFlags flag_to_check )

inline

Checks if a specific flag is set within a NetworkConstructionFlags value.

This function determines whether a particular flag is present in a given NetworkConstructionFlags value.

Parameters

flags	The NetworkConstructionFlags value to check.
flag_to_check	The specific flag to look for.

Returns

True if the flag is set; otherwise, false.

NetworkConstructionFlagsToString()

std::string gridfire::engine::NetworkConstructionFlagsToString ( NetworkConstructionFlags flags )

inline

Converts NetworkConstructionFlags to a human-readable string.

This function generates a comma-separated string representation of the set flags within a NetworkConstructionFlags value. If no flags are set, it returns "No reactions".

Parameters

flags

The NetworkConstructionFlags value to convert.

Returns

A string listing the set flags or "No reactions" if none are set.

operator&()

NetworkConstructionFlags gridfire::engine::operator& ( const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs )

inline

Bitwise AND operator for NetworkConstructionFlags.

This operator allows checking for common flags between two NetworkConstructionFlags values using the bitwise AND operation.

Parameters

lhs	The left-hand side NetworkConstructionFlags value.
rhs	The right-hand side NetworkConstructionFlags value.

Returns

A new NetworkConstructionFlags value representing the intersection of the two inputs.

operator|()

NetworkConstructionFlags gridfire::engine::operator| ( const NetworkConstructionFlags lhs, const NetworkConstructionFlags rhs )

inline

Bitwise OR operator for NetworkConstructionFlags.

This operator allows combining two NetworkConstructionFlags values using the bitwise OR operation.

Parameters

lhs	The left-hand side NetworkConstructionFlags value.
rhs	The right-hand side NetworkConstructionFlags value.

Returns

A new NetworkConstructionFlags value representing the combination of the two inputs.

primeNetwork()

PrimingReport gridfire::engine::primeNetwork	(	const NetIn &	netIn,
		GraphEngine &	engine,
		const std::optional< std::vector< reaction::ReactionType > > &	ignoredReactionTypes )

Primes absent species in the network to their equilibrium abundances.

Executes a network priming algorithm that iteratively rebuilds the reaction network, calculates equilibrium mass fractions for species with zero initial abundance, and applies mass transfers based on reaction flows.

Refer to priming.cpp for implementation details on logging, algorithmic steps, and error handling.

Parameters

netIn	Input network data containing initial composition, temperature, and density.
engine	DynamicEngine used to build and evaluate the reaction network.
ignoredReactionTypes	Types of reactions to ignore during priming (e.g., weak reactions).

Precondition

netIn.composition defines species and their mass fractions; engine is constructed with a valid network.

Postcondition

engine.networkReactions restored to its initial state; returned report contains primedComposition, massFractionChanges for each species, success flag, and status code.

Returns

PrimingReport encapsulating the results of the priming operation.

regularize_jacobian() [1/2]

NetworkJacobian gridfire::engine::regularize_jacobian	(	const NetworkJacobian &	jacobian,
		const fourdst::composition::CompositionAbstract &	comp,
		const std::optional< quill::Logger * >	logger )

regularize_jacobian() [2/2]

NetworkJacobian gridfire::engine::regularize_jacobian	(	const NetworkJacobian &	jacobian,
		const fourdst::composition::CompositionAbstract &	comp,
		std::optional< quill::Logger * >	logger = std::nullopt )

Regularizes the given Jacobian matrix based on the provided composition.

This function applies regularization techniques to the Jacobian matrix to improve its numerical stability. Specifically any (row, column) entries corresponding to species who's abundance is below a threshold of MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN in the provided composition will be set to zero if those entries were either infinite or NaN.

Parameters

jacobian	The NetworkJacobian to be regularized.
comp	The composition used for regularization.
logger	Optional logger for logging regularization steps and information.

Returns

A new NetworkJacobian instance representing the regularized Jacobian matrix.

SpeciesStatus_to_string()

std::string gridfire::engine::SpeciesStatus_to_string ( const SpeciesStatus status )

inline

Convert a SpeciesStatus enum value to its string representation.

Parameters

status

The SpeciesStatus value to convert.

Returns

A string representing the SpeciesStatus.

to_underlying()

auto gridfire::engine::to_underlying ( NetworkConstructionFlags f )

constexprnoexcept

Helper function to convert NetworkConstructionFlags to their underlying integer type.

This function facilitates bitwise operations on NetworkConstructionFlags by converting them to their underlying integer representation.

Parameters

f	The NetworkConstructionFlags value to convert.

Returns

The underlying integer representation of the flag.

Variable Documentation

MIN_ABUNDANCE_THRESHOLD

double gridfire::engine::MIN_ABUNDANCE_THRESHOLD = 1e-18

staticconstexpr

Minimum abundance threshold below which species are ignored.

Species with abundances below this threshold are treated as zero in reaction rate calculations. This helps to improve performance by avoiding unnecessary calculations for trace species.

MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN

double gridfire::engine::MIN_ABUNDANCE_TO_CONTRIBUTE_TO_JACOBIAN = 1e-100

constexpr

Minimum abundance for a species to contribute to the Jacobian.

MIN_DENSITY_THRESHOLD

double gridfire::engine::MIN_DENSITY_THRESHOLD = 1e-18

staticconstexpr

Minimum density threshold below which reactions are ignored.

Reactions are not calculated if the density falls below this threshold. This helps to improve performance by avoiding unnecessary calculations in very low-density regimes.

MIN_JACOBIAN_THRESHOLD

double gridfire::engine::MIN_JACOBIAN_THRESHOLD = 1e-24

staticconstexpr

Minimum value for Jacobian matrix entries.

Jacobian matrix entries with absolute values below this threshold are treated as zero to maintain sparsity and improve performance.

PrimingReportStatusStrings

std::map<PrimingReportStatus, std::string> gridfire::engine::PrimingReportStatusStrings

inline

Initial value:

= {
        {PrimingReportStatus::SUCCESS, "SUCCESS"},
        {PrimingReportStatus::SOLVER_FAILURE, "SOLVER_FAILURE"},
        {PrimingReportStatus::ALREADY_PRIMED, "ALREADY_PRIMED"},
    }

Mapping from PrimingReportStatus codes to human-readable strings.

Used when formatting or logging the priming status. No preconditions. The map contains entries for all PrimingReportStatus values.