TOVExtravaganza: Python Toolkit for Neutron Star Physics

From PyPI (Recommended)

pip install tovextravaganza

From Source

git clone https://github.com/PsiPhiDelta/TOVExtravaganza.git
cd TOVExtravaganza
pip install -e .

Step 0: Get Example Files

First, download the demo EOS files:

# Via pip
tovx-demo

# From source
python -m tovextravaganza.utils.demo

Step 1: Convert Raw EOS to Code Units

Input: inputRaw/hsdd2.csv - Raw EOS in CGS units (g/cm³ and dyn/cm²)

Goal: Convert to dimensionless TOV code units

# Via pip
tovx-converter inputRaw/hsdd2.csv -o inputCode/hsdd2.csv

# From source
python -m tovextravaganza.cli.converter inputRaw/hsdd2.csv -o inputCode/hsdd2.csv

The converter will analyze your file and ask:

Which column is PRESSURE? (1-based index): 2
Which column is ENERGY DENSITY? (1-based index): 1
Which unit system?
  1) MeV^-4
  2) MeV*fm^-3
  3) fm^-4
  4) CGS (g/cm^3, dyn/cm^2)
Select (1-4): 4

After confirmation, it converts the file and saves to inputCode/hsdd2.csv.

Features:

• Automatically preserves ALL additional columns (number density, chemical potential, etc.)
• Adds header comment showing conversion factors
• Reorders columns: pressure and energy first (converted), then rest (preserved)

Step 2: Compute Mass-Radius Sequence & Tidal Deformability

Goal: Solve TOV equations for 200 neutron stars with different central pressures

# Via pip
tovx inputCode/hsdd2.csv -n 200

# From source
python -m tovextravaganza.cli.tov inputCode/hsdd2.csv -n 200

Output:

• CSV: export/stars/csv/hsdd2.csv containing: Central pressure p_c, Radius R [km], Mass M_solar [M☉], Tidal deformability Lambda (dimensionless), Love number k2
• Plots: export/stars/plots/hsdd2.pdf

The plot shows three panels:

• Left: Mass-Radius relationship
• Middle: Tidal deformability Λ(M) with GW170817 constraint
• Right: Love number k₂(M)

Step 3: Generate Internal Structure Profiles

Goal: Get detailed radial profiles showing the star's interior from center to surface

# Via pip
tovx-radial inputCode/hsdd2.csv -M 1.4

# From source
python -m tovextravaganza.cli.radial inputCode/hsdd2.csv -M 1.4

What happens:

1. Searches for the star closest to 1.4 M☉
2. Computes full radial profile: M(r), p(r) at each radius point
3. Automatically interpolates all EOS columns at each radial point: ε(r), n(r), μ(r), phase(r), etc.
4. Saves all data to HDF5 format (or JSON if h5py not installed)
5. Generates plots with M-R context

Output:

• Data: export/radial_profiles/json/hsdd2.h5 (HDF5 format if h5py installed, otherwise JSON)
• Plots: Two PDFs with M-R context

Scenario: Analyze 6 Quark Matter EOS Models

Analyze 6 EOS files with color-superconducting quark matter (CSC and RGNJL series from arXiv:2411.04064). The RGNJL tables are from the RG-NJL-EoS-tables repository.

Step 0: Get Batch Example Files

The batch files are included with tovx-demo:

tovx-demo

This downloads 18 files total:

• 3 basic examples: test.csv, hsdd2.csv, csc.csv
• 6 batch EOS in inputCode/Batch/ (ready to use in code units)
• 6 raw batch EOS in inputRaw/batch/ (for unit conversion tutorials)
• 3 raw versions in inputRaw/

Step 1: Batch Convert to Code Units (Optional)

Note: Batch files are already in inputCode/Batch/, so you can skip to Step 2. This step is only if you want to practice unit conversion.

Convert all 6 raw batch files simultaneously:

# Via pip
tovx-converter --batch inputRaw/batch/ --pcol 2 --ecol 1 --system 3 --workers 6

