The python bindings intentionally look very similar to the C++ code. Generally all examples can be adapted to python by replacing includes of paths with imports of modules such that
-#include "gridfire/engine/GraphEngine.h</tt> becomes <tt>import gridfire.engine.GraphEngine</tt>
-
-All GridFire C++ types have been bound and can be passed around as one would expect.
-
-@subsubsection autotoc_md53 Common Workflow Examople
-This example impliments the same logic as the above C++ example
-@icode{python}
-import gridfire
-
-
-from fourdst.composition import Composition
-
-symbols = ["H-1", ...]
-X = [0.7, ...]
-
-comp = Composition()
-comp.registerSymbols(symbols)
-comp.setMassFraction(X)
-comp.finalize(true)
-# Initialize GraphEngine with predefined composition
-engine = gridfire.GraphEngine(comp)
-netIn = gridfire.types.NetIn
-netIn.composition = comp
-netIn.tMax = 1e-3
-netIn.temperature = 1.5e7
-netIn.density = 1.6e2
-netIn.dt0 = 1e-12
-
-# Perform one integration step
-netOut = engine.evaluate(netIn)
-print(netOut)
-@endicode
-
-
-
-@section autotoc_md54 Related Projects
-
-GridFire integrates with and builds upon several key 4D-STAR libraries:
-
-- <a href="https://github.com/4D-STAR/fourdst" >fourdst</a>: hub module managing versioning
- of <tt>libcomposition</tt>, <tt>libconfig</tt>, <tt>liblogging</tt>, and <tt>libconstants</tt>
-- <a href="https://github.com/4D-STAR/libcomposition" >libcomposition</a>
- (<a href="https://4d-star.github.io/libcomposition/" >docs</a>): Composition management
- toolkit.
-- <a href="https://github.com/4D-STAR/libconfig" >libconfig</a>: Configuration file parsing
- utilities.
-- <a href="https://github.com/4D-STAR/liblogging" >liblogging</a>: Flexible logging framework.
-- <a href="https://github.com/4D-STAR/libconstants" >libconstants: Physical constants
#include "gridfire/engine/GraphEngine.h" becomes import gridfire.engine.GraphEngine
All GridFire C++ types have been bound and can be passed around as one would expect.
+This example impliments the same logic as the above C++ example
GridFire integrates with and builds upon several key 4D-STAR libraries:
+libcomposition, libconfig, liblogging, and libconstantsA graph-first nuclear network supporting dynamic network topologies. GridFire is intended to be easy to use and very adaptable to a variety of physical situations.
+A C++ library designed to perform general nuclear network evolution as part of the 4D-STAR collaboration. GridFire focuses on modeling the most relevant burning stages for stellar evolution with a balanced approach to physical fidelity, computational efficiency, and extensibility.
GridFire is written in C++ but we maintain a robust set of Python bindings. These call the underlying C++ code, meaning that they are nearly as performant as the raw C++. Here we provide a short demonstration of how to use GridFire in Python.
-GridFire separates the network into four main parts.
-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. A GraphNetwork uses JINA Reaclib reaction rates along with a dynamically constructed network topology.
+ +GridFire is organized into composable modules, each responsible for a specific aspect of nuclear reaction network modeling:
+from gridfire import GraphEngine, DirectSolver, NetIn
-from gridfire.composition import Composition
-baseComposition = Composition(["H-1", "He-4"], [0.7, 0.3])
-engine = GraphEngine(baseComposition)
-solver = DirectSolver(engine)
+
+ Installation
+ The easiest way to install GridFire is through pip, which will install pre-compiled wheels or build locally if needed:
+ pip install gridfire
+ GridFire can also be built from source using the provided installation scripts or manual build instructions. The library requires a C++ compiler supporting C++23, Meson build system, and Boost libraries (≥1.83.0).
+
+ Key Features
+
+ - Graph-based Network Construction: GraphEngine recursively constructs reaction networks from seed compositions following JINA Reaclib pathways.
+ - Layered View Strategy: Partitioning algorithms isolate fast and slow processes, adaptive culling removes negligible reactions, and implicit solvers handle stiff systems.
+ - Multiple Engine Views: Including adaptive culling, multiscale partitioning, and network priming for different simulation needs.
+ - Automatic Differentiation: Uses CppAD to generate analytic Jacobian matrices efficiently for improved solver performance.
+ - Python Extensibility: Users can subclass engine views directly in Python and pass instances back to C++ solvers.
+
+
+ Simple Python Example
+ import gridfire
+from fourdst.composition import Composition
-inputParams = NetIn(composition, 0.1, 100, 0, 1e17, 1e-16) // (composition, T9, density, intialEnergy, tMax, dt0)
-results = solver.evaluate(inputParams)
+# Create initial composition
+comp = Composition()
+symbols = ["H-1", "He-4", "C-12"]
+massFractions = [0.7, 0.29, 0.01]
+comp.registerSymbols(symbols)
+comp.setMassFraction(symbols, massFractions)
+comp.finalize(True)
+
+# Initialize engine and solver
+baseEngine = gridfire.GraphEngine(comp, gridfire.NetworkBuildDepth.SecondOrder)
+adaptiveView = gridfire.AdaptiveEngineView(baseEngine)
+solver = gridfire.DirectNetworkSolver(adaptiveView)
+
+# Set up integration parameters
+netIn = gridfire.types.NetIn()
+netIn.composition = comp
+netIn.temperature = 1.5e7 # K
+netIn.density = 1.5e2 # g/cm^3
+netIn.dt0 = 1e-12 # s
+netIn.tMax = 3e17 # s
+
+# Perform integration
+netOut = solver.evaluate(netIn)
+print(f"Integration completed in {netOut.num_steps} steps")