gridfire::solver::PointSolver Class Reference

Stiff ODE integrator backed by SUNDIALS CVODE (BDF) for network + energy. More...

#include <PointSolver.h>

Inheritance diagram for gridfire::solver::PointSolver:

Collaboration diagram for gridfire::solver::PointSolver:

Classes
struct	CVODERHSOutputData
struct	CVODEUserData
	A helper struct to pass C++ context to C-style CVODE callbacks. More...

Public Member Functions
	PointSolver (const engine::DynamicEngine &engine)
	Construct the CVODE strategy and create a SUNDIALS context.
	PointSolver (const engine::DynamicEngine &engine, const config::GridFireConfig &config)
config::GridFireConfig	getConfig () const
NetOut	evaluate (SolverContextBase &solver_ctx, const NetIn &netIn) const override
	Integrate from t=0 to netIn.tMax and return final composition and energy.
NetOut	evaluate (SolverContextBase &solver_ctx, const NetIn &netIn, bool displayTrigger, bool forceReinitialize=false) const
	Call to evaluate which will let the user control if the trigger reasoning is displayed.
Public Member Functions inherited from gridfire::solver::SingleZoneNetworkSolver< engine::DynamicEngine >
	SingleZoneNetworkSolver (const EngineT &engine)
	Constructor for the NetworkSolverStrategy.
virtual	~SingleZoneNetworkSolver ()=default
	Virtual destructor.
	SingleZoneNetworkSolver (const EngineT &engine)
	Constructor for the NetworkSolverStrategy.
virtual	~SingleZoneNetworkSolver ()=default
	Virtual destructor.

Private Member Functions
CVODERHSOutputData	calculate_rhs (sunrealtype t, N_Vector y, N_Vector ydot, const CVODEUserData *data) const
	Compute RHS into ydot at time t from the engine and current state y.
void	initialize_cvode_integration_resources (PointSolverContext *ctx, uint64_t N, size_t numSpecies, double current_time, const fourdst::composition::Composition &composition, double absTol, double relTol, double accumulatedEnergy) const
	Allocate and initialize CVODE vectors, linear algebra, tolerances, and constraints.
void	log_step_diagnostics (PointSolverContext *sctx_p, engine::scratch::StateBlob &ctx, const CVODEUserData &user_data, bool displayJacobianStiffness, bool displaySpeciesBalance, bool to_file, std::optional< std::string > filename) const
	Compute and print per-component error ratios; run diagnostic helpers.

Static Private Member Functions
static int	cvode_rhs_wrapper (sunrealtype t, N_Vector y, N_Vector ydot, void *user_data)
	CVODE RHS C-wrapper that delegates to calculate_rhs and captures exceptions.
