nn-rns 0.1.0

Neural-network surrogate models for rotating neutron star sequences.

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

pip install nn-rns

2. Install from source

git clone [e-mail]:zzhu-astro/NN_RNS.git
cd NN_RNS
pip install .

For local development, you can also use editable mode:

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.

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:

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:

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, 2026.