# From source
python -m tovextravaganza.cli.converter --batch inputRaw/batch/ --pcol 2 --ecol 1 --system 3 --workers 6

Parameters: --pcol 2: Pressure is in column 2, --ecol 1: Energy density is in column 1, --system 3: Units are fm⁻⁴, --workers 6: Use 6 parallel workers

Result: All files converted to inputCode/Batch/ in ~2-5 seconds

Step 2: Batch Compute M-R Curves

Compute M-R sequences for all 6 EOS files:

# Via pip
tovx --batch inputCode/Batch/ -n 1000 -o export/batch_all --workers 6

# From source
python -m tovextravaganza.cli.tov --batch inputCode/Batch/ -n 1000 -o export/batch_all --workers 6

What happens:

• For each star, automatically interpolates all EOS columns at the central pressure
• Saves not just M, R, Λ, k₂ but also central energy density, number density, phase labels, etc.
• Lets you track how interior conditions (density, phase transitions) vary with stellar mass

Output: 6 CSV files with ~250-1000 stars each (R < 99 km filter), Each CSV includes: p_c, R, M_solar, Lambda, k2, central_e, central_n, central_phase, ..., 6 sets of M-R, Λ(M), k₂(M) plots, Completed in ~30-60 seconds (parallel processing!)

Results Summary:

CSC_v0.70d1.45   => M_max = 1.94 M☉
CSC_v0.80d1.50   => M_max = 2.08 M☉
CSC_v0.85d1.50   => M_max = 2.11 M☉
RGNJL_v0.70d1.45 => M_max = 2.06 M☉
RGNJL_v0.80d1.50 => M_max = 2.09 M☉
RGNJL_v0.85d1.50 => M_max = 2.19 M☉

Step 3: Batch Radial Profiles at Maximum Mass

Generate internal structure profiles at M_max for all 6 EOS:

# Via pip
tovx-radial --batch inputCode/Batch/ --max-mass -o export/radial_maxmass --workers 6

# From source
python -m tovextravaganza.cli.radial --batch inputCode/Batch/ --max-mass -o export/radial_maxmass --workers 6

What happens:

1. Each EOS: Fast M_max search (50 coarse + 200 fine = 250 TOV solves)
2. Finds M_max with precision < 0.01 M☉
3. Computes full radial profile with automatic interpolation of all EOS columns at each radius
4. Saves everything to HDF5 (or JSON) - complete radial data for post-processing
5. Generates M(r) and p(r) plots with M-R context

