Metadata-Version: 2.4
Name: exfor_tools
Version: 1.1
Summary: A lightweight interface to grab and organize differential cross sections from EXFOR, using the x4i3 library.
Author: Kyle Beyer
License: MIT License
        
        Copyright (c) 2024 Kyle Beyer
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.5
Requires-Dist: x4i3>=1.2.0
Requires-Dist: periodictable>1.0
Requires-Dist: matplotlib
Dynamic: license-file

[![Python package](https://github.com/beykyle/exfor_tools/actions/workflows/python-package.yml/badge.svg)](https://github.com/beykyle/exfor_tools/actions/workflows/python-package.yml)
[![PyPI publisher](https://github.com/beykyle/exfor_tools/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/beykyle/exfor_tools/actions/workflows/pypi-publish.yml)

# exfor-tools
Some lightweight tools to grab data from the [EXFOR database](https://www-nds.iaea.org/exfor/) using the [x4i3 library](https://github.com/afedynitch/x4i3/), and organize it for visualization and use in model calibration and uncertainty quantification.

## scope

Currently, `exfor_tools` supports most reactions in EXFOR, but only a small subset of the observables/quantities. Feel free to contribute! If it doesn't meet your needs check out the project it's built on, which is far more complete: [x4i3](https://github.com/afedynitch/x4i3/).

## quick start
```
 pip install exfor-tools
```

Package hosted at [pypi.org/project/exfor-tools/](https://pypi.org/project/exfor-tools/). Otherwise, for development, simply clone the repo and install locally:

```
git clone git@github.com:beykyle/exfor_tools.git --recurse-submodules
pip instal exfor_tools -e 
```

## tutorials

You can run the notebooks in the `examples/` directory to see how to use the package. 

To run the notebooks, some additional dependencies are required:

```
pip install -r examples/requirements.txt
```

There are two directories in `examples/`: `examples/examples_2025_release/` and `examples/examples_2023_release/`. The former contains notebooks with stored outputs valid for the latest EXFOR release, while the latter contains notebooks with stored outputs valid for the `2023-04-29` release. You can run either one, the only difference is the stored outputs (which are used for testing).

The examples include:
-   [examples/examples_2025_release/introductory_tutorial.ipynb](https://github.com/beykyle/exfor_tools/blob/main/examples/examples_2025_release/introductory_tutorial.ipynb)
-   [examples/examples_2025_release/data_curation_tutorial.ipynb](https://github.com/beykyle/exfor_tools/blob/main/examples/examples_2025_release/dataset_curation_tutorial.ipynb)

These demonstrate how to query for and parse exfor entries, and curate and plot data sets. In the first one, you will produce this figure: 

![](https://github.com/beykyle/exfor_tools/blob/main/assets/lead_208_pp_dxds.png)

## test

The tests and the examples are one and the same. To run the tests, first install the dependencies for the notebooks:

```
pip install -r examples/requirements.txt
```

Then, to test that the notebooks run, use:

```
pytest --nbmake examples/examples_2025_release/
```

To test that they produce the expected results, use:

```
pytest --nbval-lax examples/examples_2025_release/
```

Note that there may be some difference in your installation, e.g. if you're using a different version of the EXFOR database, so the expected results may not be exactly the same as those in the tutorials. 

By default, `x4i3` ships with the `2023-04-29` EXFOR release. There are a set of notebooks with stored outputs valid for that release in `examples/examples_2023_release/`. These are used in the github actions. If you haven't updated to a more recent release but you would like to run the tests, then simply run:


```
pytest --nbval-lax examples/examples_2023_release/
```


## updating the EXFOR data base

First, download your desired version `<exfor-YYYY.zip>` from here: [https://nds.iaea.org/nrdc/exfor-master/list.html](https://nds.iaea.org/nrdc/exfor-master/list.html). The latest is recomended. Then:

```sh
bash update_database.sh </path/to/exfor-XXXX.zip> --db-dir </path/where/db/should/go/>
```

This will extract and process the data to `</path/where/db/should/go/unpack_exfor-YYYY/X4-YYYY-12-31>`, setting the environment variable `$X43I_DATAPATH` accordingly. `x4i3` uses this environment variable to find the database on `import`, so you should add this to your environment setup. If you use bash, this will look something like this:

```sh
echo export X43I_DATAPATH=$X43I_DATAPATH >> ~/.bashrc
```

This functionality for modifying the database used by `x4i3` is provided in [x4i3_tools](https://github.com/afedynitch/x4i3_tools), which is included as a submodule.
