GridFire

C++ Nuclear Network Evolution Library

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.

Read the Docs Workflow Chart View on GitHub

About GridFire

Design Philosophy

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.

Architecture Overview

GridFire is organized into composable modules, each responsible for a specific aspect of nuclear reaction network modeling:

  • Engine Module: Core interfaces and implementations (e.g., GraphEngine) that evaluate reaction network rate equations and energy generation.
  • Engine Views Module: Composable engine optimization and modification (e.g., MultiscalePartitioningEngineView) which can be used to make problems more tractable.
  • Screening Module: Implements nuclear reaction screening corrections affecting reaction rates.
  • Reaction Module: Parses and manages Reaclib reaction rate data, providing temperature- and density-dependent rate evaluations.
  • Partition Module: Implements partition functions to weight reaction rates based on nuclear properties.
  • Solver Module: Defines numerical integration strategies for solving stiff ODE systems arising from reaction networks.
  • Python Interface: Exposes almost all C++ functionality to Python for ease of use.

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

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