Loading...
Searching...
No Matches
GridFire Python Usage Guide

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:

1. 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.
2. 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).
3. 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.
4. 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')}")
gridfire::engine
Definition dynamic_engine_diagnostics.h:39
gridfire::solver
Definition GridSolver.h:7

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!