Loading...
Searching...
No Matches
gridfire::solver::PointSolver Class Referencefinal

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

`#include <PointSolver.h>`

Inheritance diagram for gridfire::solver::PointSolver:
[legend]
Collaboration diagram for gridfire::solver::PointSolver:
[legend]

## 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";
  gridfire::engine
  Definition dynamic_engine_diagnostics.h:39
  gridfire::solver
  Definition GridSolver.h:7
  gridfire::NetIn
  Definition types.h:27
  gridfire::NetIn::density
  double density
  Density in g/cm^3.
  Definition types.h:32
  gridfire::NetIn::tMax
  double tMax
  Maximum time.
  Definition types.h:29
  gridfire::NetIn::composition
  fourdst::composition::Composition composition
  Composition of the network.
  Definition types.h:28
  gridfire::NetIn::temperature
  double temperature
  Temperature in Kelvin.
  Definition types.h:31

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