GridFire 0.6.0 General Purpose Nuclear Network

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

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

`#include <CVODE_solver_strategy.h>`

Inheritance diagram for gridfire::solver::CVODESolverStrategy:

## Classes
struct | CVODEUserData
| A helper struct to pass C++ context to C-style CVODE callbacks. More...
struct | TimestepContext
| Immutable view of the current integration state passed to callbacks. More...

## Public Types
using | TimestepCallback = std::function<void(const TimestepContext& context)>
| Type alias for a timestep callback.

## Public Member Functions
| CVODESolverStrategy (DynamicEngine &engine)
| Construct the CVODE strategy and create a SUNDIALS context.
| ~CVODESolverStrategy () override
| Destructor: cleans CVODE/SUNDIALS resources and frees SUNContext.
| CVODESolverStrategy (const CVODESolverStrategy &)=delete
CVODESolverStrategy & | operator= (const CVODESolverStrategy &)=delete
| CVODESolverStrategy (CVODESolverStrategy &&)=delete
CVODESolverStrategy & | operator= (CVODESolverStrategy &&)=delete
NetOut | evaluate (const NetIn &netIn) override
| Integrate from t=0 to netIn.tMax and return final composition and energy.
void | set_callback (const std::any &callback) override
| Install a timestep callback.
bool | get_stdout_logging_enabled () const
| Whether per-step logs are printed to stdout and CVode is stepped with CV_ONE_STEP.
void | set_stdout_logging_enabled (const bool value)
| Enable/disable per-step stdout logging.
std::vector< std::tuple< std::string, std::string > > | describe_callback_context () const override
| Schema of fields exposed to the timestep callback context.
Public Member Functions inherited from gridfire::solver::NetworkSolverStrategy< DynamicEngine >
| NetworkSolverStrategy (DynamicEngine &engine)
| Constructor for the NetworkSolverStrategy.
virtual | ~NetworkSolverStrategy ()=default
| Virtual destructor.
| NetworkSolverStrategy (DynamicEngine &engine)
| Constructor for the NetworkSolverStrategy.
virtual | ~NetworkSolverStrategy ()=default
| Virtual destructor.

## Private Member Functions
void | 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 (uint64_t N, size_t numSpecies, double current_time, const fourdst::composition::Composition &composition, double absTol, double relTol, double accumulatedEnergy)
| Allocate and initialize CVODE vectors, linear algebra, tolerances, and constraints.
void | cleanup_cvode_resources (bool memFree)
| Destroy CVODE vectors/linear algebra and optionally the CVODE memory block.
void | log_step_diagnostics (const CVODEUserData &user_data) 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.

## Private Attributes
fourdst::config::Config & | m_config = fourdst::config::Config::getInstance()
quill::Logger * | m_logger = fourdst::logging::LogManager::getInstance().getLogger("log")
SUNContext | m_sun_ctx = nullptr
| SUNDIALS context (lifetime of the solver).
void * | m_cvode_mem = nullptr
| CVODE memory block.
N_Vector | m_Y = nullptr
| CVODE state vector (species + energy accumulator).
N_Vector | m_YErr = nullptr
| Estimated local errors.
SUNMatrix | m_J = nullptr
| Dense Jacobian matrix.
SUNLinearSolver | m_LS = nullptr
| Dense linear solver.
TimestepCallback | m_callback
| Optional per-step callback.
int | m_num_steps = 0
| CVODE step counter (used for diagnostics and triggers).
bool | m_stdout_logging_enabled = true
| If true, print per-step logs and use CV_ONE_STEP.
N_Vector | m_constraints = nullptr
| CVODE constraints vector (>= 0 for species entries).

## Additional Inherited Members
Protected Attributes inherited from gridfire::solver::NetworkSolverStrategy< DynamicEngine >
DynamicEngine & | m_engine
| The engine used by this solver strategy.
DynamicEngine & | 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";
  gridfire::solver::CVODESolverStrategy
  Stiff ODE integrator backed by SUNDIALS CVODE (BDF) for network + energy.
  Definition CVODE_solver_strategy.h:77
  gridfire::solver::CVODESolverStrategy::CVODESolverStrategy
  CVODESolverStrategy(DynamicEngine &engine)
  Construct the CVODE strategy and create a SUNDIALS context.
  Definition CVODE_solver_strategy.cpp:121
  gridfire::solver
  Definition solver.h:12
  gridfire::NetIn
  Definition network.h:51
  gridfire::NetIn::density
  double density
  Density in g/cm^3.
  Definition network.h:56
  gridfire::NetIn::tMax
  double tMax
  Maximum time.
  Definition network.h:53
  gridfire::NetIn::composition
  fourdst::composition::Composition composition
  Composition of the network.
  Definition network.h:52
  gridfire::NetIn::temperature
  double temperature
  Temperature in Kelvin.
  Definition network.h:55

## Member Typedef Documentation

## ◆ TimestepCallback

using gridfire::solver::CVODESolverStrategy::TimestepCallback = std::function<void(const TimestepContext& context)>

Type alias for a timestep callback.

Type alias for a timestep callback function.

## Constructor & Destructor Documentation

## ◆ CVODESolverStrategy() [1/3]

