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

docs(readme): updated readme

Browse Source 
added section on policy module
This commit is contained in:
Emily Boudreaux
2025-11-25 14:18:23 -05:00
parent b8835aee7f
commit 9bdf63e2cb
1 changed files with 17 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@@ -63,16 +63,6 @@
- [Python callbacks](#python-callbacks)
- [Related Projects](#related-projects)
# Version and Notes
This repository is currently tracking GridFire version v0.7.0-alpha. Note that this
is a development version which has known scientific and build issues:
1. Over long runs (say 10Gyr) repartitioning stages can introduce discontinuities into abundances
2. We do not currently produce He-4 at a rate consistent with literature values. This is a known issue and is being addressed.
3. When using Weak Rate Library (WRL) weak reactions the network becomes pathologically stiff. Reaclib includes a limited set of reactions which can be used to close the CNO cycle. Network construction then defaults to using all reaclib reactions while we address pathological stiffness with WRL rates.
4. WRL reactions do track energy loss due to neutrinos and neutrino flux; however, these are not currently reported to the user. They will be in the final v0.7.0 release.
5. There is a current bug in meson-python which results in multiple duplicate LC_RPATH entries in any shared object files compiled for python linking. Recent versions of the macos dynamic loader (XCode command line tools versions >= 16) refuse to load shared object files with duplicat rpath entries. Because of this running `pip install`. in the root will result in a broken gridfire python install. Instead we have bundled a helper script `pip_install_mac_patch.sh` which should be used to install python bindings on macos for the time being.
# Introduction
GridFire is a C++ library designed to perform general nuclear network
evolution. It is part of the larger SERiF project within the 4D-STAR
@@ -120,19 +110,21 @@ are just that and should maintain nearly the same speed as the C++ code. End
users are strongly encouraged to use the python module rather than the C++ code.
### pypi
Installing from pip is as simple as. Note that this will install gridfire v0.5.0, currently the latest version on pip. Once
v0.7.0 is released this will be pushed to pip.
Installing from pip is as simple as.
```bash
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 |
| 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 | 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.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
> to that platform being phased out it is likely that there will never be
@@ -181,8 +173,8 @@ a source code change you have made). It is **strongly** recommended that
developers use this approach and end users *do not*.
#### Patching Shared Object Files
If you need to patch shared object files generated by meson-python directly you should first located the shared object file
these will be in the site-packages and site-packages/fourdst directories for your python enviroment.
If you need to patch shared object files generated by meson-python directly you should first locate the shared object file
these will be in the site-packages and site-packages/fourdst directories for your python environment.
Look for files named
@@ -195,7 +187,7 @@ then, for each of these files, run
otool -l <Path/to/file> | grep RPATH -A2
```
count the number of occurences of duplicate RPATH entries (these should look like `@loaderpath/.gridfire.mesonpy.libs` or `@loaderpath/../.fourdst.mesonpy.libs`). Then use `install_name_tool` to remove **all but one of these** from each shared object file.
count the number of occurrences of duplicate RPATH entries (these should look like `@loaderpath/.gridfire.mesonpy.libs` or `@loaderpath/../.fourdst.mesonpy.libs`). Then use `install_name_tool` to remove **all but one of these** from each shared object file.
If for example there are 4 occurrences of the path `@loader_path/../.fourdst.mesonpy.libs` in `_phys.cpython-3*-darwin.so` then you should run the following command 3 times
```bash
@@ -204,6 +196,8 @@ install_name_tool -delete_rpath @loader_path/../.fourdst.mesonpy.libs site-packa
the same for the other shared object file (make sure to count the duplicate rpath entries for each separately as there may be a different number of duplicates in each shared object file).
We also include a script at `pip_install_mac_patch.sh` which will do this automatically for you.
## Automatic Build and Installation
### Script Build and Installation Instructions
@@ -392,6 +386,9 @@ include:
networks.
- **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.
- **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
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,
allowing users to define compositions, configure engines, and run simulations
directly from Python scripts.