tboudreaux/GridFire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): Updated

Browse Source 
Updated readme and docs to reflect new output (neutrino)
This commit is contained in:
Emily Boudreaux
2025-11-27 15:06:02 -05:00
parent 39a689ee5d
commit 30a5a4d803
2 changed files with 52 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@@ -15,53 +15,6 @@
--- ---
# Table of Contents
- [Introduction](#introduction)
- [Design Philosophy and Workflow](#design-philosophy-and-workflow)
- [Funding](#funding)
- [Usage](#usage)
- [Python installation](#python-installation)
- [pypi](#pypi)
- [source](#source)
- [source for developers](#source-for-developers)
- [patching shared object files](#patching-shared-object-files)
- [Automatic Build and Installation](#automatic-build-and-installation)
- [Script Build and Installation Instructions](#script-build-and-installation-instructions)
- [Currently, known good platforms](#currently-known-good-platforms)
- [Manual Build Instructions](#manual-build-instructions)
- [Prerequisites](#prerequisites)
- [Install Scripts](#install-scripts)
- [Dependency Installation on Common Platforms](#dependency-installation-on-common-platforms)
- [Building the C++ Library](#building-the-c-library)
- [Installing the Library](#installing-the-library)
- [Minimum compiler versions](#minimum-compiler-versions)
- [Code Architecture and Logical Flow](#code-architecture-and-logical-flow)
- [Engines](#engines)
- [GraphEngine](#graphengine)
- [GraphEngine Configuration Options](#graphengine-configuration-options)
- [Available Partition Functions](#available-partition-functions)
- [AutoDiff](#autodiff)
- [Reaclib in GridFire](#reaclib-in-gridfire)
- [Engine Views](#engine-views)
- [A Note about composability](#a-note-about-composability)
- [Numerical Solver Strategies](#numerical-solver-strategies)
- [NetworkSolverStrategy<EngineT>](#networksolverstrategyenginet)
- [NetIn and NetOut](#netin-and-netout)
- [DirectNetworkSolver (Implicit Rosenbrock Method)](#directnetworksolver-implicit-rosenbrock-method)
- [Algorithmic Workflow in DirectNetworkSolver](#algorithmic-workflow-in-directnetworksolver)
- [Future Solver Implementations](#future-solver-implementations)
- [Python Extensibility](#python-extensibility)
- [Usage Examples](#usage-examples)
- [C++](#c)
- [GraphEngine Initialization](#graphengine-initialization)
- [Adaptive Network View](#adaptive-network-view)
- [Composition Initialization](#composition-initialization)
- [Common Workflow Example](#common-workflow-example)
- [Callback Example](#callback-example)
- [Python](#python)
- [Common Workflow Example](#common-workflow-example-1)
- [Python callbacks](#python-callbacks)
- [Related Projects](#related-projects)
# Introduction # Introduction
GridFire is a C++ library designed to perform general nuclear network GridFire is a C++ library designed to perform general nuclear network
@@ -119,7 +72,7 @@ These wheels have been compiled on many systems
| Version | Platform | Architecture | CPython Versions | PyPy Versions | | Version | Platform | Architecture | CPython Versions | PyPy Versions |
|-----------|----------|--------------|------------------------------------------------------------|---------------| |-----------|----------|--------------|------------------------------------------------------------|---------------|
| 0.7.0_rc1 | macOS | arm64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 | | 0.7.0_rc1 | macOS | arm64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 |
| 0.7.0_rc1 | Linux | aarch64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 | | 0.7.0_rc1 | Linux | aarch64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 |
| 0.7.0_rc1 | Linux | x86\_64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 | | 0.7.0_rc1 | Linux | x86\_64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 |
| 0.5.0 | macOS | arm64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 | | 0.5.0 | macOS | arm64 | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (std & t), 3.14 (std & t) | 3.10, 3.11 |
@@ -387,8 +340,8 @@ include:
- **io Module:** Defines shared interface for parsing network data from files - **io Module:** Defines shared interface for parsing network data from files
- **trigger Module:** Defines interface for complex trigger logic so that repartitioning can be followed. - **trigger Module:** Defines interface for complex trigger logic so that repartitioning can be followed.
- **Policy Module:** Contains "policies" which are small modular units of code that enforce certain contracts. - **Policy Module:** Contains "policies" which are small modular units of code that enforce certain contracts.
For example the `ProtonProtonReactionChainPolicy` enforces than an engine must include at least all the reactions For example the `ProtonProtonReactionChainPolicy` enforces than an engine must include at least all the reactions
in the proton-proton chain. This module exposes the primary construction interface for users. I.e. select a policy (such as `MainSequencePolicy`), provide a composition, and get back an engine which satisfies that policy. in the proton-proton chain. This module exposes the primary construction interface for users. I.e. select a policy (such as `MainSequencePolicy`), provide a composition, and get back an engine which satisfies that policy.
- **Python Interface:** Exposes *almost* all C++ functionality to Python, - **Python Interface:** Exposes *almost* all C++ functionality to Python,
allowing users to define compositions, configure engines, and run simulations allowing users to define compositions, configure engines, and run simulations
directly from Python scripts. directly from Python scripts.
@@ -564,11 +517,11 @@ A `NetIn` struct contains
A `NetOut` struct contains A `NetOut` struct contains
- The final composition after evolving to `tMax` (`NetOut::composition`) - The final composition after evolving to `tMax` (`NetOut::composition`)
- The number of steps the solver took to evolve to `tmax` (`NetOut::num_steps`) - The number of steps the solver took to evolve to `tmax` (`NetOut::num_steps`)
- The final energy generated by the network while evolving to `tMax` - The final specific energy generated by the network while evolving to `tMax` (`NetOut::energy`) [erg/g]
(`NetOut::energy`) - The derivative of energy with respect to temperature at the end of the evolution (`NetOut::dEps_dT`)
- The derivative of energy with respect to density at the end of the evolution (`NetOut::dEps_dRho`)
>**Note:** Currently `GraphEngine` only considers energy due to nuclear mass - The total specific energy lost to neutrinos while evolving to `tMax` (`NetOut::total_neutrino_loss`) [erg/g]
>defect and not neutrino loss. - The total flux of neutrinos while evolving to `tMax` (`NetOut::total_neutrino_flux`)
### CVODESolverStrategy ### CVODESolverStrategy
@@ -793,8 +746,8 @@ All GridFire C++ types have been bound and can be passed around as one would exp
The syntax for registration is very similar to C++. There are a few things to note about this more robust example The syntax for registration is very similar to C++. There are a few things to note about this more robust example
1. Note how I use a callback and a log object to store the state of the simulation at each timestep. 1. Note how I use a callback and a log object to store the state of the simulation at each timestep.
2. If you have tools such as mypy installed you will see that the python bindings are strongly typed. This is 2. If you have tools such as mypy installed you will see that the python bindings are strongly typed. This is
intentional to help users avoid mistakes when writing code. intentional to help users avoid mistakes when writing code.
```python ```python
from fourdst.composition import Composition from fourdst.composition import Composition
@@ -962,6 +915,8 @@ int main() {
double energy_out; double energy_out;
double dEps_dT; double dEps_dT;
double dEps_dRho; double dEps_dRho;
double neutrino_energy_loss;
double neutrino_flux;
double mass_lost; double mass_lost;
ret = gf_evolve( ret = gf_evolve(
@@ -975,7 +930,10 @@ int main() {
Y_out, Y_out,
&energy_out, &energy_out,
&dEps_dT, &dEps_dT,
&dEps_dRho, &mass_lost &dEps_dRho,
&neutrino_energy_loss,
&neutrino_flux,
&mass_lost
); );
GF_CHECK_RET_CODE(ret, gf_context, "Evolution"); GF_CHECK_RET_CODE(ret, gf_context, "Evolution");
@@ -1058,7 +1016,7 @@ program main
! Output buffers ! Output buffers
real(c_double), dimension(8) :: Y_out real(c_double), dimension(8) :: Y_out
real(c_double) :: energy_out, dedt, dedrho, dmass real(c_double) :: energy_out, dedt, dedrho, nu_E_loss, nu_flux, dmass
! Thermodynamic Conditions (Solar Core-ish) ! Thermodynamic Conditions (Solar Core-ish)
real(c_double) :: T = 1.5e7 ! 15 Million K real(c_double) :: T = 1.5e7 ! 15 Million K
@@ -1082,7 +1040,7 @@ program main
! --- 5. Evolve --- ! --- 5. Evolve ---
print *, "Evolving system (dt =", dt, "s)..." print *, "Evolving system (dt =", dt, "s)..."
call net%evolve(Y_in, T, rho, dt, Y_out, energy_out, dedt, dedrho, dmass, ierr) call net%evolve(Y_in, T, rho, dt, Y_out, energy_out, dedt, dedrho, nu_E_loss, nu_flux, dmass, ierr)
if (ierr /= 0) then if (ierr /= 0) then
print *, "Evolution Failed with error code: ", ierr print *, "Evolution Failed with error code: ", ierr

68
docs/static/mainpage.md vendored
View File

@@ -15,53 +15,6 @@
--- ---
# Table of Contents
- [Introduction](#introduction)
- [Design Philosophy and Workflow](#design-philosophy-and-workflow)
- [Funding](#funding)
- [Usage](#usage)
- [Python installation](#python-installation)
- [pypi](#pypi)
- [source](#source)
- [source for developers](#source-for-developers)
- [patching shared object files](#patching-shared-object-files)
- [Automatic Build and Installation](#automatic-build-and-installation)
- [Script Build and Installation Instructions](#script-build-and-installation-instructions)
- [Currently, known good platforms](#currently-known-good-platforms)
- [Manual Build Instructions](#manual-build-instructions)
- [Prerequisites](#prerequisites)
- [Install Scripts](#install-scripts)
- [Dependency Installation on Common Platforms](#dependency-installation-on-common-platforms)
- [Building the C++ Library](#building-the-c-library)
- [Installing the Library](#installing-the-library)
- [Minimum compiler versions](#minimum-compiler-versions)
- [Code Architecture and Logical Flow](#code-architecture-and-logical-flow)
- [Engines](#engines)
- [GraphEngine](#graphengine)
- [GraphEngine Configuration Options](#graphengine-configuration-options)
- [Available Partition Functions](#available-partition-functions)
- [AutoDiff](#autodiff)
- [Reaclib in GridFire](#reaclib-in-gridfire)
- [Engine Views](#engine-views)
- [A Note about composability](#a-note-about-composability)
- [Numerical Solver Strategies](#numerical-solver-strategies)
- [NetworkSolverStrategy<EngineT>](#networksolverstrategyenginet)
- [NetIn and NetOut](#netin-and-netout)
- [DirectNetworkSolver (Implicit Rosenbrock Method)](#directnetworksolver-implicit-rosenbrock-method)
- [Algorithmic Workflow in DirectNetworkSolver](#algorithmic-workflow-in-directnetworksolver)
- [Future Solver Implementations](#future-solver-implementations)
- [Python Extensibility](#python-extensibility)
- [Usage Examples](#usage-examples)
- [C++](#c)
- [GraphEngine Initialization](#graphengine-initialization)
- [Adaptive Network View](#adaptive-network-view)
- [Composition Initialization](#composition-initialization)
- [Common Workflow Example](#common-workflow-example)
- [Callback Example](#callback-example)
- [Python](#python)
- [Common Workflow Example](#common-workflow-example-1)
- [Python callbacks](#python-callbacks)
- [Related Projects](#related-projects)
# Introduction # Introduction
GridFire is a C++ library designed to perform general nuclear network GridFire is a C++ library designed to perform general nuclear network
@@ -564,11 +517,11 @@ A `NetIn` struct contains
A `NetOut` struct contains A `NetOut` struct contains
- The final composition after evolving to `tMax` (`NetOut::composition`) - The final composition after evolving to `tMax` (`NetOut::composition`)
- The number of steps the solver took to evolve to `tmax` (`NetOut::num_steps`) - The number of steps the solver took to evolve to `tmax` (`NetOut::num_steps`)
- The final energy generated by the network while evolving to `tMax` - The final specific energy generated by the network while evolving to `tMax` (`NetOut::energy`) [erg/g]
(`NetOut::energy`) - The derivative of energy with respect to temperature at the end of the evolution (`NetOut::dEps_dT`)
- The derivative of energy with respect to density at the end of the evolution (`NetOut::dEps_dRho`)
>**Note:** Currently `GraphEngine` only considers energy due to nuclear mass - The total specific energy lost to neutrinos while evolving to `tMax` (`NetOut::total_neutrino_loss`) [erg/g]
>defect and not neutrino loss. - The total flux of neutrinos while evolving to `tMax` (`NetOut::total_neutrino_flux`)
### CVODESolverStrategy ### CVODESolverStrategy
@@ -962,6 +915,8 @@ int main() {
double energy_out; double energy_out;
double dEps_dT; double dEps_dT;
double dEps_dRho; double dEps_dRho;
double neutrino_energy_loss;
double neutrino_flux;
double mass_lost; double mass_lost;
ret = gf_evolve( ret = gf_evolve(
@@ -975,7 +930,10 @@ int main() {
Y_out, Y_out,
&energy_out, &energy_out,
&dEps_dT, &dEps_dT,
&dEps_dRho, &mass_lost &dEps_dRho,
&neutrino_energy_loss,
&neutrino_flux,
&mass_lost
); );
GF_CHECK_RET_CODE(ret, gf_context, "Evolution"); GF_CHECK_RET_CODE(ret, gf_context, "Evolution");
@@ -1058,7 +1016,7 @@ program main
! Output buffers ! Output buffers
real(c_double), dimension(8) :: Y_out real(c_double), dimension(8) :: Y_out
real(c_double) :: energy_out, dedt, dedrho, dmass real(c_double) :: energy_out, dedt, dedrho, nu_E_loss, nu_flux, dmass
! Thermodynamic Conditions (Solar Core-ish) ! Thermodynamic Conditions (Solar Core-ish)
real(c_double) :: T = 1.5e7 ! 15 Million K real(c_double) :: T = 1.5e7 ! 15 Million K
@@ -1082,7 +1040,7 @@ program main
! --- 5. Evolve --- ! --- 5. Evolve ---
print *, "Evolving system (dt =", dt, "s)..." print *, "Evolving system (dt =", dt, "s)..."
call net%evolve(Y_in, T, rho, dt, Y_out, energy_out, dedt, dedrho, dmass, ierr) call net%evolve(Y_in, T, rho, dt, Y_out, energy_out, dedt, dedrho, nu_E_loss, nu_flux, dmass, ierr)
if (ierr /= 0) then if (ierr /= 0) then
print *, "Evolution Failed with error code: ", ierr print *, "Evolution Failed with error code: ", ierr