gridfire::solver::CVODESolverStrategy::CVODESolverStrategy | ( | 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.

## ◆ ~CVODESolverStrategy()

gridfire::solver::CVODESolverStrategy::~CVODESolverStrategy | ( |  | ) |
| override

Destructor: cleans CVODE/SUNDIALS resources and frees SUNContext.

## ◆ CVODESolverStrategy() [2/3]

gridfire::solver::CVODESolverStrategy::CVODESolverStrategy | ( | const CVODESolverStrategy & |  | ) |
| delete

## ◆ CVODESolverStrategy() [3/3]

gridfire::solver::CVODESolverStrategy::CVODESolverStrategy | ( | CVODESolverStrategy && |  | ) |
| delete

## Member Function Documentation

## ◆ calculate_rhs()

void gridfire::solver::CVODESolverStrategy::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.

## ◆ cleanup_cvode_resources()

void gridfire::solver::CVODESolverStrategy::cleanup_cvode_resources | ( | bool | memFree | ) |
| private

Destroy CVODE vectors/linear algebra and optionally the CVODE memory block.

Parameters

  memFree | If true, also calls CVodeFree on m_cvode_mem.

## ◆ cvode_jac_wrapper()

int gridfire::solver::CVODESolverStrategy::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 )
| static private

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::CVODESolverStrategy::cvode_rhs_wrapper | ( | sunrealtype | t,
|  | N_Vector | y,
|  | N_Vector | ydot,
|  | void * | user_data )
| static private

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

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

## ◆ describe_callback_context()

std::vector< std::tuple< std::string, std::string > > gridfire::solver::CVODESolverStrategy::describe_callback_context | ( |  | ) | const
| nodiscard override virtual

Schema of fields exposed to the timestep callback context.

Implements gridfire::solver::NetworkSolverStrategy< DynamicEngine >.

## ◆ evaluate()

NetOut gridfire::solver::CVODESolverStrategy::evaluate | ( | const NetIn & | netIn | ) |
| override virtual

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

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

## ◆ get_stdout_logging_enabled()

bool gridfire::solver::CVODESolverStrategy::get_stdout_logging_enabled | ( |  | ) | const
| nodiscard

Whether per-step logs are printed to stdout and CVode is stepped with CV_ONE_STEP.

## ◆ initialize_cvode_integration_resources()

void gridfire::solver::CVODESolverStrategy::initialize_cvode_integration_resources | ( | uint64_t | N,
|  | size_t | numSpecies,
|  | double | current_time,
|  | const fourdst::composition::Composition & | composition,
|  | double | absTol,
|  | double | relTol,
|  | double | accumulatedEnergy )
| 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::CVODESolverStrategy::log_step_diagnostics | ( | const CVODEUserData & | user_data | ) | 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 highest error ratios; then invokes diagnostic routines to inspect Jacobian stiffness and species balance.

## ◆ operator=() [1/2]

CVODESolverStrategy & gridfire::solver::CVODESolverStrategy::operator= | ( | const CVODESolverStrategy & |  | ) |
| delete

## ◆ operator=() [2/2]

CVODESolverStrategy & gridfire::solver::CVODESolverStrategy::operator= | ( | CVODESolverStrategy && |  | ) |
| delete

## ◆ set_callback()

void gridfire::solver::CVODESolverStrategy::set_callback | ( | const std::any & | callback | ) |
| override virtual

Install a timestep callback.

Parameters

  callback | std::any containing TimestepCallback (std::function<void(const TimestepContext&)>).

Exceptions

  std::bad_any_cast | If callback is not of the expected type.

Implements gridfire::solver::NetworkSolverStrategy< DynamicEngine >.

## ◆ set_stdout_logging_enabled()

void gridfire::solver::CVODESolverStrategy::set_stdout_logging_enabled | ( | const bool | value | ) |

Enable/disable per-step stdout logging.

## Member Data Documentation

## ◆ m_callback

TimestepCallback gridfire::solver::CVODESolverStrategy::m_callback
| private

Optional per-step callback.

## ◆ m_config

fourdst::config::Config& gridfire::solver::CVODESolverStrategy::m_config = fourdst::config::Config::getInstance()
| private

## ◆ m_constraints

N_Vector gridfire::solver::CVODESolverStrategy::m_constraints = nullptr
| private

CVODE constraints vector (>= 0 for species entries).

## ◆ m_cvode_mem

void* gridfire::solver::CVODESolverStrategy::m_cvode_mem = nullptr
| private

CVODE memory block.

## ◆ m_J

SUNMatrix gridfire::solver::CVODESolverStrategy::m_J = nullptr
| private

Dense Jacobian matrix.

## ◆ m_logger

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

## ◆ m_LS

SUNLinearSolver gridfire::solver::CVODESolverStrategy::m_LS = nullptr
| private

Dense linear solver.

## ◆ m_num_steps

int gridfire::solver::CVODESolverStrategy::m_num_steps = 0
| private

CVODE step counter (used for diagnostics and triggers).

## ◆ m_stdout_logging_enabled

bool gridfire::solver::CVODESolverStrategy::m_stdout_logging_enabled = true
| private

If true, print per-step logs and use CV_ONE_STEP.

## ◆ m_sun_ctx

SUNContext gridfire::solver::CVODESolverStrategy::m_sun_ctx = nullptr
| private

SUNDIALS context (lifetime of the solver).

## ◆ m_Y

N_Vector gridfire::solver::CVODESolverStrategy::m_Y = nullptr
| private

CVODE state vector (species + energy accumulator).

## ◆ m_YErr

N_Vector gridfire::solver::CVODESolverStrategy::m_YErr = nullptr
| private

Estimated local errors.

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

- src/include/gridfire/solver/strategies/CVODE_solver_strategy.h
- src/lib/solver/strategies/CVODE_solver_strategy.cpp