docs(readme): Updated
Updated readme and docs to reflect new output (neutrino)
This commit is contained in:
106
README.md
106
README.md
@@ -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.
|
||||||
@@ -434,25 +387,25 @@ GraphEngine exposes runtime configuration methods to tailor network
|
|||||||
construction and rate evaluations:
|
construction and rate evaluations:
|
||||||
|
|
||||||
- **Constructor Parameters:**
|
- **Constructor Parameters:**
|
||||||
- `composition`: The initial seed composition to start network construction from.
|
- `composition`: The initial seed composition to start network construction from.
|
||||||
- `BuildDepthType` (`Full`, `Shallow`, `SecondOrder`, etc...): controls
|
- `BuildDepthType` (`Full`, `Shallow`, `SecondOrder`, etc...): controls
|
||||||
number of recursions used to construct the network topology. Can either be a
|
number of recursions used to construct the network topology. Can either be a
|
||||||
member of the `NetworkBuildDepth` enum or an integer.
|
member of the `NetworkBuildDepth` enum or an integer.
|
||||||
- `partition::PartitionFunction`: Partition function used when evaluating
|
- `partition::PartitionFunction`: Partition function used when evaluating
|
||||||
detailed balance for inverse rates.
|
detailed balance for inverse rates.
|
||||||
- `NetworkConstructionFlags`: A bitwise flag telling the network how to construct itself. That is, what reaction types should be used in construction. For example one might use `NetworkConstructionFlags::STRONG | NetworkConstructionFlags::BETA_PLUS` to use all strong reactions and β+ decay. By Default this is set to use reaclib strong and reaclib weak (no WRL included by default due to current pathological stiffness issues).
|
- `NetworkConstructionFlags`: A bitwise flag telling the network how to construct itself. That is, what reaction types should be used in construction. For example one might use `NetworkConstructionFlags::STRONG | NetworkConstructionFlags::BETA_PLUS` to use all strong reactions and β+ decay. By Default this is set to use reaclib strong and reaclib weak (no WRL included by default due to current pathological stiffness issues).
|
||||||
|
|
||||||
- **setPrecomputation(bool precompute):**
|
- **setPrecomputation(bool precompute):**
|
||||||
- Enable/disable caching of reaction rates and stoichiometric data at initialization.
|
- Enable/disable caching of reaction rates and stoichiometric data at initialization.
|
||||||
- *Effect:* Reduces per-step overhead; increases memory and setup time.
|
- *Effect:* Reduces per-step overhead; increases memory and setup time.
|
||||||
|
|
||||||
- **setScreeningModel(ScreeningType type):**
|
- **setScreeningModel(ScreeningType type):**
|
||||||
- Choose plasma screening (models: `BARE`, `WEAK`).
|
- Choose plasma screening (models: `BARE`, `WEAK`).
|
||||||
- *Effect:* Alters rate enhancement under dense/low-T conditions, impacting stiffness.
|
- *Effect:* Alters rate enhancement under dense/low-T conditions, impacting stiffness.
|
||||||
|
|
||||||
- **setUseReverseReactions(bool useReverse):**
|
- **setUseReverseReactions(bool useReverse):**
|
||||||
- Toggle inclusion of reverse (detailed balance) reactions.
|
- Toggle inclusion of reverse (detailed balance) reactions.
|
||||||
- *Effect:* Improves equilibrium fidelity; increases network size and stiffness.
|
- *Effect:* Improves equilibrium fidelity; increases network size and stiffness.
|
||||||
|
|
||||||
### Available Partition Functions
|
### Available Partition Functions
|
||||||
|
|
||||||
@@ -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,9 +746,9 @@ 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
|
||||||
from gridfire.type import NetIn
|
from gridfire.type import NetIn
|
||||||
@@ -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
68
docs/static/mainpage.md
vendored
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user