165 lines
6.3 KiB
Markdown
165 lines
6.3 KiB
Markdown
# 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:
|
||
```bash
|
||
pip install gridfire
|
||
```
|
||
|
||
### 1.2 Development from Source
|
||
If you want the cutting-edge features or need to hack the C++ backend:
|
||
```bash
|
||
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):
|
||
```bash
|
||
meson setup build-python
|
||
meson compile -C build_gridfire
|
||
```
|
||
|
||
---
|
||
## 2. Why These Engines and Views?
|
||
GridFire’s design [balances physical fidelity and performance](../README.md). 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`](../../tests/python/test.py). Comments explain each choice.
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
# 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:
|
||
```bash
|
||
# Convert DOT to PNG
|
||
dot -Tpng network.dot -o network.png
|
||
```
|
||
```python
|
||
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:
|
||
```python
|
||
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**:
|
||
```python
|
||
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!
|