From 7373ca2f9acc37313a53660652a4e9ff0f34877c Mon Sep 17 00:00:00 2001 From: Emily Boudreaux Date: Thu, 31 Jul 2025 11:10:02 -0400 Subject: [PATCH] docs(docs): updated index.html and readme --- README.md | 2 +- docs/html/index.html | 86 ++++++++++++++++++--------------------- docs/index.html | 89 +++++++++++++++++++++++++++++------------ docs/static/mainpage.md | 2 +- 4 files changed, 104 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 2c146eaf..f0d23338 100644 --- a/README.md +++ b/README.md @@ -637,7 +637,7 @@ 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` becomes `import gridfire.engine.GraphEngine` +`#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. diff --git a/docs/html/index.html b/docs/html/index.html index d128a47d..776f6334 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -529,54 +529,44 @@ Workflow Components and Effects

Python

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.

+

+Common Workflow Examople

+

This example impliments the same logic as the above C++ example

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)
+

+Related Projects

+

GridFire integrates with and builds upon several key 4D-STAR libraries:

+ diff --git a/docs/index.html b/docs/index.html index b3b094de..e4a4cabe 100644 --- a/docs/index.html +++ b/docs/index.html @@ -84,7 +84,7 @@ @@ -111,7 +111,7 @@ Home - Docs + About GitHub @@ -123,36 +123,75 @@

GridFire

-

A General Purpose Nuclear Network

-

A 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.

+

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 + View on GitHub
-

Usage

-

Introduction

-

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.

-

Core Concepts

-

GridFire separates the network into four main parts.

-
    -
  • Species: These represent individual isotopes, tracking things such as their mass, beta decay energy, quantum numbers, and half-life.
    • -
  • Reactions: These represent reactions. All reactions from REACLIB, which include only reactant species up to and including iron, are included. Each reaction can evaluate the reaction rate based on the REACLIB formula.
    • -
  • Engines: Engines encode the underlying physical network. These can be either simplified networks (like `approx8Engine`) or more robust but slower networks (like `GraphEngine`). Engines are not directly evaluated; rather, solvers use engines to find abundances and energies.
    • -
  • Solvers: Solvers take an engine and know how to integrate it through time. This can either be a simple evaluation of the network topology or it can include more complex approximations such as QSE.
    • +

    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.
    -

    Python Example

    - 
    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")
@@ -169,9 +208,9 @@ results = solver.evaluate(inputParams) diff --git a/docs/static/mainpage.md b/docs/static/mainpage.md index 9dd28db2..e0eb1716 100644 --- a/docs/static/mainpage.md +++ b/docs/static/mainpage.md @@ -633,7 +633,7 @@ 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` becomes `import gridfire.engine.GraphEngine` +`#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.