Metadata-Version: 2.4
Name: libnest
Version: 0.1.1
Summary: Library for Neutron Star physics: Brussels-Montreal (BSk) energy density functional and nuclear-matter tools.
Author-email: Daniel Pęcak <daniel.pecak@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/danielpecak/libnest
Project-URL: Repository, https://github.com/danielpecak/libnest
Project-URL: Documentation, https://libnest.readthedocs.io
Project-URL: Issues, https://github.com/danielpecak/libnest/issues
Keywords: physics,nuclear-physics,neutron-star,nuclear-matter,skyrme,bsk,equation-of-state,superfluidity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: pandas>=2.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: sphinxcontrib-katex; extra == "docs"
Requires-Dist: pillow; extra == "docs"
Provides-Extra: lint
Requires-Dist: ruff>=0.6; extra == "lint"
Dynamic: license-file

# 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.

[![PyPI](https://img.shields.io/pypi/v/libnest.svg)](https://pypi.org/project/libnest/)
[![Tests](https://github.com/danielpecak/libnest/actions/workflows/tests.yml/badge.svg)](https://github.com/danielpecak/libnest/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 🔬 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

```bash
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

```bash
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

```bash
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

```python
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:
```bash
python main.py
```

## 📚 Documentation

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

### Building documentation locally

```bash
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](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](https://github.com/nuclear-physics/skynet) - Nuclear reaction network
- [CompOSE](https://compose.obspm.fr/) - Equations of state database

---

**Version**: 0.1.1  
**Last Updated**: July 2026
