# Reaclib to Header File Utility
This utility module provides a script to convert reaclib2 format (with chapters
9, 10, and 11) data into a c++ header file formated for use within SERiF. This
script uses preprocessor directives to ensure that the only reactions included
are ones for which all reactants and products are defined. That is to say that
at compile time this will cull any reaction for which we do not have data from
AME2020. One effect of this is that the non-elemental reactions which reaclib
traces (such as things like nrf, and pkrf) are not included in the reaction
library.

## Usage
There are no dependencies which are not part of a standard python installation

You will however need to provide the reaclib2 formated file. This can be downloaded from
the [reaclib snapshot library](https://reaclib.jinaweb.org/library.php?action=viewsnapshots).

Assuming you download that file to your ~/Downloads directory, and it is called something like
`results123` then usage is as simple as

```bash
python format.py ~/Downloads/results123 -o reaclib.h
```

This will generate the `reaclib.h` header file in your current directory.

> The c and T flags are optional, but they are used to set the culling parameter. c is the minimum rate
that a reaction must have to be included in the header file and T is the T9 temperature to evaluate that
rate at. Without culling (when -c is set to 0 or not set) the header file may be very large.

In order to make a translation unit `reaclib.h` depends on `atomicSpecies.h` 
which is another header file automatically generated by a utility module (utils/atomic).

> `atomicSpecies.h` provides the Species structs which are used to ensure that only reactions 
where the reactants and products are species in AME2020 are included. This pretty significantly 
cuts down on compiled binary size. This is done using preprocessor directives.

Once `reaclib.h` has been generated you can recompile `SERiF` with it simply by
running the following (from your `SERiF` root directory and assuming
`reaclib.h` is in `SERiF/utils/reaclib`)

```bash
mv assets/static/reaclib/reaclib.h assets/static/reaclib/reaclib.h.bak
cp utils/reaclib/reaclib.h assets/static/reaclib/reaclib.h
meson compile -C build
```

> All tests are run with the bundled reaclib.h based on a checkout of the
reaclib default snapshot on June 17th, 2025 where the most recent documented
change was on June 24th, 2021. This means that if you update reaclib.h some
tests may fail.

## For Developers
If you are updating the default reaclib.h file, please ensure that you also
update any relevant tests and documentation to reflect the changes made.

Further, if in the future the parser needs updating, please ensure that
those changes get upstreamed into this utility script. It is a key development guideline
that all of our tools are well documented and easy for non `SERiF` developers
to use.

## Pynucastro rates
If you have pynucastro installed you may use the `gen_rates.py` function to generate 
a rate file dump. Currently this file filters by Z but you can update this with
arbitrary internal logic. After generating this file run it through format.py with -f bin and -o reactions.bin 
and then the bin to header script. 

```bash
python ../bin_to_header.py reactions.bin reactions_data.h raw_reaction_data
```

then copy the reactions_data.h files to `GridFire/src/include/gridfire/reactions`

## Citations
REACLIB: 
 - Rauscher, T., Heger, A., Hoffman, R. D., & Woosley, S. E. 2010, ApJS, 189, 240.
