docs(docs): added more callback docs
This commit is contained in:
262
README.md
262
README.md
@@ -2,6 +2,16 @@
|
||||
<img src="https://github.com/4D-STAR/GridFire/blob/main/assets/logo/GridFire.png?raw=true" width="300" alt="OPAT Core Libraries Logo">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
'&style=for-the-badge&label=GitHub%20Main%20Branch)
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -49,10 +59,10 @@ By far the easiest way to install is with pip. This will install either
|
||||
pre-compiled wheels or, if your system has not had a wheel compiled for it, it
|
||||
will try to build locally (this may take **a long time**). The python bindings
|
||||
are just that and should maintain nearly the same speed as the C++ code. End
|
||||
users are strongly encorages to use the python module rather than the C++ code.
|
||||
users are strongly encourages to use the python module rather than the C++ code.
|
||||
|
||||
### pypi
|
||||
Installing from pip is as simple as
|
||||
Installing from pip is as simple as
|
||||
```bash
|
||||
pip install gridfire
|
||||
```
|
||||
@@ -60,16 +70,16 @@ pip install gridfire
|
||||
These wheels have been compiled on many systems
|
||||
|
||||
| Version | Platform | Architecture | CPython Versions | PyPy Versions |
|
||||
| ------- | -------- | ------------ | ---------------------------------------------------------- | ------------- |
|
||||
|---------|----------|--------------|------------------------------------------------------------|---------------|
|
||||
| 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 | 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.5.0 | 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 |
|
||||
|
||||
> **Note**: Currently macOS x86\_64 does **not** have a precompiled wheel. Due
|
||||
> **Note**: Currently macOS x86\_64 does **not** have a precompiled wheel. Do
|
||||
> to that platform being phased out it is likely that there will never be
|
||||
> precompiled wheels or releases for it.
|
||||
> precompiled wheels or releases for it.
|
||||
|
||||
> **Note:** macOS wheels were targeted to MacOS 12 Monterey and should work on
|
||||
> **Note:** macOS wheels were targeted to macOS 12 Monterey and should work on
|
||||
> any version more recent than that (at least as of August 2025).
|
||||
|
||||
> **Note:** Linux wheels were compiled using manylinux_2_28 and are expected to
|
||||
@@ -82,7 +92,7 @@ These wheels have been compiled on many systems
|
||||
> (https://www.boost.org/) as that is the most common broken dependency.
|
||||
|
||||
### source
|
||||
The user may also build the python bindings directly from source
|
||||
The user may also build the python bindings directly from source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/4D-STAR/GridFire
|
||||
@@ -94,7 +104,7 @@ pip install .
|
||||
> fail, the steps in further sections address these in more detail.
|
||||
|
||||
### source for developers
|
||||
If you are a developer and would like an editable and incrimental python
|
||||
If you are a developer and would like an editable and incremental python
|
||||
install `meson-python` makes this very easy
|
||||
|
||||
```bash
|
||||
@@ -103,10 +113,10 @@ cd GridFire
|
||||
pip install -e . --no-build-isolation -vv
|
||||
```
|
||||
|
||||
This will generate incrimental builds whenever source code changes and you run
|
||||
a python script automartically (note that since `meson setup` must run for each
|
||||
This will generate incremental builds whenever source code changes, and you run
|
||||
a python script automatically (note that since `meson setup` must run for each
|
||||
of these it does still take a few seconds to recompile regardless of how small
|
||||
a source code change you have made). It is **strongly** reccomended that
|
||||
a source code change you have made). It is **strongly** recommended that
|
||||
developers use this approach and end users *do not*.
|
||||
|
||||
|
||||
@@ -130,7 +140,7 @@ Generally, both are intended to be easy to use and will prompt you
|
||||
automatically to install any missing dependencies.
|
||||
|
||||
|
||||
### Currently known good platforms
|
||||
### Currently, known good platforms
|
||||
The installation script has been tested and found to work on clean
|
||||
installations of the following platforms:
|
||||
- MacOS 15.3.2 (Apple Silicon + brew installed)
|
||||
@@ -157,13 +167,13 @@ These only need to be manually installed if the user is not making use of the
|
||||
- ninja 1.10.0 or newer
|
||||
- Python packages: `meson-python>=0.15.0`
|
||||
- Boost libraries (>= 1.83.0) installed system-wide (or at least findable by
|
||||
meson with pkg-config)
|
||||
meson with pkg-config)
|
||||
|
||||
#### Optional
|
||||
- dialog (used by the `install.sh` script, not needed if using pip or meson
|
||||
directly)
|
||||
directly)
|
||||
- pip (used by the `install.sh` script or by calling pip directly, not needed
|
||||
if using meson directly)
|
||||
if using meson directly)
|
||||
|
||||
> **Note:** Boost is the only external library dependency used by GridFire directly.
|
||||
|
||||
@@ -176,20 +186,20 @@ if using meson directly)
|
||||
|
||||
### Install Scripts
|
||||
GridFire ships with an installer (`install.sh`) which is intended to make the
|
||||
process of installation both easier and more repetable.
|
||||
process of installation both easier and more repeatable.
|
||||
|
||||
#### Ease of Installation
|
||||
Both scripts are intended to automate installation more or less completly. This
|
||||
Both scripts are intended to automate installation more or less completely. This
|
||||
includes dependency checking. In the event that a dependency cannot be found
|
||||
they try to install (after explicitly asking for user permission). If that does
|
||||
not work they will provide a clear message as to what went wrong.
|
||||
not work they will provide a clear message as to what went wrong.
|
||||
|
||||
#### Reproducibility
|
||||
The TUI mode provides easy modification of meson build system and compiler
|
||||
settings which can then be saved to a config file. This config file can then be
|
||||
loaded by either tui mode or cli mode (with the `--config`) flag meaning that
|
||||
build configurations can be made and reused. Note that this is **not** a
|
||||
deterministicly reproducible build system as it does not interact with any
|
||||
deterministically reproducible build system as it does not interact with any
|
||||
system dependencies or settings, only meson and compiler settings.
|
||||
|
||||
#### Examples
|
||||
@@ -204,12 +214,12 @@ system dependencies or settings, only meson and compiler settings.
|
||||
[](https://asciinema.org/a/GYaWTXZbDJRD4ohde0s3DkFMC)
|
||||
|
||||
|
||||
> **Note:** `install-tui.sh` is simply a script which calles `install.sh` with
|
||||
> **Note:** `install-tui.sh` is simply a script which calls `install.sh` with
|
||||
> the `--tui` flag. You can get the exact same results by running `install.sh
|
||||
> --tui`.
|
||||
|
||||
> **Note:** Call `install.sh` with the `--help` or `--h` flag to see command
|
||||
> line options
|
||||
> line options
|
||||
|
||||
> **Note:** `clang` tends to compile GridFire much faster than `gcc` thus why I
|
||||
> select it in the above asciinema recording.
|
||||
@@ -224,12 +234,12 @@ sudo apt-get install -y build-essential meson python3 python3-pip libboost-all-d
|
||||
|
||||
> **Note:** Depending on the ubuntu version you have the libboost-all-dev
|
||||
> libraries may be too old. If this is the case refer to the boost
|
||||
> documentation for how to download and install a version `>=1.83.0`
|
||||
> documentation for how to download and install a version `>=1.83.0`
|
||||
|
||||
> **Note:** On recent versions of ubuntu python has switched to being
|
||||
> externally managed by the system. We **strongly** recomend that if you
|
||||
> install manaully all python pacakges are installed inside some kind of
|
||||
> virtual enviroment (e.g. `pyenv`, `conda`, `python-venv`, etc...). When using
|
||||
> externally managed by the system. We **strongly** recommend that if you
|
||||
> install manually all python packages are installed inside some kind of
|
||||
> virtual environment (e.g. `pyenv`, `conda`, `python-venv`, etc...). When using
|
||||
> the installer script this is handled automatically using `python-venv`.
|
||||
|
||||
- **Fedora/CentOS/RHEL:**
|
||||
@@ -252,7 +262,7 @@ meson compile -C build
|
||||
#### Clang vs. GCC
|
||||
As noted above `clang` tends to compile GridFire much faster than `gcc`. If
|
||||
your system has both `clang` and `gcc` installed you may force meson to use
|
||||
clang via enviromental variables
|
||||
clang via environmental variables
|
||||
|
||||
```bash
|
||||
CC=clang CXX=clang++ meson setup build_clang
|
||||
@@ -266,8 +276,8 @@ meson install -C build
|
||||
|
||||
### Minimum compiler versions
|
||||
GridFire uses C++23 features and therefore only compilers and standard library
|
||||
implimentations which support C++23 are supported. Generally we have found that
|
||||
`gcc >= 13.0.0` or `clang >= 16.0.0` work well.
|
||||
implementations which support C++23 are supported. Generally we have found that
|
||||
`gcc >= 13.0.0` or `clang >= 16.0.0` work well.
|
||||
|
||||
|
||||
## Code Architecture and Logical Flow
|
||||
@@ -277,28 +287,28 @@ a specific aspect of nuclear reaction network modeling. The core components
|
||||
include:
|
||||
|
||||
- **Engine Module:** Core interfaces and implementations (e.g., `GraphEngine`)
|
||||
that evaluate reaction network rate equations and energy generation. Also
|
||||
implimented `Views` submodule.
|
||||
that evaluate reaction network rate equations and energy generation. Also
|
||||
implemented `Views` submodule.
|
||||
- **Engine::Views Module:** Composable engine optimization and modification
|
||||
(e.g. `MultiscalePartitioningEngineView`) which can be used to make a problem
|
||||
more tractable or applicable.
|
||||
(e.g. `MultiscalePartitioningEngineView`) which can be used to make a problem
|
||||
more tractable or applicable.
|
||||
- **Screening Module:** Implements nuclear reaction screening corrections (e.g.
|
||||
`WeakScreening` ([Salpeter,
|
||||
1954](https://adsabs.harvard.edu/full/1954AuJPh...7..373S)), `BareScreening`)
|
||||
affecting reaction rates.
|
||||
`WeakScreening` ([Salpeter,
|
||||
1954](https://adsabs.harvard.edu/full/1954AuJPh...7..373S)), `BareScreening`)
|
||||
affecting reaction rates.
|
||||
- **Reaction Module:** Parses and manages Reaclib reaction rate data, providing
|
||||
temperature- and density-dependent rate evaluations.
|
||||
temperature- and density-dependent rate evaluations.
|
||||
- **Partition Module:** Implements partition functions (e.g.,
|
||||
`GroundStatePartitionFunction`, `RauscherThielemannPartitionFunction`
|
||||
([Rauscher & Thielemann,
|
||||
2000](https://www.sciencedirect.com/science/article/pii/S0092640X00908349?via%3Dihub]))
|
||||
to weight reaction rates based on nuclear properties.
|
||||
`GroundStatePartitionFunction`, `RauscherThielemannPartitionFunction`
|
||||
([Rauscher & Thielemann,
|
||||
2000](https://www.sciencedirect.com/science/article/pii/S0092640X00908349?via%3Dihub]))
|
||||
to weight reaction rates based on nuclear properties.
|
||||
- **Solver Module:** Defines numerical integration strategies (e.g.,
|
||||
`DirectNetworkSolver`) for solving the stiff ODE systems arising from reaction
|
||||
networks.
|
||||
`DirectNetworkSolver`) for solving the stiff ODE systems arising from reaction
|
||||
networks.
|
||||
- **Python Interface:** Exposes *almost* all C++ functionality to Python,
|
||||
allowing users to define compositions, configure engines, and run simulations
|
||||
directly from Python scripts.
|
||||
allowing users to define compositions, configure engines, and run simulations
|
||||
directly from Python scripts.
|
||||
|
||||
Generally a user will start by selecting a base engine (currently we only offer
|
||||
`GraphEngine`), which constructs the full reaction network graph from a given
|
||||
@@ -312,27 +322,27 @@ abundances and diagnostics.
|
||||
## Engines
|
||||
GridFire is, at its core, based on a series of `Engines`. These are constructs
|
||||
which know how to report information on series of ODEs which need to be solved
|
||||
to evolver abundnances. The important thing to understand about `Engines` is
|
||||
that they contain all of the detailed physics GridFire uses. For example a
|
||||
to evolver abundances. The important thing to understand about `Engines` is
|
||||
that they contain all the detailed physics GridFire uses. For example a
|
||||
`Solver` takes an `Engine` but does not compute physics itself. Rather, it asks
|
||||
the `Engine` for stuff like the jacobian matrix, stoichiometry, nuclear energy
|
||||
generation rate, and change in abundance with time.
|
||||
|
||||
Refer to the API documentation for the exact interface which an `Engine` must
|
||||
impliment to be compatible with GridFire solvers.
|
||||
implement to be compatible with GridFire solvers.
|
||||
|
||||
Currently we only impliment `GraphEngine` which is intended to be a very general and
|
||||
Currently, we only implement `GraphEngine` which is intended to be a very general and
|
||||
adaptable `Engine`.
|
||||
|
||||
### GraphEngine
|
||||
In GridFire the `GraphEngine` will generally be the most fundamental building
|
||||
block of a nuclear network. A `GraphEngine` represents a directional hypergraph
|
||||
connecting some set of atomic species through reactions listed in the [JINA
|
||||
Reaclib database](https://reaclib.jinaweb.org/index.php).
|
||||
Reaclib database](https://reaclib.jinaweb.org/index.php).
|
||||
|
||||
`GraphEngine`s are constructed from a seed composition of species from which
|
||||
they recursivley expand their topology outward, following known reaction
|
||||
pathways and adding new species to the tracked list as they expand.
|
||||
they recursively expand their topology outward, following known reaction
|
||||
pathways and adding new species to the tracked list as they expand.
|
||||
|
||||
|
||||
### GraphEngine Configuration Options
|
||||
@@ -341,38 +351,38 @@ GraphEngine exposes runtime configuration methods to tailor network
|
||||
construction and rate evaluations:
|
||||
|
||||
- **Constructor Parameters:**
|
||||
- `composition`: The initial seed composition to start network construction from.
|
||||
- `BuildDepthType` (`Full`, `Shallow`, `SecondOrder`, etc...): controls
|
||||
number of recursions used to construct the network topology. Can either be an
|
||||
member of the `NetworkBuildDepth` enum or an integerl.
|
||||
- `partition::PartitionFunction`: Partition function used when evlauating
|
||||
detailed balance for inverse rates.
|
||||
- `composition`: The initial seed composition to start network construction from.
|
||||
- `BuildDepthType` (`Full`, `Shallow`, `SecondOrder`, etc...): controls
|
||||
number of recursions used to construct the network topology. Can either be a
|
||||
member of the `NetworkBuildDepth` enum or an integer.
|
||||
- `partition::PartitionFunction`: Partition function used when evaluating
|
||||
detailed balance for inverse rates.
|
||||
|
||||
- **setPrecomputation(bool precompute):**
|
||||
- Enable/disable caching of reaction rates and stoichiometric data at initialization.
|
||||
- *Effect:* Reduces per-step overhead; increases memory and setup time.
|
||||
- Enable/disable caching of reaction rates and stoichiometric data at initialization.
|
||||
- *Effect:* Reduces per-step overhead; increases memory and setup time.
|
||||
|
||||
- **setScreeningModel(ScreeningType type):**
|
||||
- Choose plasma screening (models: `BARE`, `WEAK`).
|
||||
- *Effect:* Alters rate enhancement under dense/low-T conditions, impacting stiffness.
|
||||
- Choose plasma screening (models: `BARE`, `WEAK`).
|
||||
- *Effect:* Alters rate enhancement under dense/low-T conditions, impacting stiffness.
|
||||
|
||||
- **setUseReverseReactions(bool useReverse):**
|
||||
- Toggle inclusion of reverse (detailed balance) reactions.
|
||||
- *Effect:* Improves equilibrium fidelity; increases network size and stiffness.
|
||||
- Toggle inclusion of reverse (detailed balance) reactions.
|
||||
- *Effect:* Improves equilibrium fidelity; increases network size and stiffness.
|
||||
|
||||
### Available Partition Functions
|
||||
|
||||
| Function Name | Identifier / Enum | Description |
|
||||
|---------------------------------------|--------------------------|-----------------------------------------------------------------|
|
||||
| `GroundStatePartitionFunction` | "GroundState" | Weights using nuclear ground-state spin factors. |
|
||||
| `RauscherThielemannPartitionFunction` | "RauscherThielemann" | Interpolates normalized g-factors per Rauscher & Thielemann. |
|
||||
| `CompositePartitionFunction` | "Composite" | Combines multiple partition functions for situations where different partitions functions are used for different domains |
|
||||
| Function Name | Identifier / Enum | Description |
|
||||
|---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------|
|
||||
| `GroundStatePartitionFunction` | "GroundState" | Weights using nuclear ground-state spin factors. |
|
||||
| `RauscherThielemannPartitionFunction` | "RauscherThielemann" | Interpolates normalized g-factors per Rauscher & Thielemann. |
|
||||
| `CompositePartitionFunction` | "Composite" | Combines multiple partition functions for situations where different partitions functions are used for different domains |
|
||||
|
||||
### AutoDiff
|
||||
One of the primary tasks any engine must accomplish is to report the jacobian
|
||||
matrix of the system to the solver. `GraphEngine` uses `CppAD`, a C++ auto
|
||||
differentiation library, to generate analytic jacobian matricies very
|
||||
efficiently.
|
||||
differentiation library, to generate analytic jacobian matrices very
|
||||
efficiently.
|
||||
|
||||
|
||||
## Reaclib in GridFire
|
||||
@@ -380,14 +390,14 @@ All reactions in JINA Reaclib which only include reactants iron and lighter
|
||||
were downloaded on June 17th, 2025 where the most recent documented change on
|
||||
the JINA Reaclib site was on June 24th, 2021.
|
||||
|
||||
All of thes reactions have been compiled into a header file which is then
|
||||
All of these reactions have been compiled into a header file which is then
|
||||
statically compiled into the gridfire binaries (specifically into
|
||||
lib_reaction_reaclib.cpp.o). This does increase the binary size by a few MB;
|
||||
however, the benafit is faster load times and more importantly no need for end
|
||||
however, the benefit is faster load times and more importantly no need for end
|
||||
users to manage resource files.
|
||||
|
||||
If a developer wants to add new reaclib reactions we include a script at
|
||||
`utils/reaclib/format.py` which can injest a reaclib data file and produce the
|
||||
`utils/reaclib/format.py` which can ingest a reaclib data file and produce the
|
||||
needed header file. More details on this process are included in
|
||||
`utils/reaclib/readme.md`
|
||||
|
||||
@@ -398,13 +408,13 @@ The GridFire engine supports multiple engine view strategies to adapt or
|
||||
restrict network topology. Generally when extending GridFire the approach is
|
||||
likely to be one of adding new `EngineViews`.
|
||||
|
||||
| View Name | Purpose | Algorithm / Reference | When to Use |
|
||||
|---------------------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
|
||||
| AdaptiveEngineView | Dynamically culls low-flow species and reactions during runtime | Iterative flux thresholding to remove reactions below a flow threshold | Large networks to reduce computational cost |
|
||||
| DefinedEngineView | Restricts the network to a user-specified subset of species and reactions | Static network masking based on user-provided species/reaction lists | Targeted pathway studies or code-to-code comparisons |
|
||||
| FileDefinedEngineView | Load a defined engine view from a file using some parser | Same as DefinedEngineView but loads from a file | Same as DefinedEngineView
|
||||
| MultiscalePartitioningEngineView | Partitions the network into fast and slow subsets based on reaction timescales | Network partitioning following Hix & Thielemann Silicon Burning I & II (DOI:10.1086/177016,10.1086/306692)| Stiff, multi-scale networks requiring tailored integration |
|
||||
| NetworkPrimingEngineView | Primes the network with an initial species or set of species for ignition studies| Single-species ignition and network priming | Investigations of ignition triggers or initial seed sensitivities|
|
||||
| View Name | Purpose | Algorithm / Reference | When to Use |
|
||||
|----------------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
|
||||
| AdaptiveEngineView | Dynamically culls low-flow species and reactions during runtime | Iterative flux thresholding to remove reactions below a flow threshold | Large networks to reduce computational cost |
|
||||
| DefinedEngineView | Restricts the network to a user-specified subset of species and reactions | Static network masking based on user-provided species/reaction lists | Targeted pathway studies or code-to-code comparisons |
|
||||
| FileDefinedEngineView | Load a defined engine view from a file using some parser | Same as DefinedEngineView but loads from a file | Same as DefinedEngineView |
|
||||
| MultiscalePartitioningEngineView | Partitions the network into fast and slow subsets based on reaction timescales | Network partitioning following Hix & Thielemann Silicon Burning I & II (DOI:10.1086/177016,10.1086/306692) | Stiff, multi-scale networks requiring tailored integration |
|
||||
| NetworkPrimingEngineView | Primes the network with an initial species or set of species for ignition studies | Single-species ignition and network priming | Investigations of ignition triggers or initial seed sensitivities |
|
||||
|
||||
These engine views implement the common Engine interface and may be composed in
|
||||
any order to build complex network pipelines. New view types can be added by
|
||||
@@ -413,11 +423,11 @@ chain without modifying core engine code.
|
||||
|
||||
### A Note about composability
|
||||
There are certain functions for which it is expected that a call to an engine
|
||||
view will propegate the result down the chain of engine views, eventually
|
||||
view will propagate the result down the chain of engine views, eventually
|
||||
reaching the base engine (e.g. `DynamicEngine::update`). We do not strongly
|
||||
enforce this as it is not hard to contrive a situation where that is not the
|
||||
mose useful behavior; however, we do strongly encorage developers to think
|
||||
carefully about passing along calls to base engine methods when implimenting
|
||||
mose useful behavior; however, we do strongly encourage developers to think
|
||||
carefully about passing along calls to base engine methods when implementing
|
||||
new views.
|
||||
|
||||
## Numerical Solver Strategies
|
||||
@@ -428,7 +438,7 @@ integration algorithms to be used interchangeably with any engine that
|
||||
implements the `Engine` or `DynamicEngine` contract.
|
||||
|
||||
### NetworkSolverStrategy<EngineT>:
|
||||
All GridFire solvers impliment the abstract strategy templated by
|
||||
All GridFire solvers implement the abstract strategy templated by
|
||||
`NetworkSolverStrategy` which enforces only that there is some `evaluate`
|
||||
method with the following signature
|
||||
|
||||
@@ -440,7 +450,7 @@ abundances, temperature, density, and diagnostics.
|
||||
|
||||
### NetIn and NetOut
|
||||
GridFire solvers use a unified input and output type for their public interface
|
||||
(though as developers will quickly learn, internally these are immediatly
|
||||
(though as developers will quickly learn, internally these are immediately
|
||||
broken down into simpler data structures). All solvers expect a `NetIn` struct
|
||||
for the input type to the `evaluate` method and return a `NetOut` struct.
|
||||
|
||||
@@ -454,11 +464,11 @@ A `NetIn` struct contains
|
||||
- The initial energy in the system in ergs (`NetIn::energy`)
|
||||
|
||||
>**Note:** It is often useful to set `NetIn::dt0` to something *very* small and
|
||||
>let an iterative timestepper push the timestep up. Often for main sequence
|
||||
>let an iterative time stepper push the timestep up. Often for main sequence
|
||||
>burning I use ~1e-12 for dt0
|
||||
|
||||
>**Note:** The composition must be a `fourdst::composition::Composition`
|
||||
>object. This is made avalible through the `foursdt` library and the
|
||||
>object. This is made available through the `foursdt` library and the
|
||||
>`fourdst/composition/Composition.h` header. `fourdst` is installed
|
||||
>automatically with GridFire
|
||||
|
||||
@@ -471,7 +481,7 @@ A `NetOut` struct contains
|
||||
- The final composition after evolving to `tMax` (`NetOut::composition`)
|
||||
- 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`
|
||||
(`NetOut::energy`)
|
||||
(`NetOut::energy`)
|
||||
|
||||
>**Note:** Currently `GraphEngine` only considers energy due to nuclear mass
|
||||
>defect and not neutrino loss.
|
||||
@@ -480,18 +490,18 @@ A `NetOut` struct contains
|
||||
### DirectNetworkSolver (Implicit Rosenbrock Method)
|
||||
|
||||
- **Integrator:** Implicit Rosenbrock4 scheme (order 4) via `Boost.Odeint`’s
|
||||
`rosenbrock4<double>`, optimized for stiff reaction networks with adaptive step
|
||||
size control using configurable absolute and relative tolerances.
|
||||
`rosenbrock4<double>`, optimized for stiff reaction networks with adaptive step
|
||||
size control using configurable absolute and relative tolerances.
|
||||
- **Jacobian Assembly:** Asks the base engine for the Jacobian Matrix
|
||||
- **RHS Evaluation:** Assk the base engine for RHS of the abundance evolution
|
||||
equations
|
||||
- **RHS Evaluation:** Asks the base engine for RHS of the abundance evolution
|
||||
equations
|
||||
- **Linear Algebra:** Utilizes `Boost.uBLAS` for state vectors and dense Jacobian
|
||||
matrices, with sparse access patterns supported via coordinate lists of nonzero
|
||||
entries.
|
||||
matrices, with sparse access patterns supported via coordinate lists of nonzero
|
||||
entries.
|
||||
- **Error Control and Logging:** Absolute and relative tolerance parameters
|
||||
(`absTol`, `relTol`) are read from configuration; Quill loggers, which run in a
|
||||
seperate non blocking thread, capture integration diagnostics and step
|
||||
statistics.
|
||||
(`absTol`, `relTol`) are read from configuration; Quill loggers, which run in a
|
||||
separate non blocking thread, capture integration diagnostics and step
|
||||
statistics.
|
||||
|
||||
### Algorithmic Workflow in DirectNetworkSolver
|
||||
1. **Initialization:** Convert input temperature to T9 units, retrieve
|
||||
@@ -499,21 +509,21 @@ statistics.
|
||||
2. **Integrator Setup:** Construct the controlled Rosenbrock4 stepper and bind
|
||||
`RHSManager` and `JacobianFunctor`.
|
||||
3. **Adaptive Integration Loop:**
|
||||
- Perform `integrate_adaptive` advancing until `tMax`, catching any
|
||||
`StaleEngineTrigger` to repartition the network and update composition.
|
||||
- On each substep, observe states and log via `RHSManager::observe`.
|
||||
- Perform `integrate_adaptive` advancing until `tMax`, catching any
|
||||
`StaleEngineTrigger` to repartition the network and update composition.
|
||||
- On each substep, observe states and log via `RHSManager::observe`.
|
||||
4. **Finalization:** Assemble final mass fractions, compute accumulated energy,
|
||||
and populate `NetOut` with updated composition and diagnostics.
|
||||
|
||||
### Future Solver Implementations
|
||||
- **Operator Splitting Solvers:** Strategies to decouple thermodynamics,
|
||||
screening, and reaction substeps for performance on stiff, multi-scale
|
||||
networks.
|
||||
screening, and reaction substeps for performance on stiff, multiscale
|
||||
networks.
|
||||
- **GPU-Accelerated Solvers:** Planned use of CUDA/OpenCL backends for
|
||||
large-scale network integration.
|
||||
large-scale network integration.
|
||||
- **Callback observer support:** Currently we use an observer built into our
|
||||
`RHSManager` (`RHSManager::observe`); however, we intend to inlucde support for
|
||||
custom, user defined, observer method.
|
||||
`RHSManager` (`RHSManager::observe`); however, we intend to include support for
|
||||
custom, user defined, observer method.
|
||||
|
||||
These strategies can be developed by inheriting from `NetworkSolverStrategy`
|
||||
and registering against the same engine types without modifying existing engine
|
||||
@@ -629,22 +639,22 @@ int main(){
|
||||
|
||||
#### Workflow Components and Effects
|
||||
- **GraphEngine** constructs the full reaction network, capturing all species
|
||||
and reactions.
|
||||
and reactions.
|
||||
- **MultiscalePartitioningEngineView** segregates reactions by characteristic
|
||||
timescales (Hix & Thielemann), reducing the effective stiffness by treating
|
||||
fast processes separately.
|
||||
timescales (Hix & Thielemann), reducing the effective stiffness by treating
|
||||
fast processes separately.
|
||||
- **AdaptiveEngineView** prunes low-flux species/reactions at runtime,
|
||||
decreasing dimensionality and improving computational efficiency.
|
||||
decreasing dimensionality and improving computational efficiency.
|
||||
- **DirectNetworkSolver** employs an implicit Rosenbrock method to stably
|
||||
integrate the remaining stiff system with adaptive step control.
|
||||
integrate the remaining stiff system with adaptive step control.
|
||||
|
||||
This layered approach enhances stability for stiff networks while maintaining
|
||||
accuracy and performance.
|
||||
|
||||
### Callback Example
|
||||
Custom callback functions can be registered with any solver. Because it might make sense for each solver to provide
|
||||
different context to the callback function, you should use the struct `gridfire::solver::<SolverName>::TimestepContext`
|
||||
as the argument type for the callback function. This struct contains all of the information provided by that solver to
|
||||
different context to the callback function, you should use the struct `gridfire::solver::<SolverName>::TimestepContext`
|
||||
as the argument type for the callback function. This struct contains all the information provided by that solver to
|
||||
the callback function.
|
||||
|
||||
```c++
|
||||
@@ -704,20 +714,32 @@ int main(){
|
||||
|
||||
>**Note:** A fully detailed list of all available information in the TimestepContext struct is available in the API documentation.
|
||||
|
||||
>**Note:** The order of species in the boost state vector (`ctx.state`) is **not guaranteed** to be any particular order run over run. Therefore, in order to reliably extract
|
||||
>**Note:** The order of species in the boost state vector (`ctx.state`) is **not guaranteed** to be any particular order run over run. Therefore, in order to reliably extract
|
||||
> values from it, you **must** use the `getSpeciesIndex` method of the engine to get the index of the species you are interested in (these will always be in the same order).
|
||||
|
||||
#### Callback Context
|
||||
|
||||
Since each solver may provide different context to the callback function, and it may be frustrating to refer to the
|
||||
documentation every time, we also enforce that all solvers must implement a `descripe_callback_context` method which
|
||||
returns a vector of tuples<string, string> where the first element is the name of the field and the second is its
|
||||
datatype. It is on the developer to ensure that this information is accurate.
|
||||
|
||||
```c++
|
||||
...
|
||||
std::cout << solver.describe_callback_context() << std::endl;
|
||||
```
|
||||
|
||||
## 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
|
||||
with imports of modules such that
|
||||
|
||||
`#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
|
||||
### Common Workflow Example
|
||||
This example implements the same logic as the above C++ example
|
||||
```python
|
||||
from gridfire.engine import GraphEngine, MultiscalePartitioningEngineView, AdaptiveEngineView
|
||||
from gridfire.solver import DirectNetworkSolver
|
||||
@@ -820,11 +842,11 @@ print(f"Final H-1 mass fraction {results.composition.getMassFraction("H-1")}")
|
||||
GridFire integrates with and builds upon several key 4D-STAR libraries:
|
||||
|
||||
- [fourdst](https://github.com/4D-STAR/fourdst): hub module managing versioning
|
||||
of `libcomposition`, `libconfig`, `liblogging`, and `libconstants`
|
||||
of `libcomposition`, `libconfig`, `liblogging`, and `libconstants`
|
||||
- [libcomposition](https://github.com/4D-STAR/libcomposition)
|
||||
([docs](https://4d-star.github.io/libcomposition/)): Composition management
|
||||
toolkit.
|
||||
([docs](https://4d-star.github.io/libcomposition/)): Composition management
|
||||
toolkit.
|
||||
- [libconfig](https://github.com/4D-STAR/libconfig): Configuration file parsing
|
||||
utilities.
|
||||
utilities.
|
||||
- [liblogging](https://github.com/4D-STAR/liblogging): Flexible logging framework.
|
||||
- [libconstants](https://github.com/4D-STAR/libconstants): Physical constants
|
||||
|
||||
Reference in New Issue
Block a user