<p>GridFire is a C++ library designed to perform general nuclear network evolution using the Reaclib library. It is part of the larger SERiF project within the 4D-STAR collaboration.</p>
<p><b>Design Philosophy and Workflow:</b> GridFire is architected to balance physical fidelity, computational efficiency, and extensibility when simulating complex nuclear reaction networks. Users begin by defining a composition, which is used to construct a full GraphEngine representation of the reaction network. To manage the inherent stiffness and multi-scale nature of these networks, GridFire employs a layered view strategy: partitioning algorithms isolate fast and slow processes, adaptive culling removes negligible reactions at runtime, and implicit solvers stably integrate the remaining stiff system. This modular pipeline allows researchers to tailor accuracy versus performance trade-offs, reuse common engine components, and extend screening or partitioning models without modifying core integration routines.</p>
<p>GridFire is a part of the 4D-STAR collaboration.</p>
<p>4D-STAR is funded by European Research Council (ERC) under the Horizon Europe programme (Synergy Grant agreement No. 101071505: 4D-STAR) Work for this project is funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research.</p>
</div><!-- fragment --><h3><aclass="anchor"id="autotoc_md7"></a>
Python Bindings and Installation</h3>
<p>The Python interface is provided via <code>meson-python</code> and <code>pybind11</code>. To install the Python package: </p><divclass="fragment"><divclass="line">pip install .</div>
</div><!-- fragment --><h3><aclass="anchor"id="autotoc_md8"></a>
Developer Workflow</h3>
<oltype="1">
<li>Clone the repository and install dependencies listed in <code>pyproject.toml</code>.</li>
<li>Configure and build with Meson: <divclass="fragment"><divclass="line">meson setup build</div>
<divclass="line">meson compile -C build</div>
</div><!-- fragment --></li>
<li>Run the unit tests: <divclass="fragment"><divclass="line">meson test -C build</div>
</div><!-- fragment --></li>
<li>Iterate on code, rebuild, and rerun tests.</li>
</ol>
<h2><aclass="anchor"id="autotoc_md9"></a>
Code Architecture and Logical Flow</h2>
<p>GridFire is organized into modular components that collaborate to simulate nuclear reaction networks with high fidelity:</p>
<li><b>Engine Module:</b> Core interfaces and implementations (e.g., <code>GraphEngine</code>) that evaluate reaction network rate equations and energy generation.</li>
<li><b>Rates Module:</b> Parses and manages Reaclib reaction rate data, providing temperature- and density-dependent rate evaluations.</li>
<li><b>Python Interface:</b> Exposes C++ functionality to Python, enabling rapid prototyping and integration into workflows.</li>
</ul>
<h3><aclass="anchor"id="autotoc_md10"></a>
GraphEngine Configuration Options</h3>
<p>GraphEngine exposes runtime configuration methods to tailor network construction and rate evaluations:</p>
<ul>
<li><b>Constructor Parameters:</b><ul>
<li><code>BuildDepthType</code> (<code>Full</code>/<code>Reduced</code>/<code>Minimal</code>): controls network build depth, trading startup time for network completeness.</li>
<li><code>partition::PartitionFunction</code>: custom functor for network partitioning based on <code>Z</code>, <code>A</code>, and <code>T9</code>.</li>
<li>Toggle inclusion of reverse (detailed balance) reactions.</li>
<li><em>Effect:</em> Improves equilibrium fidelity; increases network size and stiffness.</li>
</ul>
</li>
</ul>
<h3><aclass="anchor"id="autotoc_md11"></a>
Available Partition Functions</h3>
<tableclass="markdownTable">
<trclass="markdownTableHead">
<thclass="markdownTableHeadNone">Function Name </th><thclass="markdownTableHeadNone">Identifier </th><thclass="markdownTableHeadNone">Description </th></tr>
<trclass="markdownTableRowOdd">
<tdclass="markdownTableBodyNone"><code>GroundStatePartitionFunction</code></td><tdclass="markdownTableBodyNone">"GroundState" </td><tdclass="markdownTableBodyNone">Weights using nuclear ground-state spin factors. </td></tr>
<trclass="markdownTableRowEven">
<tdclass="markdownTableBodyNone"><code>RauscherThielemannPartitionFunction</code></td><tdclass="markdownTableBodyNone">"RauscherThielemann" </td><tdclass="markdownTableBodyNone">Interpolates normalized g-factors per Rauscher & Thielemann. </td></tr>
</div><!-- fragment --><h2><aclass="anchor"id="autotoc_md12"></a>
Engine Views</h2>
<p>The GridFire engine supports multiple engine view strategies to adapt or restrict network topology. Each view implements a specific algorithm:</p>
<tableclass="markdownTable">
<trclass="markdownTableHead">
<thclass="markdownTableHeadNone">View Name </th><thclass="markdownTableHeadNone">Purpose </th><thclass="markdownTableHeadNone">Algorithm / Reference </th><thclass="markdownTableHeadNone">When to Use </th></tr>
<trclass="markdownTableRowOdd">
<tdclass="markdownTableBodyNone">AdaptiveEngineView </td><tdclass="markdownTableBodyNone">Dynamically culls low-flow species and reactions during runtime </td><tdclass="markdownTableBodyNone">Iterative flux thresholding to remove reactions below a flow threshold </td><tdclass="markdownTableBodyNone">Large networks to reduce computational cost </td></tr>
<trclass="markdownTableRowEven">
<tdclass="markdownTableBodyNone">DefinedEngineView </td><tdclass="markdownTableBodyNone">Restricts the network to a user-specified subset of species and reactions </td><tdclass="markdownTableBodyNone">Static network masking based on user-provided species/reaction lists </td><tdclass="markdownTableBodyNone">Targeted pathway studies or code-to-code comparisons </td></tr>
<trclass="markdownTableRowOdd">
<tdclass="markdownTableBodyNone">MultiscalePartitioningEngineView </td><tdclass="markdownTableBodyNone">Partitions the network into fast and slow subsets based on reaction timescales </td><tdclass="markdownTableBodyNone">Network partitioning following Hix & Thielemann Silicon Burning I & II (DOI:10.1086/177016,10.1086/306692) </td><tdclass="markdownTableBodyNone">Stiff, multi-scale networks requiring tailored integration </td></tr>
<trclass="markdownTableRowEven">
<tdclass="markdownTableBodyNone">NetworkPrimingEngineView </td><tdclass="markdownTableBodyNone">Primes the network with an initial species or set of species for ignition studies </td><tdclass="markdownTableBodyNone">Single-species injection with transient flow analysis </td><tdclass="markdownTableBodyNone">Investigations of ignition triggers or initial seed sensitivities </td></tr>
</table>
<p>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 <code>EngineView</code> base class, and linked into the composition chain without modifying core engine code.</p>
<p><b>Python Extensibility:</b> Through the Python bindings, users can subclass engine view classes directly in Python, override methods like <code>evaluate</code> or <code>generateStoichiometryMatrix</code>, and pass instances back into C++ solvers. This enables rapid prototyping of custom view strategies without touching C++ sources.</p>
<h2><aclass="anchor"id="autotoc_md13"></a>
Numerical Solver Strategies</h2>
<p>GridFire defines a flexible solver architecture through the <code>networkfire::solver::NetworkSolverStrategy</code> interface, enabling multiple ODE integration algorithms to be used interchangeably with any engine that implements the <code>Engine</code> or <code>DynamicEngine</code> contract.</p>
<li><b>Integrator:</b> Implicit Rosenbrock4 scheme (order 4) via Boost.Odeint’s <code>rosenbrock4<double></code>, optimized for stiff reaction networks with adaptive step size control using configurable absolute and relative tolerances.</li>
<li><b>Jacobian Assembly:</b> Employs the <code>JacobianFunctor</code> to assemble the Jacobian matrix (∂f/∂Y) at each step, enabling stable implicit integration.</li>
<li><b>RHS Evaluation:</b> Continues to use the <code>RHSManager</code> to compute and cache derivative evaluations and specific energy rates, minimizing redundant computations.</li>
<li><b>Linear Algebra:</b> Utilizes Boost.uBLAS for state vectors and dense Jacobian matrices, with sparse access patterns supported via coordinate lists of nonzero entries.</li>
<li><b>Error Control and Logging:</b> Absolute and relative tolerance parameters (<code>absTol</code>, <code>relTol</code>) are read from configuration; Quill logger captures integration diagnostics and step statistics.</li>
<li><b>Initialization:</b> Convert input temperature to T9 units, retrieve tolerances, and initialize state vector <code>Y</code> from equilibrated composition.</li>
<li><b>Integrator Setup:</b> Construct the controlled Rosenbrock4 stepper and bind <code>RHSManager</code> and <code>JacobianFunctor</code>.</li>
<li><b>Adaptive Integration Loop:</b><ul>
<li>Perform <code>integrate_adaptive</code> advancing until <code>tMax</code>, catching any <code>StaleEngineTrigger</code> to repartition the network and update composition.</li>
<li>On each substep, observe states and log via <code>RHSManager::observe</code>.</li>
</ul>
</li>
<li><b>Finalization:</b> Assemble final mass fractions, compute accumulated energy, and populate <code>NetOut</code> with updated composition and diagnostics.</li>
<li><b>Operator Splitting Solvers:</b> Strategies to decouple thermodynamics, screening, and reaction substeps for performance on stiff, multi-scale networks.</li>
<li><b>GPU-Accelerated Solvers:</b> Planned use of CUDA/OpenCL backends for large-scale network integration.</li>
<p>These strategies can be developed by inheriting from <code>NetworkSolverStrategy</code> and registering against the same engine types without modifying existing engine code.</p>
<divclass="ttc"id="aclassgridfire_1_1_graph_engine_html"><divclass="ttname"><ahref="classgridfire_1_1_graph_engine.html">gridfire::GraphEngine</a></div><divclass="ttdoc">A reaction network engine that uses a graph-based representation.</div><divclass="ttdef"><b>Definition</b><ahref="engine__graph_8h_source.html#l00101">engine_graph.h:101</a></div></div>
<divclass="ttc"id="aclassgridfire_1_1_adaptive_engine_view_html"><divclass="ttname"><ahref="classgridfire_1_1_adaptive_engine_view.html">gridfire::AdaptiveEngineView</a></div><divclass="ttdoc">An engine view that dynamically adapts the reaction network based on runtime conditions.</div><divclass="ttdef"><b>Definition</b><ahref="engine__adaptive_8h_source.html#l00050">engine_adaptive.h:50</a></div></div>
<divclass="line"><spanclass="comment"># Perform one integration step</span></div>
<divclass="line">engine.step(dt=1e-3)</div>
<divclass="line">print(engine.abundances)</div>
</div><!-- fragment --><h2><aclass="anchor"id="autotoc_md21"></a>
Common Workflow Example</h2>
<p>A representative workflow often composes multiple engine views to balance accuracy, stability, and performance when integrating stiff nuclear networks:</p>
<divclass="ttc"id="aclassgridfire_1_1_multiscale_partitioning_engine_view_html"><divclass="ttname"><ahref="classgridfire_1_1_multiscale_partitioning_engine_view.html">gridfire::MultiscalePartitioningEngineView</a></div><divclass="ttdoc">An engine view that partitions the reaction network into multiple groups based on timescales.</div><divclass="ttdef"><b>Definition</b><ahref="engine__multiscale_8h_source.html#l00174">engine_multiscale.h:174</a></div></div>
</div><!-- fragment --><p><b>Workflow Components and Effects:</b></p><ul>
<li><b>GraphEngine</b> constructs the full reaction network, capturing all species and reactions.</li>
<li><b>MultiscalePartitioningEngineView</b> segregates reactions by characteristic timescales (Hix & Thielemann), reducing the effective stiffness by treating fast processes separately.</li>
<li><b>AdaptiveEngineView</b> prunes low-flux species/reactions at runtime, decreasing dimensionality and improving computational efficiency.</li>
<li><b>DirectNetworkSolver</b> employs an implicit Rosenbrock method to stably integrate the remaining stiff system with adaptive step control.</li>
</ul>
<p>This layered approach enhances stability for stiff networks while maintaining accuracy and performance.</p>
<h2><aclass="anchor"id="autotoc_md22"></a>
Related Projects</h2>
<p>GridFire integrates with and builds upon several key 4D-STAR libraries:</p>
<ul>
<li><ahref="https://github.com/4D-STAR/fourdst">fourdst</a>: hub module managing versioning of <code>libcomposition</code>, <code>libconfig</code>, <code>liblogging</code>, and <code>libconstants</code></li>
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<ul>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.13.2 </li>
