libnest

Library for Neutron Star Physics

A Python library for nuclear matter and neutron star physics calculations, implementing the Brussels-Montreal (BSk) energy density functional and related physical models.

🔬 Overview

libnest provides computational tools for:

• Energy density functionals: Brussels-Montreal Skyrme parametrization (BSk31)
• Nuclear matter properties: Equations of state, effective masses, pairing fields
• Neutron star physics: Inner crust structure, superfluid properties, pasta phases
• Unit conversions: Nuclear physics units (MeV, fm⁻³, etc.) and astronomical units
• Visualization: Ready-to-use plotting functions for physical quantities

This library is designed for researchers working on:

• Dense matter in neutron stars
• Nuclear superfluidity and pairing
• Neutron star crust composition
• Nuclear energy density functionals

📦 Installation

We strongly recommend installing into a virtual environment (venv). It keeps libnest and its dependencies isolated from your system Python and avoids version conflicts — in particular NumPy/Matplotlib ABI mismatches (numpy.core.multiarray failed to import) that occur when the system packages were built against a different NumPy. Do not run the code with your system python3.

1. Create and activate a virtual environment

git clone https://github.com/danielpecak/libnest.git
cd libnest

python3 -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows (cmd)
# .venv\Scripts\Activate.ps1     # Windows (PowerShell)

Your prompt now shows (.venv). Everything below runs inside it; leave later with deactivate.

2. Install libnest

pip install libnest              # from PyPI (once released)

pip install -e .                 # or from source, editable (for development)
pip install -e ".[test]"         # + test tools (pytest)
pip install -e ".[docs]"         # + documentation tools (Sphinx)

3. Check it works

python main.py                   # runs the demo
pytest                           # runs the test suite (needs the [test] extra)

Requirements

• Python ≥ 3.9
• NumPy, SciPy, Matplotlib, Pandas — installed automatically

Exact runtime dependencies are declared in pyproject.toml (mirrored in requirements.txt).

🚀 Quick Start

import libnest
import libnest.bsk
import libnest.definitions

# Example 1: Unit conversion
rho_fm3 = 0.16  # nuclear saturation density
rho_gcm3 = libnest.units.fm3togcm3(rho_fm3)
print(f"Density: {rho_fm3} fm⁻³ = {rho_gcm3:.2e} g/cm³")

# Example 2: Calculate Fermi energy
rho_n = 0.08  # neutron density in fm⁻³
kF = libnest.definitions.rho2kf(rho_n)
eF = libnest.definitions.eF_n(kF)
print(f"Fermi energy: {eF:.2f} MeV")

# Example 3: BSk energy functional
rho_n = rho_p = 0.08  # symmetric nuclear matter
E_per_A = libnest.bsk.energy_per_nucleon(rho_n, rho_p)
print(f"Energy per nucleon: {E_per_A:.2f} MeV")

# Example 4: Neutron pairing gap
delta_n = libnest.bsk.neutron_pairing_field(rho_n)
print(f"Pairing gap: {delta_n:.2f} MeV")

Run the included example:

python main.py

📚 Documentation

Full documentation is built with Sphinx and published to GitHub Pages: https://danielpecak.github.io/libnest/

Building documentation locally

cd docs
make html

The documentation will be in docs/_build/html/.

🧪 Modules

Core Modules

• units: Physical constants and unit conversion functions
• definitions: Basic definitions (Fermi wavevector, energy, velocities)
• bsk: Brussels-Montreal Skyrme functional (BSk31 parametrization)
• tools: Utility functions (center of mass, condensation energy, slicing)
• myio: Input/output functions for data files

Analysis Modules

• plots: Plotting functions for uniform matter properties
• real_data_plots: Visualization for simulation output
• delta_and_temperature: Temperature-dependent pairing analysis
• pasta: Nuclear pasta phases in the crust
• nucleus: Nuclear structure calculations

📖 Examples

See the examples/ directory for more comprehensive examples:

• examples/analyze_data.py - Load a density map, compute a physical quantity per grid point, and plot it (the "analyze your own data" starting point)
• examples/tools_example.py - Using utility functions

🧮 Physical Constants

The library uses natural units with ℏ = c = 1 where convenient. Key constants:

Constant	Value	Unit	Description
HBARC	197.327	MeV·fm	ℏc
MN	939.565	MeV	Neutron mass
MP	938.272	MeV	Proton mass
RHOSAT	0.16	fm⁻³	Nuclear saturation density

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Daniel Pęcak

• Email: daniel.pecak@gmail.com
• Affiliation: Institute of Physics, Polish Academy of Sciences

🙏 Acknowledgments

This work has been supported by:

• Polish National Science Centre (NCN)
• PLGrid Infrastructure
• LUMI Supercomputer (EuroHPC)

📚 References

If you use this library in your research, please cite:

• S. Goriely, N. Chamel, J.M. Pearson, Phys. Rev. C 88, 024308 (2013) - BSk functional
• N. Chamel, S. Goriely, J.M. Pearson, Phys. Rev. C 80, 065804 (2009) - Pairing model

See docs/bibliography.rst for a complete list of references.

🔗 Related Projects

• SkyNET - Nuclear reaction network
• CompOSE - Equations of state database

---

Version: 0.1.1
Last Updated: July 2026