SkillAgentSearch skills...

TOVExtravaganza

Python toolkit for solving the Tolman-Oppenheimer-Volkoff equations and analyzing neutron star properties. Includes EOS conversion, mass-radius analysis, and radial profile generation.

GenerateConvertImprove

Install / Use

/learn @PsiPhiDelta/TOVExtravaganza
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

🌟 TOV Extravaganza

Python Toolkit for Neutron Star Physics: Solve TOV Equations, Calculate Tidal Deformability, and Explore Neutron Star Properties

License: MIT PyPI version Python 3.7+ arXiv Downloads

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

Features

  • 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

📂 Project Structure

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

🚀 Quick Start

Installation

Option 1: Install from PyPI (Easiest!)

Global Install:

pip install tovextravaganza

Or 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 any tovx commands!

This installs the package with console commands: tovx, tovx-radial, tovx-converter, tovx-wizard, tovx-demo, tovextravaganza

Option 2: Install from Source (For Development)

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.

Workflow 1: Interactive Wizard (Easiest - Recommended!)

Perfect for first-time users! The wizard guides you through everything:

If installed via pip:

tovx-demo        # Get example files
tovx-wizard      # Run the wizard

If using source/cloned repository:

python -m tovextravaganza.tov_wizard

The 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!

Workflow 2: Command-Line (Advanced)

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 units

If using source/cloned repository:

python -m tovextravaganza.tov inputCode/hsdd2.csv
python -m tovextravaganza.radial inputCode/hsdd2.csv -M 1.4
python -m tovextravaganza.converter

That's it! Results appear in the export/ folder.

📚 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

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

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
    • Automatic: All EOS columns at central pressure (central_e, central_n, central_phase, etc.)
  • Plots: export/stars/plots/hsdd2.pdf

Example plot:

Mass-Radius Plot

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:

Mass Profile:

Mass Profile

Pressure 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

🚀 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: Pres

PsiPhiDelta

View profile

View on GitHub
GitHub Stars8
CategoryDevelopment
Updated11d ago
Forks1
PsiPhiDelta/TOVExtravaganza

Languages

Python

Security Score

90/100

Audited on Mar 24, 2026

No findings