static int	cvode_jac_wrapper (sunrealtype t, N_Vector y, N_Vector ydot, SUNMatrix J, void *user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
	CVODE dense Jacobian C-wrapper that fills SUNDenseMatrix using the engine.
static void	cvode_error_handler (int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)
	CVODE error handler that logs errors and warnings from SUNDIALS using the solver's logger.

Private Attributes
fourdst::config::Config< config::GridFireConfig >	m_config
quill::Logger *	m_logger = fourdst::logging::LogManager::getInstance().getLogger("log")

Additional Inherited Members
Protected Attributes inherited from gridfire::solver::SingleZoneNetworkSolver< engine::DynamicEngine >
const EngineT &	m_engine
	The engine used by this solver strategy.
const EngineT &	m_engine
	The engine used by this solver strategy.

Detailed Description

Stiff ODE integrator backed by SUNDIALS CVODE (BDF) for network + energy.

Integrates the nuclear network abundances along with a final accumulator entry for specific energy using CVODE's BDF method and a dense linear solver. The state vector layout is: [y_0, y_1, ..., y_{N-1}, eps], where eps is the accumulated specific energy (erg/g).

Implementation summary:

• Creates a SUNContext and CVODE memory; initializes the state from a Composition.
• Enforces non-negativity on species via CVodeSetConstraints (>= 0 for all species slots).
• Uses a user-provided DynamicEngine to compute RHS and to fill the dense Jacobian.
• The Jacobian is assembled column-major into a SUNDenseMatrix; the energy row/column is currently set to zero (decoupled from abundances in the linearization).
• An internal trigger can rebuild the engine/network; when triggered, CVODE resources are torn down and recreated with the new network size, preserving the energy accumulator.
• The CVODE RHS wrapper captures exceptions::StaleEngineTrigger from the engine evaluation path as recoverable (return code 1) and stores a copy in user-data for the driver loop.

Example

using gridfire::solver::CVODESolverStrategy;
using gridfire::solver::NetIn;
 
CVODESolverStrategy solver(engine);
NetIn in;
in.temperature = 1.0e9; // K
in.density = 1.0e6;     // g/cm^3
in.tMax = 1.0;          // s
in.composition = initialComposition;
auto out = solver.evaluate(in);
std::cout << "Final energy: " << out.energy << " erg/g\n";

Constructor & Destructor Documentation

PointSolver() [1/2]

gridfire::solver::PointSolver::PointSolver ( const engine::DynamicEngine & engine )

explicit

Construct the CVODE strategy and create a SUNDIALS context.

Parameters

engine

DynamicEngine used for RHS/Jacobian evaluation and network access.

Exceptions

std::runtime_error

If SUNContext_Create fails.

PointSolver() [2/2]

gridfire::solver::PointSolver::PointSolver	(	const engine::DynamicEngine &	engine,
		const config::GridFireConfig &	config )

Member Function Documentation

calculate_rhs()

PointSolver::CVODERHSOutputData gridfire::solver::PointSolver::calculate_rhs ( sunrealtype t, N_Vector y, N_Vector ydot, const CVODEUserData * data ) const

private

Compute RHS into ydot at time t from the engine and current state y.

Converts the CVODE state to a Composition (mass fractions) and calls engine.calculateRHSAndEnergy(T9, rho). Negative small abundances are clamped to zero before constructing Composition. On stale engine, throws exceptions::StaleEngineTrigger.

cvode_error_handler()

void gridfire::solver::PointSolver::cvode_error_handler ( int line, const char * func, const char * file, const char * msg, SUNErrCode err_code, void * err_user_data, SUNContext sunctx )

staticprivate

CVODE error handler that logs errors and warnings from SUNDIALS using the solver's logger.

Parameters

line
func
file
msg
err_code
err_user_data
sunctx

cvode_jac_wrapper()

int gridfire::solver::PointSolver::cvode_jac_wrapper ( sunrealtype t, N_Vector y, N_Vector ydot, SUNMatrix J, void * user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3 )

staticprivate

CVODE dense Jacobian C-wrapper that fills SUNDenseMatrix using the engine.

Assembles J(i,j) = d(f_i)/d(y_j) for all species using engine->getJacobianMatrixEntry, then zeros the last row and column corresponding to the energy variable.

cvode_rhs_wrapper()

int gridfire::solver::PointSolver::cvode_rhs_wrapper ( sunrealtype t, N_Vector y, N_Vector ydot, void * user_data )

staticprivate

CVODE RHS C-wrapper that delegates to calculate_rhs and captures exceptions.

Returns

0 on success; 1 on recoverable StaleEngineTrigger; -1 on other failures.

evaluate() [1/2]

NetOut gridfire::solver::PointSolver::evaluate ( SolverContextBase & solver_ctx, const NetIn & netIn ) const

overridevirtual

Integrate from t=0 to netIn.tMax and return final composition and energy.

Implementation summary:

• Converts temperature to T9, initializes CVODE memory and state (size = numSpecies + 1).
• Repeatedly calls CVode in single-step or normal mode depending on stdout logging.
• Wraps RHS to capture exceptions::StaleEngineTrigger as a recoverable step failure; if present after a step, it is rethrown for upstream handling.
• Prints/collects diagnostics per step (step size, energy, solver iterations).
• On trigger activation, rebuilds CVODE resources to reflect a changed network and reinitialized the state using the latest engine composition, preserving energy.
• At the end, converts molar abundances to mass fractions and assembles NetOut, including derivatives of energy w.r.t. T and rho from the engine.

Parameters

solver_ctx
netIn	Inputs: temperature [K], density [g cm^-3], tMax [s], composition.

Returns

NetOut containing final Composition, accumulated energy [erg/g], step count, and dEps/dT, dEps/dRho.

Exceptions

std::runtime_error	If any CVODE or SUNDIALS call fails (negative return codes), or if internal consistency checks fail during engine updates.
exceptions::StaleEngineTrigger	Propagated if the engine signals a stale state during RHS evaluation (captured in the wrapper then rethrown here).

Implements gridfire::solver::SingleZoneNetworkSolver< engine::DynamicEngine >.

evaluate() [2/2]

NetOut gridfire::solver::PointSolver::evaluate	(	SolverContextBase &	solver_ctx,
		const NetIn &	netIn,
		bool	displayTrigger,
		bool	forceReinitialize = false ) const

Call to evaluate which will let the user control if the trigger reasoning is displayed.

Parameters

solver_ctx
netIn	Inputs: temperature [K], density [g cm^-3], tMax [s], composition.
displayTrigger	Boolean flag to control if trigger reasoning is displayed
forceReinitialize	Boolean flag to force reinitialization of CVODE resources at the start

Returns

NetOut containing final Composition, accumulated energy [erg/g], step count, and dEps/dT, dEps/dRho.

Exceptions

std::runtime_error	If any CVODE or SUNDIALS call fails (negative return codes), or if internal consistency checks fail during engine updates.
exceptions::StaleEngineTrigger	Propagated if the engine signals a stale state during RHS evaluation (captured in the wrapper then rethrown here).

getConfig()

config::GridFireConfig gridfire::solver::PointSolver::getConfig ( ) const

inline

initialize_cvode_integration_resources()

void gridfire::solver::PointSolver::initialize_cvode_integration_resources ( PointSolverContext * ctx, uint64_t N, size_t numSpecies, double current_time, const fourdst::composition::Composition & composition, double absTol, double relTol, double accumulatedEnergy ) const

private

Allocate and initialize CVODE vectors, linear algebra, tolerances, and constraints.

State vector m_Y is sized to N (numSpecies + 1). Species slots are initialized from Composition molar abundances when present, otherwise a tiny positive value; the last slot is set to accumulatedEnergy. Sets scalar tolerances, non-negativity constraints for species, maximum step size, creates a dense matrix and dense linear solver, and registers the Jacobian.

log_step_diagnostics()

void gridfire::solver::PointSolver::log_step_diagnostics ( PointSolverContext * sctx_p, engine::scratch::StateBlob & ctx, const CVODEUserData & user_data, bool displayJacobianStiffness, bool displaySpeciesBalance, bool to_file, std::optional< std::string > filename ) const

private

Compute and print per-component error ratios; run diagnostic helpers.

Gathers CVODE's estimated local errors, converts the state to a Composition, and prints a sorted table of species with the highest error ratios; then invokes diagnostic routines to inspect Jacobian stiffness and species balance.

Member Data Documentation

m_config

fourdst::config::Config<config::GridFireConfig> gridfire::solver::PointSolver::m_config

private

m_logger

quill::Logger* gridfire::solver::PointSolver::m_logger = fourdst::logging::LogManager::getInstance().getLogger("log")

private

---

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

• src/include/gridfire/solver/strategies/PointSolver.h
• src/lib/solver/strategies/PointSolver.cpp