YAML configuration reference

YAML configuration reference#

Auto-generated from Pydantic schemas - This document is the authoritative reference for all supported YAML configuration options.

Note

Auto-Generated File - Do Not Edit Manually This file is automatically generated from jesterTOV/inference/config/schema.py.

Do not modify this file directly! Your changes will be overwritten.

To update this reference:

Modify jesterTOV/inference/config/schema.py (Pydantic models)
Run: uv run python -m jesterTOV.inference.config.generate_yaml_reference

Overview#

The JESTER inference system uses YAML configuration files validated by Pydantic models. This reference documents every supported field, its type, default value, and purpose.

Run Options#

Control runtime behavior for validation, debugging, and random seed configuration.

EOS Configuration#

The eos section specifies which equation of state (EOS) parametrization to use.

Metamodel#

Metamodel EOS parametrization

Metamodel CSE#

Metamodel EOS parametrization with speed-of-sound extension above a breakdown density

Spectral (LALSuite-Compatible)#

Spectral decomposition parametrization compatible with LALSimulation for GW analysis.

TOV Configuration#

The tov section configures the Tolman-Oppenheimer-Volkoff equation solver used to compute neutron star structure (mass-radius-tidal deformability).

Prior Configuration#

Specify prior distributions for EOS parameters using a .prior specification file.

Likelihoods#

The likelihoods section specifies observational constraints to include in the inference. Multiple likelihoods can be combined for multi-messenger analysis.

Gravitational Wave Observations#

Constrain the EOS using gravitational wave observations of binary neutron star mergers.

Standard GW Likelihood (Presampled)#

Standard GW Likelihood (Presampled) (type: “gw”)

- type: "gw"
  enabled: true
  parameters:
    events: [{"name": "GW170817", "nf_model_dir": "./NFs/GW170817"}]  # List of GW events (see GWEventConfig below)
    N_masses_evaluation: 2000  # Number of mass samples to pre-sample (optional, default: 2000)
    N_masses_batch_size: 1000  # Batch size for processing (optional, default: 1000)
    seed: 42  # Random seed for mass sampling (optional, default: 42)

Field Details:

events (list[GWEventConfig]) - List of GW event configs (see GWEventConfig below). Each entry must have name. Three modes are supported:
- Pre-trained flow: set nf_model_dir to point to a trained flow, or omit it to use a built-in preset.
- From bilby result: set from_bilby_result to the path of a bilby HDF5 result file; jester will extract posterior samples and train a flow automatically before inference.
- From NPZ file: set from_npz_file to an existing .npz file with posterior samples; jester will train a flow directly from it, skipping the bilby extraction step.
penalty_value (float, default: 0.0) - Log-likelihood penalty for masses exceeding TOV maximum mass (default: 0.0, i.e. no penalty)
N_masses_evaluation (int, default: 2000) - Number of mass samples to pre-sample from the GW posterior
N_masses_batch_size (int, default: 1000) - Batch size for jax.lax.map processing of mass grid
seed (int, default: 42) - Random seed for mass pre-sampling from GW posterior

Description:

Default GW likelihood (presampled version): pre-samples masses from the GW posterior for efficient evaluation. Recommended for production use.

GWEventConfig fields (each entry in events):

Field	Type	Default	Description
`name`	str	required	Event name, e.g. `GW170817`
`nf_model_dir`	str\|null	null	Path to a pre-trained normalizing flow directory. Mutually exclusive with `from_bilby_result` and `from_npz_file`.
`from_bilby_result`	str\|null	null	Path to a bilby result `.hdf5` file. jester will extract posterior samples and train a flow automatically. Mutually exclusive with `nf_model_dir` and `from_npz_file`.
`from_npz_file`	str\|null	null	Path to an existing `.npz` file with posterior samples (`mass_1_source`, `mass_2_source`, `lambda_1`, `lambda_2`). jester will train a flow directly from this file, skipping bilby extraction. Mutually exclusive with `nf_model_dir` and `from_bilby_result`.
`flow_config`	str\|null	null	Path to a `FlowTrainingConfig` YAML file for custom flow training (only valid with `from_bilby_result` or `from_npz_file`).
`retrain_flow`	bool	false	Force re-training even if a cached flow exists (only valid with `from_bilby_result` or `from_npz_file`).

Examples:

# Pre-trained flow (preset):
events:
  - name: GW170817

# Pre-trained flow (custom path):
events:
  - name: GW170817
    nf_model_dir: ./my_flow

# From bilby result (auto-train):
events:
  - name: GW170817
    from_bilby_result: ./GW170817_result.hdf5

# From existing NPZ file (skip bilby extraction):
events:
  - name: GW170817
    from_npz_file: ./GW170817_posterior.npz

Resampled GW Likelihood (Legacy)#

X-ray Observations#

Constrain the mass-radius relation using NICER X-ray timing observations of millisecond pulsars.

NICER Flow Likelihood (DEFAULT)#

NICER KDE Likelihood (LEGACY)#

Radio Pulsar Observations#

Constrain neutron star masses using radio pulsar timing measurements.

Nuclear Theory Constraints#

Constrain the low-density EOS using nuclear theory calculations and laboratory measurements.

ChiEFT Likelihood#

REX Likelihood#

Generic Constraints#

Apply custom physics-motivated constraints on EOS and TOV observables.

EOS Constraints#

TOV Constraints#

Gamma Constraints#

Prior-Only Sampling#

Sample from the prior without applying observational constraints.

Samplers#

Choose a sampling algorithm for Bayesian inference. JESTER supports four production-ready samplers with different strengths.

FlowMC (Normalizing Flow MCMC)#

Normalizing flow-enhanced MCMC combining local MCMC proposals with global normalizing flow proposals.

Sequential Monte Carlo with Random Walk#

BlackJAX SMC with adaptive tempering and Gaussian Random Walk kernel. Production-ready and recommended for most analyses.

Sequential Monte Carlo with NUTS#

BlackJAX SMC with adaptive tempering and No-U-Turn Sampler (NUTS) kernel. EXPERIMENTAL - use with caution.

Nested Sampling (BlackJAX NS-AW)#

BlackJAX nested sampling with acceptance walk for Bayesian evidence estimation and posterior sampling.

Data Paths (Optional)#

Override default data file locations for likelihoods.

Postprocessing#

Configure automatic plot generation and posterior analysis after inference completes.

Complete Examples#

Minimal Configuration (Prior-Only)#

Sample from the prior distribution without observational constraints.

Multi-Messenger Configuration#

Combine gravitational wave, X-ray, radio, and nuclear theory constraints.

Spectral Parametrization (LALSuite-Compatible)#

Configuration using spectral decomposition for GW analysis workflows.

Validation Rules#

The configuration is validated using Pydantic. Common validation errors:

Document Status: Auto-generated Source: jesterTOV/inference/config/schema.py Generator: jesterTOV/inference/config/generate_yaml_reference.py

To regenerate this reference after modifying schema.py:

uv run python -m jesterTOV.inference.config.generate_yaml_reference