This tutorial walks you through installing GridFire’s Python bindings, choosing engines and views thoughtfully, running a simulation, and visualizing your results.

1. Installation

1.1 PyPI Release

The quickest way to get started is:

pip install gridfire

1.2 Development from Source

If you want the cutting-edge features or need to hack the C++ backend:

git clone https://github.com/4DSTAR/GridFire.git
cd GridFire
# Create a virtualenv to isolate dependencies
python3 -m venv .venv && source .venv/bin/activate
 
# Install Python bindings (meson-python & pybind11 under the hood)
pip install .

You can also build manually with Meson (generally end users will not need to do this):

meson setup build-python

meson compile -C build_gridfire

2. Why These Engines and Views?

GridFire’s design balances physical fidelity and performance. Here’s why we pick each component:

GraphEngine: Constructs the full reaction network from Reaclib rates and composition. Use this when:
- You need maximum physical accuracy (no reactions are omitted).
- You are exploring new burning pathways or validating against literature.
MultiscalePartitioningEngineView: Implements the Hix & Thielemann partitioning strategy:
- Fast reactions vs slow reactions are split onto separate kernels.
- This reduces stiffness by isolating processes on very different timescales.
- Choose when your network spans orders of magnitude in timescales (e.g., rapid proton captures vs. slow beta decays).
AdaptiveEngineView: Dynamically culls low-flow reactions at runtime:
- At each timestep, reactions with negligible contribution are temporarily removed.
- This greatly accelerates large networks without significant loss of accuracy.
- Ideal for long integrations where the active set evolves over time.
Leading-Edge Views:
- NetworkPrimingEngineView to inject seed species and study ignition phenomena.
- DefinedEngineView to freeze the network to a user-specified subset (e.g., focus on the CNO cycle).

By composing these views in sequence, you can tailor accuracy vs performance for your scientific question. Commonly one might use a flow like GraphEngine → Partitioning → Adaptive to capture both full-network physics and manageable stiffness.

3. Step-by-Step Example

Adapted from tests/python/test.py. Comments explain each choice.

import matplotlib.pyplot as plt
from gridfire.engine import GraphEngine, MultiscalePartitioningEngineView, AdaptiveEngineView
from gridfire.solver import DirectNetworkSolver
from gridfire.type import NetIn
from fourdst.composition import Composition
 
# 1. Define your composition (e.g., M-dwarf surface mix)
symbols = ["H-1","He-3","He-4","C-12","N-14","O-16","Ne-20","Mg-24"]
abundances = [0.708,2.94e-5,0.276,0.003,0.0011,9.62e-3,1.62e-3,5.16e-4]
comp = Composition()
comp.registerSymbols(symbols)
comp.setMassFraction(symbols, abundances)
comp.finalize(normalize=True)  # scale to total mass = 1
 
# 2. Prepare the NetIn object
netIn = NetIn()
netIn.composition = comp
netIn.temperature = 1.5e7   # Kelvin
netIn.density = 1.6e2       # g/cm³
netIn.tMax = 3.15e7           # seconds to evolve (~1yr)
netIn.dt0 = 1e-12           # initial timestep
 
# 3. Construct the full network engine
build_depth = 2  # shallow test network for speed; Full = -1
baseEngine = GraphEngine(comp, buildDepth=build_depth)
baseEngine.setUseReverseReactions(False) # At these temps we can turn off reverse reactions
 
# 4. Partition fast/slow reactions (reduces stiffness)
partitionedEngine = MultiscalePartitioningEngineView(baseEngine)
 
# 5. Adaptively cull negligible flows (improves speed)
adaptiveEngine = AdaptiveEngineView(partitionedEngine)
 
# 6. Choose an ODE solver (implicit Rosenbrock4)
solver = DirectNetworkSolver(adaptiveEngine, absTol=1e-12, relTol=1e-8)
 
# 7. Run the integration
 
netOut = solver.evaluate(netIn)
 
# 8. Final result:
print(f"Final H-1 fraction: {netOut.composition.getMassFraction('H-1')}")

Why these choices?

buildDepth=2: In Emily’s preliminary tests, depth=2 captures key reaction loops without the overhead of a full network.
Partition & Adaptive Views: Partitioning reduces stiffness between rapid charged-particle captures and slower β-decays; adaptive culling keeps the working set minimal.
Implicit solver: Rosenbrock4 handles stiff systems robustly, letting you push to longer tMax.

4. Visualizing Reaction Networks

GridFire engines and views provide built-in export methods for Graphviz DOT and CSV formats:

# Export the base network to DOT for Graphviz
baseEngine.exportToDot('network.dot')
# Optionally generate a PNG (shell):
#   dot -Tpng network.dot -o network.png
 
# Export a partitioned view of the network
partitionedEngine.exportToDot('partitioned.dot')
 
# Export to CSV for programmatic analysis
baseEngine.exportToCSV('network.csv')

You can then use tools like Graphviz or pandas:

# Convert DOT to PNG

dot -Tpng network.dot -o network.png

import pandas as pd
 
# Load and inspect reaction list
df = pd.read_csv('network.csv')
print(df.head())

For time-series data, record intermediates with an observer and save with pandas or numpy:

import pandas as pd
 
# Build a DataFrame of time vs species fraction
df = pd.DataFrame({'time': t, 'H-1': X_H1})
df.to_csv('H1_evolution.csv', index=False)

Then plot in pandas or Excel for custom figures.

5. Beyond the Basics

Custom Partition Functions: In Python, subclass gridfire.partition.PartitionFunction, override evaluate, supports, and clone to implement new weighting schemes.
Parameter Studies: Loop over buildDepth, solver tolerances, or initial compositions to get a sense of the sensitity of the network to input conditions or build a monte carlo grid.
Error Handling:
try:

results = solver.evaluate(netIn)

except GridFireRuntimeError as e:

print('Fatal engine error:', e)

except GridFireValueError as e:

print('Invalid input:', e)

For full API details, consult the docstrings in src/python/ and the C++ implementation in src/lib/. Enjoy exploring nuclear astrophysics with GridFire!