> **Note:** Boost is the only external library dependency; no additional libraries are required beyond a C++ compiler, Meson, Python, CMake, and Boost.
> **Note:** Windows is not supported at this time and *there are no plans to support it in the future*. Windows users are encouraged to use WSL2 or a Linux VM.
GridFire is organized into a series of composable modules, each responsible for a specific aspect of nuclear reaction network modeling. The core components include:
- **Reaction Module:** Parses and manages Reaclib reaction rate data, providing temperature- and density-dependent rate evaluations.
- **Partition Module:** Implements partition functions (e.g., `GroundStatePartitionFunction`, `RauscherThielemannPartitionFunction`) to weight reaction rates based on nuclear properties.
- **Solver Module:** Defines numerical integration strategies (e.g., `DirectNetworkSolver`) for solving the stiff ODE systems arising from reaction networks.
- **Python Interface:** Exposes *almost* all C++ functionality to Python, allowing users to define compositions, configure engines, and run simulations directly from Python scripts.
Generally a user will start by selecting a base engine (currently we only offer `GraphEngine`), which constructs the
full reaction network graph from a given composition. The user can then apply various engine views to adapt the network
topology, such as partitioning fast and slow reactions, adaptively culling low-flow pathways, or priming the network
with specific species. Finally, a numerical solver is selected to integrate the network over time, producing updated
| AdaptiveEngineView | Dynamically culls low-flow species and reactions during runtime | Iterative flux thresholding to remove reactions below a flow threshold | Large networks to reduce computational cost |
| DefinedEngineView | Restricts the network to a user-specified subset of species and reactions | Static network masking based on user-provided species/reaction lists | Targeted pathway studies or code-to-code comparisons |
| MultiscalePartitioningEngineView | Partitions the network into fast and slow subsets based on reaction timescales | Network partitioning following Hix & Thielemann Silicon Burning I & II (DOI:10.1086/177016,10.1086/306692)| Stiff, multi-scale networks requiring tailored integration |
| NetworkPrimingEngineView | Primes the network with an initial species or set of species for ignition studies| Single-species injection with transient flow analysis | Investigations of ignition triggers or initial seed sensitivities|
These engine views implement the common Engine interface and may be composed in any order to build complex network pipelines. New view types can be added by deriving from the `EngineView` base class, and linked into the composition chain without modifying core engine code.
**Python Extensibility:**
Through the Python bindings, users can subclass engine view classes directly in Python, override methods like `evaluate` or `generateStoichiometryMatrix`, and pass instances back into C++ solvers. This enables rapid prototyping of custom view strategies without touching C++ sources.
## Numerical Solver Strategies
GridFire defines a flexible solver architecture through the `networkfire::solver::NetworkSolverStrategy` interface, enabling multiple ODE integration algorithms to be used interchangeably with any engine that implements the `Engine` or `DynamicEngine` contract.
- **NetworkSolverStrategy<EngineT>**: Abstract strategy templated on an engine type. Requires implementation of:
```cpp
NetOut evaluate(const NetIn& netIn);
```
which integrates the network over one timestep and returns updated abundances, temperature, density, and diagnostics.
- **Integrator:** Implicit Rosenbrock4 scheme (order 4) via Boost.Odeint’s `rosenbrock4<double>`, optimized for stiff reaction networks with adaptive step size control using configurable absolute and relative tolerances.
- **Jacobian Assembly:** Employs the `JacobianFunctor` to assemble the Jacobian matrix (∂f/∂Y) at each step, enabling stable implicit integration.
- **RHS Evaluation:** Continues to use the `RHSManager` to compute and cache derivative evaluations and specific energy rates, minimizing redundant computations.
- **Linear Algebra:** Utilizes Boost.uBLAS for state vectors and dense Jacobian matrices, with sparse access patterns supported via coordinate lists of nonzero entries.
- **Error Control and Logging:** Absolute and relative tolerance parameters (`absTol`, `relTol`) are read from configuration; Quill logger captures integration diagnostics and step statistics.
### Algorithmic Workflow in DirectNetworkSolver
1.**Initialization:** Convert input temperature to T9 units, retrieve tolerances, and initialize state vector `Y` from equilibrated composition.
2.**Integrator Setup:** Construct the controlled Rosenbrock4 stepper and bind `RHSManager` and `JacobianFunctor`.
3.**Adaptive Integration Loop:**
- Perform `integrate_adaptive` advancing until `tMax`, catching any `StaleEngineTrigger` to repartition the network and update composition.
- On each substep, observe states and log via `RHSManager::observe`.
4.**Finalization:** Assemble final mass fractions, compute accumulated energy, and populate `NetOut` with updated composition and diagnostics.
### Future Solver Implementations
- **Operator Splitting Solvers:** Strategies to decouple thermodynamics, screening, and reaction substeps for performance on stiff, multi-scale networks.
- **GPU-Accelerated Solvers:** Planned use of CUDA/OpenCL backends for large-scale network integration.
These strategies can be developed by inheriting from `NetworkSolverStrategy` and registering against the same engine types without modifying existing engine code.
A representative workflow often composes multiple engine views to balance accuracy, stability, and performance when integrating stiff nuclear networks:
- **GraphEngine** constructs the full reaction network, capturing all species and reactions.
- **MultiscalePartitioningEngineView** segregates reactions by characteristic timescales (Hix & Thielemann), reducing the effective stiffness by treating fast processes separately.
- **AdaptiveEngineView** prunes low-flux species/reactions at runtime, decreasing dimensionality and improving computational efficiency.
- **DirectNetworkSolver** employs an implicit Rosenbrock method to stably integrate the remaining stiff system with adaptive step control.
This layered approach enhances stability for stiff networks while maintaining accuracy and performance.
## Related Projects
GridFire integrates with and builds upon several key 4D-STAR libraries:
- [fourdst](https://github.com/4D-STAR/fourdst): hub module managing versioning of `libcomposition`, `libconfig`, `liblogging`, and `libconstants`
