Python Toolkit for Neutron Star Physics: Solve TOV Equations, Calculate Tidal Deformability, and Explore Neutron Star Properties
TOV Extravaganza is a comprehensive Python package for astrophysicists and researchers studying neutron stars, compact objects, and gravitational wave astronomy. Solve the Tolman-Oppenheimer-Volkoff (TOV) equations, compute tidal deformabilities for binary neutron star mergers, generate detailed radial profiles of neutron star interiors, and explore the Mass-Radius relationship for different equations of state (EoS).
- Interactive Wizard – Beginner-friendly guided workflow (just answer questions!)
- Mass-Radius Calculations – Solve TOV equations for multiple central pressures
- Tidal Deformability – Compute dimensionless tidal deformability (Λ) and Love number (k₂)
- Batch Processing 🚀 NEW! – Process multiple EOS files in parallel:
- Converter Batch: Convert all raw EOS files with any columns preserved
- TOV Batch: Compute M-R curves for multiple EOS simultaneously
- Radial Batch: Generate radial profiles for multiple EOS in parallel
- Radial Profiles – Generate detailed internal structure profiles with M-R context
- Target-Specific Profiles – Find stars by exact mass or radius values
- EOS Converter – Convert raw equation of state data into TOV code units (preserves all columns!)
- Clean Output – Organized export structure with CSV data and publication-ready plots
TOVExtravaganza/
├── tovextravaganza/ # Main package
│ ├── core/ # Core logic (reusable classes)
│ │ ├── eos.py # EOS interpolation
│ │ ├── tov_solver.py # TOV equation solver
│ │ ├── tidal_calculator.py # Tidal deformability
│ │ └── output_handlers.py # Output writers
│ ├── cli/ # Command-line tools
│ │ ├── tov.py # TOV solver CLI
│ │ ├── radial.py # Radial profiler CLI
│ │ └── converter.py # EOS converter CLI
│ └── utils/ # Utilities
│ ├── wizard.py # Interactive wizard
│ ├── demo.py # Demo file downloader
│ └── help_command.py # Help command
│
├── inputRaw/ # Raw EOS data files
├── inputCode/ # Converted EOS (code units)
│
├── export/ # All output goes here!
│ ├── stars/ # TOV + Tidal results
│ │ ├── csv/ # M-R + Tidal data
│ │ └── plots/ # M-R curves, Λ(M), k₂(M)
│ └── radial_profiles/ # Internal structure
│ ├── json/ # Detailed radial data
│ └── plots/ # M(r) and p(r) plots
│
└── README.md # This file
Global Install:
pip install tovextravaganzaOr in a Virtual Environment (Recommended):
python -m venv tovenv
source tovenv/bin/activate # Linux/Mac, or tovenv\Scripts\activate on Windows
pip install tovextravaganza
⚠️ Important: If using a venv, activate it before using anytovxcommands!
This installs the package with console commands: tovx, tovx-radial, tovx-converter, tovx-wizard, tovx-demo, tovextravaganza
git clone https://github.com/PsiPhiDelta/TOVExtravaganza.git
cd TOVExtravaganza
pip install -e .The -e flag installs in editable mode - any code changes take effect immediately without reinstalling.
Perfect for first-time users! The wizard guides you through everything:
If installed via pip:
tovx-demo # Get example files
tovx-wizard # Run the wizardIf using source/cloned repository:
python -m tovextravaganza.tov_wizardThe wizard will:
- 🔍 Auto-detect your EOS files
- ❓ Ask simple questions (no expertise needed!)
- 🚀 Run everything for you
- 📊 Show you exactly where results are
- 🎉 Celebrate your success!
If installed via pip:
tovx-demo # Get example files
tovx inputCode/hsdd2.csv # Compute M-R + Tidal
tovx-radial inputCode/hsdd2.csv -M 1.4 # Radial profile for 1.4 M☉
tovx-converter # Convert EOS unitsIf using source/cloned repository:
python -m tovextravaganza.tov inputCode/hsdd2.csv
python -m tovextravaganza.radial inputCode/hsdd2.csv -M 1.4
python -m tovextravaganza.converterThat's it! Results appear in the export/ folder.
This tutorial shows the complete workflow from raw EOS data to publication-quality results using the HS(DD2) equation of state as an example.
First, download the demo EOS files:
# Via pip
tovx-demo
# From source
python -m tovextravaganza.utils.demoThis downloads example files including hsdd2.csv to both inputRaw/ and inputCode/ directories.
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.csvWhat happens:
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)
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 200Output:
- CSV:
export/stars/csv/hsdd2.csvcontaining:- Central pressure
p_c - Radius
R[km] - Mass
M_solar[M☉] - Tidal deformability
Lambda(dimensionless) - Love number
k2 - Automatic: All EOS columns at central pressure (
central_e,central_n,central_phase, etc.)
- Central pressure
- Plots:
export/stars/plots/hsdd2.pdf
Example plot:
The plot shows three panels:
- Left: Mass-Radius relationship
- Middle: Tidal deformability Λ(M) with GW170817 constraint
- Right: Love number k₂(M)
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.4What happens:
- Searches for the star closest to 1.4 M☉
- Computes full radial profile: M(r), p(r) at each radius point
- Automatically interpolates all EOS columns at each radial point: ε(r), n(r), μ(r), phase(r), etc.
- Saves all data to HDF5 format (or JSON if h5py not installed)
- 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:
Mass Profile:
Pressure Profile:
Each plot:
- Left Panel: Radial profile from center to surface
- Right Panel: Full M-R curve with ⭐ marking this star's position
Process multiple EOS files in parallel for high-throughput analysis.
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.
The batch files are included with tovx-demo:
tovx-demoThis 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/
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 6Parameters:
--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
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 6What 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☉
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 6What happens:
- Each EOS: Fast M_max search (50 coarse + 200 fine = 250 TOV solves)
- Finds M_max with precision < 0.01 M☉
- Computes full radial profile with automatic interpolation of all EOS columns at each radius:
- Numeric columns → interpolated
- String columns → nearest value
- Saves everything to HDF5 (or JSON) - complete radial data for post-processing
- Generates M(r) and p(r) plots with M-R context
Output:
- 6 HDF5 files in
export/radial_maxmass/*/json/*.h5with complete radial data - 12 plots (Mass and Pressure profiles for each EOS)
- Total time: ~30 seconds for all 6 files in parallel!
Because all columns are stored, you can easily create custom plots like phase-color-coded visualizations:
Example M-R curves for all 6 EOS models (color-coded by central phase):
M-R curves from arXiv:2411.04064 showing how central phase changes with mass. Colors: Blue=Hadronic, Orange=2SC, Red=CFL. Line styles: Solid=CSC series, Dashed=RGNJL series. Maximum mass predictions: 1.94 - 2.19 M☉.
Example radial profile at M_max (RGNJL v0.70, M_max = 2.06 M☉, R = 12.44 km):
Phase-resolved internal structure at maximum mass showing Hadronic → 2SC → CFL transitions. Phase color-coding: Blue=Hadronic, Orange=2SC, Red=CFL. Units: Pressure & energy in MeV/fm³, number density in fm⁻³.
Via pip (easiest):
pip install tovextravaganza
tovx-demo # Get example files
tovx-wizard # Guided workflowFrom source:
git clone https://github.com/PsiPhiDelta/TOVExtravaganza.git
cd TOVExtravaganza
pip install -e .
tovx-wizardThat's it! The wizard does everything for you!
NEW! All TOVExtravaganza tools now support batch processing to analyze multiple EOS files simultaneously using parallel workers.
Process entire directories of EOS files with a single command:
- Converter Batch: Convert all raw EOS files to code units
- TOV Batch: Compute M-R curves for all EOS files
- Radial Batch: Generate radial profiles for all EOS files
Convert all raw EOS files in a directory with proper unit conversion.
Interactive Mode (prompts for columns and units if not provided):
# Via pip
tovx-converter --batch inputRaw/
# From source
python -m tovextravaganza.converter --batch inputRaw/Non-Interactive Mode (all parameters specified):
# Via pip
tovx-converter --batch inputRaw/ --pcol 2 --ecol 1 --system 3 # fm^-4
# From source
python -m tovextravaganza.converter --batch inputRaw/ --pcol 2 --ecol 3 --system 4 --workers 4Features:
- 🎯 Interactive prompts when parameters not provided
- 📁 Auto-creates
inputCode/Batch/for batch folders - ⚙️ Parallel processing for multiple files
- ✅ Preserves ALL additional columns (mu, n, temperature, phase labels, etc.)
- ✅ Maintains header tags with "(code_units)" annotations
- ✅ Reorders columns: p & e first (converted), then rest (preserved)
Example Output:
======================================================================
BATCH CONVERTER MODE - oh boy oh boy!
======================================================================
Found 3 CSV files in inputRaw
Processing with 2 parallel workers
Processed 3 files in 0.60 seconds
✓ Successful: 3
csc.csv => 1042 lines (MeV^-4 => code)
hsdd2.csv => 401 lines (CGS => code)
test.csv => 500 lines (Already code)
======================================================================
Compute M-R curves and tidal deformability for all EOS files in parallel.
Via pip:
# Process all CSV files in a directory
tovx --batch inputCode/
# Specify number of workers and stars
tovx --batch inputCode/ --workers 4 -n 500From source:
python -m tovextravaganza.tov --batch inputCode/ --workers 8 -n 200Example Output:
======================================================================
BATCH PROCESSING MODE - oh boy oh boy!
======================================================================
Found 3 CSV files in inputCode
Processing with 24 parallel workers
Processed 3 files in 16.15 seconds
✓ Successful: 3
csc => 149 solutions, Max M = 1.1186 Msun
hsdd2 => 151 solutions, Max M = 2.4229 Msun
test => 140 solutions, Max M = 1.8730 Msun
======================================================================
Generate radial profiles for all EOS files in parallel.
Via pip:
# Process all files in a directory
tovx-radial --batch inputCode/
# Custom number of profiles and workers
tovx-radial --batch inputCode/ -n 10 --workers 4From source:
python -m tovextravaganza.radial --batch inputCode/ -n 5 --workers 2Output Structure:
export/radial_profiles/
├── csc/
│ ├── json/
│ └── plots/
├── hsdd2/
│ ├── json/
│ └── plots/
└── test/
├── json/
└── plots/
- Parallel Processing: Uses all CPU cores by default (configurable with
--workers) - Organized Output: Each EOS gets its own folder (for radial profiles)
All batch modes support:
--batch <directory>: Directory containing CSV files--workers <N>: Number of parallel workers (default: CPU count)-o, --output <dir>: Output directory-n, --num-stars <N>: Number of stars/profiles (TOV & radial)
# Step 1: Convert all raw EOS files to code units
tovx-converter --batch inputRaw/ --system 2 --workers 4
# Step 2: Compute M-R sequences for all converted EOS
tovx --batch inputCode/ -n 200 --workers 8
# Step 3: Generate radial profiles for all EOS
tovx-radial --batch inputCode/ -n 10 --workers 8The main workhorse. Solves TOV equations and computes tidal properties for a sequence of neutron stars.
Via pip:
tovx inputCode/hsdd2.csv # 200 stars (default)
tovx inputCode/test.csv -n 500 # 500 starsFrom source:
python -m tovextravaganza.tov inputCode/hsdd2.csv
python -m tovextravaganza.tov inputCode/test.csv -n 500Via pip:
tovx inputCode/hsdd2.csv -n 1000 --dr 0.0001 --quiet --no-showFrom source:
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)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)
For HS(DD2) EOS:
- Maximum Mass: ~2.42 M☉
- Λ @ 1.4 M☉: ~705 (dimensionless)
- Radius @ 1.4 M☉: ~13.26 km
Get detailed profiles of mass, pressure, and energy density from center to surface.
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.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☉)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 profilesHDF5 (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]orpip install h5py
Fallback JSON: export/radial_profiles/json/<eos_name>.json
- Used if h5py not installed
- Human-readable but large files
{
"stars": [
{
"p_c": 0.001,
"R": 12.34,
"M": 0.543,
"radial_data": {
"r": [0.0, 0.001, 0.002, ...],
"M": [0.0, 0.0001, 0.0003, ...],
"p": [0.001, 0.0009, 0.0008, ...],
"e": [0.05, 0.049, 0.048, ...]
}
}
]
}Plots: export/radial_profiles/plots/
Mass/mass_profile_N.pdf– M(r) vs rPressure/pressure_profile_N.pdf– p(r) vs r
Sick of unit conversion? I was too. This tool converts raw EOS data into TOV code units.
Via pip:
tovx-converterFrom source:
python -m tovextravaganza.converterThe script will guide you through:
- Selecting input file from
inputRaw/ - Specifying if the file has a header
- Identifying pressure and energy density columns
- Choosing the unit system (MeV fm⁻³, CGS, etc.)
Via pip:
tovx-converter <input_file> <pcol> <ecol> <system> [output_file]From source:
python -m tovextravaganza.converter <input_file> <pcol> <ecol> <system> [output_file]Example:
# 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.csvParameters:
<input_file>: Filename ininputRaw/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, ...]
| System | Pressure Units | Energy Density Units |
|---|---|---|
| 0 | Code units | Code units |
| 1 | MeV⁻⁴ | MeV⁻⁴ |
| 2 | MeV·fm⁻³ | MeV·fm⁻³ |
| 3 | fm⁻⁴ | fm⁻⁴ |
| 4 | CGS (dyn/cm²) | CGS (erg/cm³) |
The Tolman-Oppenheimer-Volkoff equations describe hydrostatic equilibrium in general relativity:
dM/dr = 4πr²ε(r)
dp/dr = -(ε + p)(M + 4πr³p) / (r(r - 2M))
Solved in dimensionless "code units" where G = c = M☉ = 1.
The dimensionless tidal deformability Λ characterizes how a neutron star deforms under tidal forces:
Λ = (2/3) k₂ (c²R/GM)⁵
where k₂ is the second Love number, obtained by solving a coupled ODE system with TOV.
We solve a coupled 4-variable ODE system simultaneously with TOV:
dM/dr = 4πr²ε
dp/dr = -(ε + p)(M + 4πr³p) / (r(r - 2M))
dH/dr = β
dβ/dr = (2H/F₁)[-2π(5ε + 9p + f(ε+p)) + 3/r² + (2/F₁)(M/r² + 4πrp)²] + (2β/rF₁)[-1 + M/r + 2πr²(ε-p)]
where:
H(r)is the metric perturbation functionβ(r) = dH/dris integrated explicitly for numerical stabilityF₁ = 1 - 2M/ris the metric factorf = dε/dpis the EOS stiffness (precomputed using centered differences)
The Love number k₂ is then extracted at the surface (r = R):
k₂ = (8/5) C⁵ (1-2C)² [2C(y_R - 1) - y_R + 2] / {2C[4(y_R + 1)C⁴ + (6y_R - 4)C³ + (26 - 22y_R)C² + 3(5y_R - 8)C - 3y_R + 6] - 3(1-2C)²[2C(y_R - 1) - y_R + 2]ln(1-2C)}
where C = GM/(c²R) is the compactness and y_R = y(R).
Using HS(DD2) EOS, we compute 200 neutron star configurations:
python -m tovextravaganza.tov inputCode/hsdd2.csvResult: The M-R curve shows:
- Stable branch reaching M_max ≈ 2.42 M☉
- Typical 1.4 M☉ star has R ≈ 13.26 km
- Tidal deformability Λ(1.4 M☉) ≈ 705
For a 1.4 M☉ star:
python -m tovextravaganza.radial inputCode/hsdd2.csv -n 10Result: Radial profiles reveal:
- Central pressure: ~10¹⁵ g/cm³
- Pressure drops by ~6 orders of magnitude to surface
- Mass accumulates mostly in inner 10 km
All calculations use geometric units where G = c = 1:
- Radius: km
- Mass: km (geometric units, where 1 M☉ = 1.4766 km)
- Pressure: dimensionless code units
- Energy density: dimensionless code units
- tov.py: Converts M to M☉ in output CSV and plots
- radial.py: Shows M(r) in M☉, p(r) in MeV/fm³, r in km
- M [M☉] = M [km] / 1.4766
- p [MeV/fm³] = p [code] / 1.32379×10⁻⁶
- ε [MeV/fm³] = ε [code] / 1.32379×10⁻⁶
- ODE Integration:
scipy.integrate.odeintwith rtol=1e-12, atol=1e-14 - EOS Interpolation: Piecewise-linear
- Boundary conditions: Start integration at r=1e-5 to avoid r=0 singularity
The code automatically filters out unphysical solutions:
- Stars that hit maximum radius (R = 100 km)
- Low-mass configurations (M < 0.05 M☉)
CSV format, no header, columns: p, e, ...
0.00010000,0.00050000
0.00012000,0.00058000
...
Header row with columns: p_c, R, M_code, M_solar, Lambda, k2
p_c,R,M_code,M_solar,Lambda,k2
0.00010000,12.34,0.123,0.543,789.12,0.098
...
Structured JSON with full radial arrays for each star.
| Argument | Type | Default | Description |
|---|---|---|---|
input |
positional | required | Input EOS file path (e.g., inputCode/hsdd2.csv) |
-n, --num-stars |
int | 200 | Number of stars to compute across central pressure range |
-o, --output |
str | export/stars | Output folder for CSV and plots |
--dr |
float | 0.0005 | Radial step size for integration [km] |
--rmax |
float | 100.0 | Maximum radius before integration stops [km] |
--rmax-plot |
float | 20.0 | Maximum radius for plot x-axis [km] (data not cropped) |
--timeout |
float | 10.0 | Timeout per star calculation [seconds] (0 = no timeout) |
-q, --quiet |
flag | False | Suppress per-star output |
--no-plot |
flag | False | Skip plotting entirely |
--no-show |
flag | False | Don't display plot window (still saves to file) |
--save-png |
flag | False | Also save PNG versions of plots (default: PDF only) |
-b, --batch |
str | None | Batch mode: process all CSV files in specified directory |
-w, --workers |
int | CPU count | Number of parallel workers for batch mode |
Example:
tovx inputCode/hsdd2.csv -n 500 --rmax-plot 15 --timeout 20| Argument | Type | Default | Description |
|---|---|---|---|
input |
positional | required | Input EOS file path (e.g., inputCode/hsdd2.csv) |
-n, --num-stars |
int | 10 | Number of profiles to generate (evenly spaced in mass) |
-o, --output |
str | export/radial_profiles | Output folder for HDF5/JSON and plots |
-M, --mass |
float | None | Generate profile at this mass [M☉] (can use multiple times) |
-R, --radius |
float | None | Generate profile at this radius [km] (can use multiple times) |
--max-mass |
flag | False | Generate profile at M_max with precision < 0.001 M☉ |
--rmax-plot |
float | 20.0 | Maximum radius for M-R plot x-axis [km] (data not cropped) |
--timeout |
float | 10.0 | Timeout per star calculation [seconds] (0 = no timeout) |
--save-png |
flag | False | Also save PNG versions of plots (default: PDF only) |
-b, --batch |
str | None | Batch mode: process all CSV files in specified directory |
-w, --workers |
int | CPU count | Number of parallel workers for batch mode |
Example:
tovx-radial inputCode/hsdd2.csv -M 1.4 -M 2.0 --max-mass
tovx-radial --batch inputCode/Batch/ --max-mass --timeout 60| Argument | Type | Default | Description |
|---|---|---|---|
-b, --batch |
str | required | Batch mode: convert all CSV files in specified directory |
-p, --pcol |
int | None | Pressure column number (1-based, prompted if not provided) |
-e, --ecol |
int | None | Energy density column number (1-based, prompted if not provided) |
-s, --system |
int | None | Unit system: 0=code, 1=MeV⁻⁴, 2=MeV·fm⁻³, 3=fm⁻⁴, 4=CGS |
-o, --output |
str | inputCode | Output directory (auto-creates inputCode/Batch/ for batch) |
--header |
flag | True | Input files have header row (default) |
--no-header |
flag | False | Input files do NOT have header row |
-w, --workers |
int | CPU count | Number of parallel workers |
Unit System Reference:
- 0: Code units (no conversion)
- 1: MeV⁻⁴ → multiply by 1.32379×10⁻⁶
- 2: MeV·fm⁻³ → divide by 1.32379×10⁻⁶
- 3: fm⁻⁴ → multiply by (197.33 MeV·fm)⁻⁴ × 1.32379×10⁻⁶
- 4: CGS → multiply by G×c⁻⁴ (for p, ε in g/cm³)
Example:
tovx-converter --batch inputRaw/Batch/ -p 2 -e 1 -s 3
tovx-converter --batch inputRaw/ -s 2 --no-headerProblem: ValueError: not enough values to unpack
- Solution: Check that your EOS file has at least 2 columns (p, e)
Problem: ODEintWarning: Excess work done on this call
- Solution: Reduce
--dror check for discontinuities in your EOS
Problem: All masses are zero
- Solution: Your EOS might be too soft or in wrong units. Run
converter.pyfirst.
Problem: UnicodeEncodeError in terminal output
- Solution: Set environment variable:
PYTHONIOENCODING=utf-8
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please maintain the code style and add tests where appropriate.
- Tolman (1939): Static Solutions of Einstein's Field Equations
- Oppenheimer & Volkoff (1939): On Massive Neutron Cores
- Damour & Nagar (2009): Relativistic tidal properties of neutron stars
- Abbott et al. (2017): GW170817: Observation of Gravitational Waves from a Binary Neutron Star Inspiral
- CompOSE: https://compose.obspm.fr/
- stellarcollapse.org: Comprehensive EOS tables
- RG-NJL EoS Tables: Renormalization Group-consistent NJL model with color-superconducting quark matter (2SC and CFL phases) - https://github.com/marcohof/RG-NJL-EoS-tables
Author: Hosein Gholami
Website: hoseingholami.com
Email: [email protected]
GitHub: TOVExtravaganza
Questions? Suggestions? Found a bug? Don't hesitate to reach out or open an issue!
This project is licensed under the MIT License. See LICENSE for details.
If you use TOV Extravaganza in your research, please cite this repository and our work on arXiv:
@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}
}
@article{Gholami:2024csc,
author = "Gholami, Hosein and Rather, Ishfaq Ahmad and Hofmann, Marco and Buballa, Michael and Schaffner-Bielich, J{\"u}rgen",
title = "{Astrophysical constraints on color-superconducting phases in compact stars within the RG-consistent NJL model}",
eprint = "2411.04064",
archivePrefix = "arXiv",
primaryClass = "hep-ph",
month = "11",
year = "2024"
}arXiv: 2411.04064
Thanks to the astrophysics and gravitational wave communities for making neutron star science accessible and exciting.
Oh boy oh boy! May your neutron stars be massive and your convergence ever stable! 🌟
Built with Python, NumPy, SciPy, and a healthy dose of enthusiasm for compact objects.
neutron-star neutron-stars tov tov-equation tov-equations tidal-deformability gravitational-waves astrophysics equation-of-state eos python-physics astronomy compact-objects GW170817 nuclear-astrophysics nuclear-physics mass-radius love-number relativistic-stars color-superconductivity superconductivity csc cfl quark-matter dense-matter phase-transitions qcd binary-neutron-stars ligo virgo general-relativity stellar-structure computational-physics scientific-computing