TOV Extravaganza

Overview

TOVExtravaganza is a free, open-source Python package for solving the Tolman-Oppenheimer-Volkoff (TOV) equations and exploring neutron star properties. You install it with pip and run it on your own machine. Built for astrophysicists studying compact objects and gravitational wave astronomy.

This TOV equation solver provides everything you need to compute mass-radius sequences, tidal deformability calculations, Love numbers, and internal structure profiles for neutron stars. Perfect for research, education, and gravitational wave analysis.

Installation

From PyPI (Recommended)

pip install tovextravaganza

From Source

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

Complete Tutorial: DD2 Equation of State

This tutorial shows the complete workflow from raw EOS data to publication-quality results using the HS(DD2) equation of state as an example.

Step 0: Get Example Files

First, download the demo EOS files:

# Via pip
tovx-demo

# From source
python -m tovextravaganza.utils.demo

This downloads example files including hsdd2.csv to both inputRaw/ and inputCode/ directories.

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

Batch Processing Tutorial: Multiple EOS Files

Process multiple EOS files in parallel for high-throughput analysis.

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!

Features

• Interactive Wizard: Beginner-friendly guided workflow with auto-detection of EOS files
• Mass-Radius Calculations: Solve TOV equations for sequences of neutron stars with different central pressures
• Tidal Deformability: Compute Love numbers k₂ and dimensionless tidal deformability Λ for gravitational wave analysis
• Batch Processing: Process multiple EOS files in parallel for high-throughput analysis

Tutorial Plots & Results

Here are the actual plots produced by the tutorial commands above. The numbers quoted next to them are read off these plots. A few values in the batch table did not match the plots or the relation Λ = (2/3) k₂ (Rc²/GM)⁵; they are marked to be regenerated until the batch run is repeated.

DD2 Equation of State Results

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

HS(DD2): Mass-Radius, Tidal Deformability and Love Number

Enlarge

The plot contains three panels:

Left Panel: Mass-Radius Relationship

• X-axis: Radius (km), Y-axis: Mass (solar masses)
• Blue curve with markers: one point per star of the HS(DD2) sequence
• The curve peaks at the maximum mass, about 2.42 M☉ near R ≈ 12 km; past the peak it turns back to smaller radii (the unstable branch)

Middle Panel: Tidal Deformability Λ(M)

• X-axis: Mass (solar masses), Y-axis: Λ on a logarithmic scale
• Red curve with markers (“EoS prediction”): Λ(M) for HS(DD2)
• Blue star with error bar: the GW170817 constraint at 1.4 M☉ (the bar spans Λ ≈ 70 to 580); at 1.4 M☉ the DD2 curve (Λ ≈ 700) lies above it

Right Panel: Love Number k₂(M)

• X-axis: Mass (solar masses), Y-axis: Love number k₂ (dimensionless)
• Green curve with square markers: k₂(M) for HS(DD2)
• k₂ peaks at about 0.117 near 0.9 M☉ and falls with mass; past the maximum mass the curve turns back (unstable branch)

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

Enlarge

Phase-Coded M-R Curves

Enlarge

Data from: tovx --batch inputCode/Batch/ -n 1000 --workers 6

† The earlier values in these cells disagreed with the M-R plots above or with Λ = (2/3) k₂ (Rc²/GM)⁵ (GM☉/c² = 1.4766 km). They will be filled in from a fresh run of the batch command. The maximum masses match the plots.

Radial Profile Results

Internal Structure: radial profiles from the center to the surface, first for the maximum-mass star of one batch EOS, then for the HS(DD2) star closest to 1.4 M☉.

Radial Profile Plots

RGNJL_v0.70d1.45 at Maximum Mass: M(r), p(r), ε(r), n(r)

Enlarge

HS(DD2): Mass Profile M(r)

Enlarge

HS(DD2): Pressure Profile p(r)

Enlarge

HS(DD2) profiles generated by: tovx-radial inputCode/hsdd2.csv -M 1.4

CLI Reference

Complete command-line interface documentation with all parameters, defaults, and examples.

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

Examples

# 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

Examples

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

Examples

# 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

Usage Guide

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

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

Simple Usage

Via pip:

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

From source:

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

Advanced Options

Via pip:

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

From source:

python -m tovextravaganza.cli.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)

Output

CSV: export/stars/csv/<eos_name>.csv

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

Plots: export/stars/plots/<eos_name>.pdf

• Mass-Radius relationship
• Λ vs M (tidal deformability)
• k₂ vs M (Love number)

2. radial.py – Internal Structure Profiles

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

Usage

Via pip:

# 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☉)

From source:

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

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

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

Advanced Options

NEW features in v1.4.2+:

# 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

Output

HDF5 (default): export/radial_profiles/json/<eos_name>.h5

• 10-100x smaller than JSON (binary + compression)
• Fast read/write for large datasets
• Standard scientific format (Python, MATLAB, Julia, R)
• Requires: pip install tovextravaganza[hdf5] or pip install h5py

Fallback JSON: export/radial_profiles/json/<eos_name>.json

Used if h5py not installed, Human-readable but large files

3. converter.py – EOS Unit Converter

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

Interactive Mode

Via pip:

tovx-converter

From source:

python -m tovextravaganza.cli.converter

The script will guide you through:

1. Selecting input file from inputRaw/
2. Specifying if the file has a header
3. Identifying pressure and energy density columns
4. Choosing the unit system (MeV fm⁻³, CGS, etc.)

CLI Mode

Via pip:

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

From source:

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

Example:

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

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

Parameters:

• <input_file>: Filename in inputRaw/ folder
• <pcol>: Pressure column (1-based index)
• <ecol>: Energy density column (1-based index)
• <system>: Unit system choice (0-4, see table below)
• [output_file]: Optional output path (default: inputCode/<input_file>)

Output: Converted file saved to inputCode/ with columns rearranged as [p, e, ...]

Supported Unit Systems

Citation

If you use TOV Extravaganza in your research, please cite:

@software{Gholami_TOVExtravaganza_Python_toolkit_2025,
  author = {Gholami, Hosein},
  license = {MIT},
  month = jan,
  title = {{TOVExtravaganza: Python toolkit for solving the Tolman-Oppenheimer-Volkoff (TOV) equations and exploring neutron star properties}},
  url = {https://github.com/PsiPhiDelta/TOVExtravaganza},
  version = {1.0.0},
  year = {2025}
}

arXiv: 2411.04064

License

This project is licensed under the MIT License. See LICENSE for details.