Output: 6 HDF5 files in export/radial_maxmass/*/json/*.h5 with complete radial data, 12 plots (Mass and Pressure profiles for each EOS), Total time: ~30 seconds for all 6 files in parallel!

DD2 Equation of State Results

Generated Plot: export/stars/plots/hsdd2.pdf

📊 Tutorial Plot: HS(DD2) Mass-Radius & Tidal Properties

export/stars/plots/hsdd2.pdf

📈

Three-Panel Plot

Left: Mass-Radius Relationship

Middle: Tidal Deformability Λ(M)

Right: Love Number k₂(M)

Generated by: tovx inputCode/hsdd2.csv -n 200

The plot contains three panels:

Batch Processing Results

6 Quark Matter EOS Models: Comparison of CSC and RGNJL series showing different maximum masses and tidal properties.

📊 Batch Processing Plots

All M-R Curves Comparison

📊

6 M-R Curves

CSC and RGNJL series

Different maximum masses

Phase-Coded M-R Curves

📈

Phase-Coded Plots

Color-coded by phase

Quark matter transitions

Generated by: tovx --batch inputCode/Batch/ -n 1000 --workers 6

Radial Profile Results

Internal Structure: Detailed radial profiles showing mass M(r) and pressure p(r) from center to surface for a 1.4 M☉ neutron star.

📈 Radial Profile Plots

Mass and Pressure Profiles

📈

Radial Profiles

Mass M(r) and Pressure p(r)

Internal structure

Mass Profile M(r)

📊

Mass Profile

M(r) vs Radius

Pressure Profile p(r)

📈

Pressure Profile

p(r) vs Radius

Generated by: tovx-radial inputCode/hsdd2.csv -M 1.4

tovx - TOV Solver Command

Usage: tovx [OPTIONS] INPUT_FILE

Options:
  -n, --nstars INTEGER        Number of stars to compute [default: 200]
  -o, --output TEXT          Output directory [default: export/stars]
  --dr FLOAT                 Radial step size [default: 0.001]
  --rmax FLOAT               Maximum radius (km) [default: 50.0]
  --rmax-plot FLOAT          Plot radius limit (km) [default: 20.0]
  --timeout INTEGER          Timeout per star (seconds) [default: 10]
  --quiet                    Suppress progress messages
  --no-plot                  Skip plot generation
  --no-show                  Don't display plots
  --batch TEXT               Process multiple files from directory
  --workers INTEGER          Number of parallel workers [default: 4]
  --help                     Show this message and exit

# Basic usage
tovx inputCode/hsdd2.csv

# High resolution
tovx inputCode/hsdd2.csv -n 1000 --dr 0.0001

# Batch processing
tovx --batch inputCode/Batch/ -n 500 --workers 8

# Custom output
tovx inputCode/hsdd2.csv -o results/my_analysis

tovx-radial - Radial Profiles Command

Usage: tovx-radial [OPTIONS] INPUT_FILE

Options:
  -n, --nprofiles INTEGER    Number of profiles [default: 10]
  -M, --mass FLOAT           Target mass (M☉) - can specify multiple
  -R, --radius FLOAT         Target radius (km) - can specify multiple
  --max-mass                 Find maximum mass star
  -o, --output TEXT          Output directory [default: export/radial_profiles]
  --dr FLOAT                 Radial step size [default: 0.001]
  --rmax-plot FLOAT          Plot radius limit (km) [default: 20.0]
  --timeout INTEGER          Timeout per star (seconds) [default: 10]
  --batch TEXT               Process multiple files from directory
  --workers INTEGER          Number of parallel workers [default: 4]
  --help                     Show this message and exit

# Default profiles
tovx-radial inputCode/hsdd2.csv

# Specific mass
tovx-radial inputCode/hsdd2.csv -M 1.4

# Multiple masses
tovx-radial inputCode/hsdd2.csv -M 1.4 -M 2.0

# Maximum mass
tovx-radial inputCode/hsdd2.csv --max-mass

# Batch processing
tovx-radial --batch inputCode/Batch/ --max-mass --workers 6

tovx-converter - Unit Converter Command

Usage: tovx-converter [OPTIONS] [INPUT_FILE] [PCOL] [ECOL] [SYSTEM] [OUTPUT_FILE]

Options:
  --batch TEXT               Convert all files in directory
  --pcol INTEGER             Pressure column (1-based) [default: 2]
  --ecol INTEGER             Energy density column (1-based) [default: 1]
  --system INTEGER           Unit system (0-4) [default: 4]
  --workers INTEGER          Number of parallel workers [default: 4]
  --help                     Show this message and exit

Unit Systems:
  0: Code units
  1: MeV^-4
  2: MeV*fm^-3
  3: fm^-4
  4: CGS (g/cm^3, dyn/cm^2)

# Interactive mode
tovx-converter

# CLI mode
tovx-converter hsdd2.csv 2 1 4 inputCode/hsdd2.csv

# Batch conversion
tovx-converter --batch inputRaw/batch/ --pcol 2 --ecol 1 --system 3 --workers 6

1. tov.py – Mass-Radius & Tidal Deformability

The main workhorse. Solves TOV equations and computes tidal properties for a sequence of neutron stars.

tovx inputCode/hsdd2.csv           # 200 stars (default)
tovx inputCode/test.csv -n 500     # 500 stars

python -m tovextravaganza.tov inputCode/hsdd2.csv
python -m tovextravaganza.tov inputCode/test.csv -n 500

tovx inputCode/hsdd2.csv -n 1000 --dr 0.0001 --quiet --no-show

python -m tovextravaganza.tov inputCode/hsdd2.csv \
    -n 1000 \                               # Number of stars
    -o export/my_stars \                    # Custom output folder
    --dr 0.0001 \                           # Radial step size
    --rmax 50 \                             # Maximum radius
    --rmax-plot 15 \                        # 🆕 NEW! Zoom M-R plot to R ≤ 15 km (default: 20)
    --timeout 20 \                          # 🆕 NEW! Abort stars taking > 20s (default: 10s)
    --quiet \                               # Suppress progress messages
    --no-plot \                             # Skip plot generation
    --no-show                               # Don't display plot (still saves)

p_c,R,M_code,M_solar,Lambda,k2
0.00010000,12.34,0.123,0.543,789.12,0.098
0.00015000,11.89,0.156,0.689,456.78,0.087
...

2. radial.py – Internal Structure Profiles

Get detailed profiles of mass, pressure, and energy density from center to surface.

# Generate profiles across pressure range
tovx-radial inputCode/hsdd2.csv           # 10 profiles (default)
tovx-radial inputCode/test.csv -n 20      # 20 profiles

# Generate profiles for specific mass/radius
tovx-radial inputCode/hsdd2.csv -M 1.4          # Star closest to 1.4 M☉
tovx-radial inputCode/hsdd2.csv -R 12.0         # Star closest to 12 km
tovx-radial inputCode/hsdd2.csv -M 1.4 -M 2.0   # Multiple masses
tovx-radial inputCode/hsdd2.csv -M 1.4 -R 12    # By mass AND radius

# 🆕 NEW! Generate profile at maximum mass
tovx-radial inputCode/hsdd2.csv --max-mass      # Finds M_max automatically (precision < 0.01 M☉)

# Generate profiles across pressure range
python -m tovextravaganza.radial inputCode/hsdd2.csv           # 10 profiles (default)
python -m tovextravaganza.radial inputCode/test.csv -n 20      # 20 profiles

# Generate profiles for specific mass/radius
python -m tovextravaganza.radial inputCode/hsdd2.csv -M 1.4          # Star closest to 1.4 M☉
python -m tovextravaganza.radial inputCode/hsdd2.csv -R 12.0         # Star closest to 12 km
python -m tovextravaganza.radial inputCode/hsdd2.csv -M 1.4 -M 2.0   # Multiple masses
python -m tovextravaganza.radial inputCode/hsdd2.csv -M 1.4 -R 12    # By mass AND radius

# 🆕 NEW! Generate profile at maximum mass
python -m tovextravaganza.radial inputCode/hsdd2.csv --max-mass      # Finds M_max automatically (precision < 0.01 M☉)

# Control plot viewport (doesn't crop data)
tovx-radial inputCode/hsdd2.csv --rmax-plot 15   # M-R diagrams show only R ≤ 15 km

# Set timeout for stuck calculations
tovx-radial inputCode/hsdd2.csv --timeout 20     # Abort stars taking > 20s (default: 10s)

# Batch process all EOS files at M_max
tovx-radial --batch inputCode/Batch/ --max-mass  # Parallel M_max profiles

3. converter.py – EOS Unit Converter

Sick of unit conversion? I was too. This tool converts raw EOS data into TOV code units.

tovx-converter

python -m tovextravaganza.converter

tovx-converter <input_file> <pcol> <ecol> <system> [output_file]

python -m tovextravaganza.converter <input_file> <pcol> <ecol> <system> [output_file]

# Via pip
tovx-converter hsdd2.csv 2 3 4 inputCode/hsdd2.csv

# From source
python -m tovextravaganza.converter hsdd2.csv 2 3 4 inputCode/hsdd2.csv