Metadata-Version: 2.4
Name: nn-rns
Version: 0.1.0
Summary: Neural-network surrogate models for rotating neutron star sequences.
Author: NN_RNS contributors
Project-URL: Homepage, https://github.com/zzhu-astro/NN_RNS
Project-URL: Repository, https://github.com/zzhu-astro/NN_RNS
Project-URL: Issues, https://github.com/zzhu-astro/NN_RNS/issues
Keywords: neutron-star,equation-of-state,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"

# nn_rns

`nn_rns` is a library of neural-network reconstruction for rotating neutron
stars. It evaluates reconstructed neutron-star observables from a user-provided
equation-of-state (EoS) table.

## Install

You can install `nn_rns` in two common ways.

### 1. Install from PyPI

```bash
pip install nn-rns
```

### 2. Install from source

```bash
git clone git@github.com:zzhu-astro/NN_RNS.git
cd NN_RNS
pip install .
```

For local development, you can also use editable mode:

```bash
pip install -e .
```

## Basic usage

The main workflow is:

1. Load the neural networks.
2. Load an EoS table.
3. Evaluate reconstructed rotating-neutron-star observables.

```python
from nn_rns import EoSTable, RNSNetworks

model = RNSNetworks()                     # load networks
eos = EoSTable("path/to/eos_table.rns")   # load EoS
model.rns_eval(eos)                       # evaluate observables
```

After `model.rns_eval(eos)`, the reconstructed results are stored in three main
members:

- `model.nn_rns_static`: reconstructed observables for static stars.
- `model.nn_rns_kepler`: reconstructed observables for the Kepler sequence.
- `model.nn_rns_rotate`: reconstructed observables for rotating models.

These arrays store the reconstructed observables generated by the trained neural
networks.

## Main functions

### `compute_observables()`

`compute_observables()` is used to compute interpolated observables for
user-specified rotation and central variables.

- Rotation input can be given as `Omega` or `r_ratio`.
- Central input can be given as `e_c`, `p_c`, or `nb_c`.
- The function returns interpolated observables on the target grid.

Typical usage:

```python
obs = model.compute_observables(
    rot_input=[0.4, 0.5],
    central_input=[1.0e15, 1.2e15],
    rot_input_type="Omega",
    central_input_type="e_c",
)
```

### `compute_m_max()`

`compute_m_max()` is used to compute the maximum mass sequence for
user-specified rotation input.

- Rotation input can be given as `Omega` or `r_ratio`.
- The function returns the interpolated maximum mass and the corresponding
  rotation quantity.

Typical usage:

```python
mmax, rot = model.compute_m_max(
    rot_input=[0.4, 0.5],
    rot_input_type="Omega",
)
```

## Warning

> [!WARNING]
> Data after the maximum mass may not be trustworthy due to the lack of
> training data.

Users should treat post-maximum-mass predictions with caution.

## Notes

- Users should provide their own EoS table when constructing `EoSTable`.
- The package ships with the trained model weights under `nn_rns/NN/`, so users
  do not need to download them separately.


## References

If you use `nn_rns` in research work or publications, please cite the
corresponding paper.

W. Liu, L. Wang and Z. Zhu, "Reconstruction of fast-rotating neutron star observables with the neural network", *arXiv preprint* [arXiv:2604.05428](https://arxiv.org/abs/2604.05428), 2026.
