saclay-format 0.3.0
python parser and usefull script related to the saclay format
Requires Python: >=3.10

# Saclay_format (v0.3.0)

This repository defines a data standard to describe parts of the inputs/outputs of 
mean-field theory codes in the nuclear physics and astrophysics communities.
It adheres to the results of the 05/2025 and 10/2025 ESNT workshops entitled 
*"Simulating dense matter on three-dimensional coordinate space meshes (part I and II)"*.

It also defines and implements two storage formats for the data:

1. A format relying on a series of custom binary files containing the raw data along with
a YAML header containing metadata. This format ensures compatibility with the [wdata](TODO)
format, requires a YAML library and is not 100% portable.

2. A [HDF5](https://support.hdfgroup.org/documentation) format.
This requires the HDF5 library and ensures portability.

## Content

* `src/saclay_format` — Python3 package to parse and visualize the data standard
* `docs` — documentation on this package and specification of the data content and formats
* `examples` — nuclear mean-field outputs in this format
* `tests` — unit tests of the package

## Requirements

* `numpy` —  Python3 package for linear algebra
* `pyyaml` — Python3 package for YAML parsing
* `h5py` — Python3 package for HDF5 parsing

## Installation via PyPI

The parser is available as a PyPI package:
[https://pypi.org/project/saclay-format/](https://pypi.org/project/saclay-format/)

Install it using pip:

```bash
pip install saclay-format
```

This also installs several command-line scripts:

* `saclay_format_ev8_to_ev1`
* `saclay_format_ev1_to_cr1`
* `saclay_format_hdf5_yaml_converter`
* `saclay_format_compute_densities`
* `saclay_format_visualisation_rho`
* `saclay_format_visualisation_rho_TD`
* `saclay_format_visualisation_ascii`

## Running the parser

From a Python terminal, import the package and use its `read()` and `write()` methods.
Example:

```python
import saclay_format

data = saclay_format.read('file.yml')
# Modify or inspect data...
saclay_format.write(data, 'file_out.h5')
```

To run the unit tests:

```bash
cd tests/
python3 test_saclay_format.py
```

## Examples

### Example structure

```
examples/20Ne_bcs_hdf5/
├── state.h5
├── fields.h5
└── README.md

examples/alpha_alpha_3MeV/
├── reaction_alpha_alpha_3MeV_header.yml
├── reaction_alpha_alpha_3MeV_rho_n.bin
├── reaction_alpha_alpha_3MeV_rho_p.bin
├── README_visualisation_convert.md
└── script_test.convert.sh

examples/Ca40_ev8/
├── Ca40_HF_SLy4.yaml
├── Ca40_HF_SLy4_*.dat
└── README_test.md
```

### Conversion test

```bash
python3 ../../src/saclay_format/hdf5_yaml_converter.py -h5 Ca40_HF_SLy4.yaml
python3 ../../src/saclay_format/ev8_to_ev1.py Ca40_HF_SLy4.h5 -o Ca40_HF_SLy4_ev1.h5
python3 ../../src/saclay_format/ev1_to_cr1.py Ca40_HF_SLy4_ev1.h5 -o Ca40_HF_SLy4_cr1.h5
```

### Visualization test

Static:

```bash
python3 ../../src/saclay_format/visualisation_rho.py reaction_alpha_alpha_3MeV_header.yml
```

Dynamic:

```bash
python3 ../../src/saclay_format/visualisation_rho_TD.py reaction_alpha_alpha_3MeV_header.yml
```

Conversion and round-trip test:

```bash
python3 ../../src/saclay_format/hdf5_yaml_converter.py -h5 reaction_alpha_alpha_3MeV_header.yml
mv reaction_alpha_alpha_3MeV_header.h5 reaction_alpha_alpha_3MeV_converted.h5
python3 ../../src/saclay_format/visualisation_rho_TD.py reaction_alpha_alpha_3MeV_converted.h5
python3 ../../src/saclay_format/hdf5_yaml_converter.py -yaml reaction_alpha_alpha_3MeV_converted.h5
python3 ../../src/saclay_format/visualisation_rho_TD.py reaction_alpha_alpha_3MeV_converted.yaml
rm reaction_alpha_alpha_3MeV_converted*
```

## Todo

* Should we stick to a constant rank for the numpy arrays returned by the read method ?
* Should we clarify the Python dictionary returned by read ?
* Change `t0` and `frame` to `tmin` and `nt`
* Should we stick to [ix,iy,iz...] with column-major storage or go back to the numpy
native storage and a [...,iz,iy,ix] order for the indices ?

## Project layout

This project follows the structure recommended by the Hitchhiker’s Guide to Python:
[https://docs.python-guide.org/writing/structure](https://docs.python-guide.org/writing/structure)