CompactObject

CompactObject is an open-source package designed to perform Bayesian inference on neutron star equation of state (EOS) constraints. It offers a comprehensive workflow that integrates astrophysical observations and nuclear measurements to explore the interior composition of neutron stars. The package is built to be user-friendly, easily extendable, and thoroughly documented, making it an essential tool for researchers in nuclear astrophysics.

We have a detailed documentation please check here: CompactObject Package Website

Please star this repository if you find it is helpful!

Table of Contents

• Core Functionality
• Papers
• Sample Citation
• Includes
• Installation
• Physics Notations
• License
• Contact
• Acknowledgments

Core Functionality

CompactObject offers a range of functionalities essential for constraining the EOS of neutron stars:

1. Equation of State (EOS) Generation

   • Utilizes multiple physics/meta models, including Relativistic Mean Field (RMF), strange star, quark star, polytrope, and speed of sound models, to generate neutron star EOS.
   • EOSgenerators Package

2. Tolman-Oppenheimer-Volkoff (TOV) Solver

   • Solves the TOV equations for a spherically symmetric compact object based on a given neutron star EOS.
   • TOVsolver Package

3. Bayesian Inference Workflow

   • Implements neutron star EOS inference using Nested Sampling.
   • Provide options for single machine users using MCMC sampling by emcee.
   • Integrates constraints from nuclear experiments, neutron star mass and/or radius observations (from X-ray timing and/or radio timing), and tidal measurements from gravitational wave detections.
   • InferenceWorkflow Package

Papers

Please consider cite the following papers if you use CompactObject in your research:

Package paper:

1. Huang, C., Malik, T., Cartaxo, J., et al. (2024). CompactObject: An open-source Python package for full-scope neutron star equation of state inference arXiv:2411.14615

2. Cartaxo, J., Huang, C., Malik, T., Sourav, S. , Yuan, W., Zhou, T., Liu, X., Providência, C., “Covariant Energy Density Functionals for Neutron Star Matter Equation of State Modeling: Cross-Comparison Analysis Using \texttt{CompactObject}”, The Astrophysical Journal Supplement Series, Volume 282, Number 2, https://iopscience.iop.org/article/10.3847/1538-4365/ae2310

Other papers:

1. Huang, C., Raaijmakers, G., Watts, A. L., Tolos, L., & Providência, C. (2024). Constraining fundamental nuclear physics parameters using neutron star mass-radius measurements I: Nucleonic models. Monthly Notices of the Royal Astronomical Society, 529. DOI:10.1093/mnras/stae844

2. Huang, C., & Zheng, X.-P. (2024). Bayesian Insights into post-Glitch Dynamics: Model comparison and parameter constraint from decades-long observation data of the Crab pulsar, Monthly Notices of the Royal Astronomical Society, Volume 542, Issue 4, October 2025, Pages 3198–3205, https://doi.org/10.1093/mnras/staf1415.

3. Huang, C., Sourav, S., Constraining first-order phase transition inside neutron stars with application of Bayesian techniques on PSR J0437-4715 NICER data, (2025), The Astrophysical Journal, Volume 983, Number 1, https://iopscience.iop.org/article/10.3847/1538-4357/adbca6

4. Huang, C., Equation of State Independent Determination on the Radius of a 1.4 $M_{\odot}$ Neutron Star Using Mass-Radius Measurements (2025), The Astrophysical Journal Letters, Volume 978, Number 1, https://iopscience.iop.org/article/10.3847/2041-8213/ad9f3c.

Sample Citation

"The inference conducted here relies on the framework in the CompactObject \cite{CompactObject} package\footnote{https://chunhuangphy.github.io/CompactObject/}. This is an open-source, comprehensive package designed to implement Bayesian constraints on the neutron star EOS. Other works based on this package include ..."

Includes

CompactObject includes the following components to facilitate neutron star EOS inference analysis:

1. EOS Output Validation Routine

   • Compute various type of EOS by different models
   • Checks the validity of EOS inputs.

2. Mass, Radius, and Tidal Deformability Calculator

   • Returns mass, radius, tidal deformability, by solve TOV equation, and computes the corresponding speed of sound.

3. Sample TOV Solver Notebook

   • Test_TOVsolver.ipynb
   • Demonstrates how to solve the TOV equation with a given EOS.

4. Sample EOS Generators Notebook

   • test_EOSgenerators.ipynb
   • Showcases all integrated EOS computations, including:
     • Polytrope
     • Speed of Sound Model
     • RMF Model
     • Strange Star Model
     • Quark Star Model

5. Sample Analysis and Tutorial Notebook

   • test_Inference.ipynb
   • Demonstrates the entire pipeline of Bayesian inference using supported EOS models, constructing priors and likelihoods, and the types of likelihoods supported in this project. Also provide a MCMC based emcee example for people don't have access to High Performance Computer. This is specifically focus on the RMF EOS, However, please check this notebook before all other notebook, since here we showcase all the likelihood
   • Other Inference pipline that using different EOS are
     • MIT bag inference
     • Strangeon Star inference
     • Polytrope inference

Note: Please review these notebooks before starting your own project to familiarize yourself with the coding routines.

Installation

Install the CompactObject-TOV package from PyPI in an isolated Python environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install CompactObject-TOV

For a Conda installation, clone the repository and create the supplied environment. This installs Python and the package dependencies with Conda before installing only the local CompactObject code with pip:

git clone https://github.com/ChunHuangPhy/CompactObject.git
cd CompactObject
conda env create --file environment.yml
conda activate CompactObject
python -m pip install --no-deps --no-build-isolation -e .

See the installation guide for notebook, development, and optional FastRMF dependencies.

NumbaMinpack is optional and only needed for the accelerated FastRMF solver. Its PyPI release can fail to build with newer CMake versions. If this happens, install it from the upstream GitHub source; the FastRMF installation instructions include the build prerequisites, direct GitHub and clone commands, and an import check. Run these commands in the same environment as CompactObject.

Running the Tests

From a source checkout:

python -m pip install -e ".[test]"
python -m pytest

The testing guide also documents Conda setup, individual test commands, and troubleshooting.

Importing the Package

• For EOS Computation:

  import EOSgenerators
  

• For TOV Solver:

  import TOVsolver
  

• For Bayesian Inference:

  import InferenceWorkflow
  

Physics Notations

1. Units:

   • CGS Units are used throughout the package.
   • Pressure (P): erg/cm³
   • Energy Density (ρ): g/cm³
   • Default Unit system any input in this package is follow the cgs unit

2. Unit Conventions:

   • Follow the unit system defined in the Unit Conversion notebook.
   • Basic Rules:
     1. If using a quantity with a unit, multiply by the unit during computations.
     2. If plotting or demonstrating values in a specific unit, divide accordingly.
   • Detailed guidelines can be found in the Unit Conversion documentation.

License

Distributed under the GNU GPL-3.0-or-later license. See LICENSE for more information.

(back to top)

Contact

• Chun Huang - chun.h@wustl.edu

Documentation Link: CompactObject Documentation

(back to top)

Acknowledgments

We would like to acknowledge the support of the Code/Astro workshop, which was instrumental in the development of this project. Special thanks to Professor Anna Watts, Dr. Geert Raaijmakers, and Jeannie Kuijper for their assistance with coding and providing foundational strategies to address the research challenges.

• Code Astro
• Choose an Open Source License
• Read Me Template

(back to top)