Metadata-Version: 2.4
Name: compytools
Version: 0.2.0
Summary: Read and write CompOSE equation-of-state tables.
Author-email: "Philip J. Davis" <davis@lpccaen.in2p3.fr>
License-Expression: MIT
Project-URL: Documentation, https://compytools.in2p3.fr/
Project-URL: Repository, https://gitlab.in2p3.fr/lpc-caen/compytools
Project-URL: Issues, https://gitlab.in2p3.fr/lpc-caen/compytools/-/issues
Keywords: astrophysics,CompOSE,equations of state,neutron stars,nuclear physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Programming Language :: Fortran
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy>=7.1.0
Requires-Dist: lalsuite==7.26.15.1.dev20260923
Requires-Dist: matplotlib>=3.10.3
Requires-Dist: pandas>=2.3.2
Requires-Dist: pdg==0.2.2
Requires-Dist: scipy>=1.15.2
Requires-Dist: requests
Requires-Dist: rich>=14.1.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: jupyter-sphinx; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: sphinx-copybutton; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: sphinxemoji; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: jupyter
Requires-Dist: jupyterlab>=4.4.3; extra == "jupyter"
Requires-Dist: pdf2image; extra == "jupyter"
Dynamic: license-file

![compytools](https://gitlab.in2p3.fr/lpc-caen/compytools/-/raw/main/docs/source/logo/ComPyTools_logo_rescaled.png)

[![PyPI - Version](https://img.shields.io/pypi/v/compytools)](https://pypi.org/project/compytools/)
[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/license/mit)
[![astropy](http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat-square)](http://www.astropy.org/)
![coverage](https://img.shields.io/badge/coverage-91%25-orange)

**ComPyTools** is an open source (MIT) Python package for working with equation of state (EoS) tables in the [**CompOSE** ("CompStar Online Supernova Equations of State")](https://compose.obspm.fr/home/) format. It provides tools to read, write and analyse **CompOSE** tables within Python workflows, leveraging **astropy** for data tables, units and metadata.

**ComPyTools** allows the user to:

* Read in **CompOSE** cold or general purpose EoS tables,
* Create interpolated tables from cold or general purpose EoSs via a Python interface to the **CompOSE** code,
* Produce cold EoS tables in the **CompOSE** format for those who wish to contribute their own EoS to the **CompOSE** database.

# Quick Example 1: Reading **CompOSE** tables

```python
import tempfile
import matplotlib.pyplot as plt

from compytools import EoS
from compytools.download import CompOSEDownloader

# Download sample data into temporary directory
# for purposes of this example
tmpdir = tempfile.TemporaryDirectory()
downloader = CompOSEDownloader.from_eosname('PCP(BSk22)', tmpdir.name)
downloader.get()

bsk22 = EoS.from_compose(tmpdir.name)

# View the data in tabular form
bsk22.thermo.pprint(max_width=-1)

# View column descriptions
print(bsk22.thermo.info)

nb = bsk22.params.nb.grid_points
# Q1 corresponds to the ratio p/nb
pressure = bsk22.thermo['Q1'] * nb
plt.loglog(nb, pressure)
plt.grid()

plt.xlabel(r'$n_{B}$ [fm$^{-3}$]')
plt.ylabel(r'$p$ [MeV fm$^{-3}$]')
plt.show()
```
![PCP(BSk22) example](https://gitlab.in2p3.fr/lpc-caen/compytools/-/raw/main/docs/source/figs/BSk22_pressure_versus_nb_example.png)

# Quick Example 2: Create interpolated tables from cold CompOSE data

```python
import tempfile

from compytools import (
    GridSettings,
    Interface,
    summarise
)

from compytools.download import CompOSEDownloader

# Download a sample table
tmpdir = tempfile.TemporaryDirectory()
getter = CompOSEDownloader.from_eosname('PCP(BSk22)', tmpdir.name)
getter.get()

# Summarise the grid parameters and available
# thermodynamic quantities
summarise(tmpdir.name, tables='thermo')
```
```
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Quantity Number ┃ Quantity                                       ┃ Unit          ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 1               │ total pressure                                 │ 1.0 MeV / fm3 │
│ 2               │ total entropy per baryon                       │               │
│ 3               │ shifted baryon chemical potential              │ MeV           │
│ 4               │ charge chemical potential                      │ MeV           │
│ 5               │ lepton chemical potential                      │ MeV           │
│ 6               │ Scaled free energy per baryon                  │               │
│ 7               │ Scaled internal energy per baryon              │               │
│ 8               │ Scaled enthalpy per baryon                     │               │
│ 9               │ Scaled free enthalpy per baryon                │               │
│ 18              │ isothermal compressibility                     │ fm3 / MeV     │
│ 20              │ Free energy per baryon                         │ MeV           │
│ 21              │ Energy per baryon (with rest mass              │ MeV           │
│                 │ contribution)                                  │               │
│ 22              │ enthalpy per baryon                            │ MeV           │
│ 23              │ free enthalpy per baryon                       │ MeV           │
│ 24              │ Energy density                                 │ 1.0 MeV / fm3 │
└─────────────────┴────────────────────────────────────────────────┴───────────────┘
```
```python
# 1. Define the grid in baryon number density for the interpolation
nbgrid = GridSettings(
    # Min. and max. grid point values
    min=1.e-7,
    max=1.0,
    # interpolation order
    order=2,
    # Num. of points
    npoints=200,
    # Choose grid on log scale
    logscale=True
)

# 2. Set up the CompOSE interface
interface = Interface(
    # Directory containing the tables
    eospath=tmpdir.name,
    # Grid settings for baryon number density
    nbconfig=nbgrid,
    # Values defining pressure (1) and energy density (24)
    # given in the summary table above
    thermo_choice=[1, 24]
)

# 3. Run the interface and display the table.
# The table is saved to the same location as the
# CompOSE tables.
table = interface.run()
table.pprint()
```

# Quick Example 3: Create mandatory **CompOSE** tables for a cold EoS

```python
import os
import tempfile

from urllib.request import urlretrieve

import numpy as np

from compytools import (
    EoS,
    Grid,
    GridData,
    Thermo,
    ThermoData,
    NeutronStar,
    NeutronStarData,
    Nucleons
)

from compytools.constants import (
    DIMENSIONLESS,
    DYN_PER_CM2,
    G_PER_CM3,
    GRAM,
    MEV,
    PERFM3
)

# Download sample data to be converted into CompOSE format
tmpdir = tempfile.TemporaryDirectory()
eos_file = "eos_akmalpr.d"
eos_url = "https://gitlab.in2p3.fr/lpc-caen/compytools/-/raw/main/tests/inputs/lorene/"
    
source = os.path.join(eos_url, eos_file)
dest = os.path.join(tmpdir.name, eos_file)

urlretrieve(source, dest)

# Load the data
nbgrid, rho, p = np.loadtxt(
    dest,
    # Ignore file's header info
    skiprows=9,
    usecols=(1, 2, 3),
    unpack=True
)

# Prepare the grid parameter data
# 1. Enter the grid parameter data with units
grid_data = GridData(
    # Temperature grid points in MeV. Zero for a cold EoS
    t=np.array([0.0]) << MEV,
    # Baryon number density in 1/fm^3
    nb=nbgrid << PERFM3,
    # Charge fraction (no units). Zero for a cold EoS
    yq=np.array([0.0]) << DIMENSIONLESS
)

# 2. Convert into tabular format
grid_params = Grid.from_dataset(grid_data)

# Prepare the thermodynamic quantities
# 1. Nucleon masses
nucleons = Nucleons(
    mn=1.6749286e-24 << GRAM,
    mp=1.6726231e-24 << GRAM,
    # Indicates that leptons are considered (0 otherwise)
    has_leptons=1
)

# 2. Enter thermodynamic quantities with units
thermo_data = ThermoData(
    grid_params=grid_params,
    nucleons=nucleons,
    pressure=p << DYN_PER_CM2,
    entropy_density=np.zeros(nbgrid.size) << PERFM3,
    charge_chemical_potential=np.zeros(nbgrid.size) << MEV,
    lepton_chemical_potential=np.zeros(nbgrid.size) << MEV,
    # Free and internal energy densities are equal for a cold EoS
    free_energy_density=rho << G_PER_CM3,
    internal_energy_density=rho << G_PER_CM3,
)

# 3. Convert data into tabular form
thermo = Thermo.from_dataset(thermo_data)

# Calculate the static neutron star properties
# 1. Compute the data
ns_data = NeutronStarData(
    grid_params=grid_params,
    thermo=thermo
)

# 2. Convert to tabulated form
mr = NeutronStar.from_dataset(ns_data)

# Combine the tables and write the CompOSE files
myeos = EoS(
    params=grid_params,
    thermo=thermo,
    mr=mr
)

# Write the files to your current working directory
myeos.to_compose('./')
```

# Documentation

Full documentation, including installation instructions, a tutorial and an API reference can be found on the [ComPyTools web page](https://compytools.in2p3.fr/).

# Requirements

**ComPyTools** requires at least Python 3.12 along with the following Python packages, which will be installed automatically via the steps outlined in the [Installation](#installation) section:

- **Astropy**: for displaying data in tabular form and to attach metadata and units to the data. We also use physical constants defined within **astropy**,
- **lalsuite**: for solving the Tolman-Oppenheimer-Volkoff equations to calculate neutron star static properties,
- **Matplotlib**: for plotting EoS data,
- **Pandas**: for writing out tabulated data into text files,
- **PDG**: for accessing particle masses via the Particle Data Group (PDG) database,
- **requests**: for downloading sample data,
- **Rich**: for log output and tabulating metadata information,
- **Scipy**: for performing integration, optimization and interpolation tasks.

Additional packages are also needed to install and build **ComPyTools**:

- [**CompOSE**](https://compose.obspm.fr/software/): a set of Fortran routines for computing the interpolated tables. This is included as part of the **ComPyTools** package,
- **cmake** and **make**: for compiling the **CompOSE** Fortran routines,
- **gfortran**: compiler for the Fortran routines,
- **micromamba** or **conda**: for creating the software environment within which to install ComPyTools,
- **tectonic**: required when creating the **CompOSE** PDF datasheet describing a contributor's EoS.

# Installation

For Linux, MacOS or WSL for Windows, install **micromamba** (recommended for a more optimized, drop-in replacement of **conda**) with
```
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)
```

and create the **micromamba** environment in order to install the build and compilation tools:
```
micromamba create -n compytools-env -c conda-forge python=3.12 cmake make gfortran tectonic
```
Activate the environment with
```
micromamba activate compytools-env
```
Then, install **ComPyTools** with **pip**:
```
pip install compytools
```

This will also compile **CompOSE** on your machine. You can test the installation with:
```
python -c "import compytools"
```

Further details can be found on the [installation instructions](https://compytools.in2p3.fr/installation.html).

# License

[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/license/mit)

**ComPyTools** is released under the MIT license.

# Acknowledgements

The development of **ComPyTools** has been partially supported by the French Centre National de la Recherche Scientifique (CNRS) International Research Project (IRP) "Origine des éléments lourds dans l'univers: Astres Compacts et Nucléosynthèse (ACNu)".

We also acknowledge contributions from the **CompOSE** core development team and members of the LuTH-Caen group within the Virgo collaboration.

# Contributing and contact

**ComPyTools** is a community project. We therefore welcome and appreciate any comments that you may have to improve the tool. Suggestions or bug reports can be communicated to Philip Davis at the following email address: davis@lpccaen.in2p3.fr, or by opening an [issue](https://gitlab.in2p3.fr/lpc-caen/compytools/-/work_items).
