JESTER documentation

JAX-accelerated equation of state inference and TOV solvers

jester performs fast and accurate Bayesian inference on the neutron star equation of state (EOS) using GPU-accelerated TOV solvers and samplers through jax.

Try it out!

Try jester right away in your browser and infer the neutron star equation of state from GW170817 within 15 minutes — no installation required!

Want to run locally? Check the installation instructions below.

What’s in jester?

jester combines flexible EOS parametrizations with GPU-accelerated TOV solvers and modern Bayesian samplers. See the Overview guide for detailed explanations about what is implemented in the code.

🧮 EOS models

Parametrize the equation of state of neutron star matter

• Metamodel

• Metamodel + CSE

• Spectral expansion

⚙️ TOV solvers

Integrate neutron star structure equations

• General Relativity

• Pressure anisotropy

• Modified gravity theories

🔭 Likelihood constraints

Multi-messenger astronomical observations

• Nuclear experiments (chiEFT)

• Radio timing (mass measurements)

• NICER mass-radius

• Gravitational waves

📊 Samplers

GPU-accelerated Bayesian inference

• Sequential Monte Carlo

• Nested Sampling

• FlowMC (normalizing flows)

Curious for more?

• Check out the Constructing EOS and solving TOV equations to get familiar with using jester for generating EOSs and solving TOV equations.

• Get familiar with the Bayesian inference workflow, starting from the Quick start guide.

• Dive into the code itself in the API reference of jesterTOV

Installation

jester depends on a specific fork of blackjax for nested sampling support, which prevents publishing to PyPI. Instead, install the latest version by cloning the repository:

git clone https://github.com/nuclear-multimessenger-astronomy/jester

We recommend using uv for managing the Python environment and installing the package. Once uv is installed, create a virtual environment e.g. as follows:

uv venv --python=3.12            # Specify the Python version, if desired (optional)
source .venv/bin/activate        # Activate the virtual environment to access the installed dependencies

The package can then be installed directly or in editable mode in case you want to modify the code or contribute to the development of jester:

cd jester
uv pip install -e .             # Basic install for the core functionality (CPU-only)

Extra dependencies can be installed as follows:

uv pip install -e ".[cuda12]"   # For GPU support (fast sampling)
uv pip install -e ".[dev]"      # For developers (work on documentation, run tests,...)

Or using uv also as follows:

uv sync
uv sync --extra cuda12   # For GPU support (fast sampling)
uv sync --extra dev      # For developers (work on documentation, run tests,...)

To run Bayesian inference, make sure to install support for CUDA or upgrade jax according to the jax documentation page. This should work fine by specifying the appropriate extra (.[cuda12]) when installing with uv.

Having trouble? Check out the FAQ and common pitfalls.

Contents

Overview

• EOS models
  • Crust
  • Metamodel
  • Metamodel + CSE
  • Metamodel + peakCSE
  • Spectral Decomposition
• TOV solvers
  • General Relativity
  • Pressure Anisotropy
  • Modified Gravity
• Likelihood constraints
  • Base class
  • Chiral effective field theory (ChiEFT)
  • Radio Timing
  • NICER
  • Gravitational Waves
• Samplers
  • Sequential Monte Carlo (SMC)
  • Nested Sampling (NS-AW)
  • FlowMC

Basic examples

• Constructing EOS and solving TOV equations
  • Equation of state
  • TOV solver
• Automatic differentiation
  • EOS and TOV setup
  • Score functions
• Optimizer setup
  • Runs
• Closing remarks
• Prior predictive checks for EOS models
  • Words of caution
  • MetaModel + CSE
  • MetaModel + peakCSE
  • Spectral (reparametrized)

Bayesian inference guide

• Quick start
  • Running your first inference
  • Result
  • Postprocessing
  • Next steps
  • Running inference in the cloud with Google Colab
• YAML configuration reference
  • Overview
  • Run options
  • EOS configuration
  • TOV configuration
  • Prior configuration
  • Likelihoods
  • Samplers
  • Data paths (optional)
  • Postprocessing
  • Complete examples
• Inference workflow
  • 1. Configuration loading
  • 2. Prior setup
  • 3. Transform setup
  • 4. GW flow preparation
  • 5. Likelihood setup
  • 6. Sampler setup
  • 7. Sampling
  • 8. EOS quantity generation
  • 9. Saving results
  • 10. Postprocessing
• Analyzing a binary neutron star signal
  • 1. Get GW posteriors
  • 2. GW posterior postprocessing: training a normalizing flow
  • 3. Running jester
• Training normalizing flows
  • Flow class
  • Flow configuration
  • Starting the training
  • Training output
  • Available flow types
• Inspecting inference results

API reference

• jesterTOV
  • jesterTOV.eos module
  • jesterTOV.tov module
  • jesterTOV.inference module
  • jesterTOV.utils module

Developer guide

• FAQ and common pitfalls
  • Installation and GPU setup
  • Configuration
  • JAX-specific pitfalls
  • Numerical issues
  • Sphinx documentation build
• Adding a new EOS model
  • Architecture overview
  • Step 1: Create EOS class
  • Step 2: Update configuration schema
  • Step 3: Register in transform factory
  • Step 4: Create prior file
  • Step 5: Write tests
  • Step 6: Create example configuration
  • Step 7: Documentation
  • Checklist
  • Common pitfalls
  • Need help?
• Adding a new TOV solver
  • Architecture overview
  • Step 1: Create TOV solver class
  • Step 2: Update Configuration schema
  • Step 3: Register in Transform factory
  • Step 4: Create Prior file
  • Step 5: Write tests
  • Step 6: Create example configuration
  • Step 7: Documentation
  • Checklist
  • Common Pitfalls
  • Need Help?
• Adding a new likelihood
  • Architecture overview
  • Step 1: Create Likelihood class
  • Step 2 (optional): Add data loading function
  • Step 3: Update Configuration schema
  • Step 4: Register in Likelihood factory
  • Step 5: Write tests
  • Step 6: Create example configuration
  • Step 7: Documentation
  • Checklist
  • Common pitfalls
  • Advanced: resampling during likelihood call
  • Need Help?
• Documentation guide
  • Overview
  • Keeping Documentation in Sync
  • YAML Reference Structure
  • Documentation Structure
  • Testing Documentation
  • Version Control
  • Documentation Review

Miscellaneous

• Citing Jester
  • Jester methods papers
  • Additional methods papers
  • List of papers that used jester
• Acknowledgements

Indices and tables

• Index

• Module Index

• Search Page