YAML configuration reference

YAML configuration reference#

This page is the authoritative reference for all supported YAML configuration options in the JESTER inference system. When you add or change configuration fields, update this file by hand to keep it accurate.

Overview#

JESTER uses YAML configuration files validated by Pydantic models (see InferenceConfig). This reference documents every supported field, its type, default value, and purpose. For a worked example from start to finish, see the Quick start guide. For a conceptual explanation of the full inference pipeline, see Inference workflow.

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. For a conceptual overview of all available EOS models, see EOS models. Each model transforms a set of physically motivated parameters into a pressure–density relation that is then fed to the TOV solver.

Metamodel#

The metamodel parametrizes the EOS using nuclear empirical parameters (NEPs) around nuclear saturation density. For the physical motivation and parameter definitions, see Metamodel. The corresponding Python class is MetaModel_EOS_model. The Pydantic config schema is MetamodelEOSConfig.

Metamodel CSE#

The metamodel with speed-of-sound extension (CSE) replaces the metamodel above a breakdown density with a flexible speed-of-sound parametrization, allowing for more freedom at high densities. For the physical motivation and parameter definitions, see Metamodel + CSE. The corresponding Python class is MetaModel_with_CSE_EOS_model. The Pydantic config schema is MetamodelCSEEOSConfig.

Metamodel PeakCSE#

The metamodel with peak speed-of-sound extension (PeakCSE) is a variant of the CSE parametrization that models a peak feature in the speed of sound at high densities. The corresponding Python class is MetaModel_with_PeakCSE_EOS_model. The Pydantic config schema is MetamodelPeakCSEEOSConfig.

Spectral#

The spectral decomposition parametrizes the adiabatic index as a function of pressure using a series of basis functions, following Lindblom (2010). It is compatible with LALSimulation for GW analysis. For the physical motivation and parameter definitions, see Spectral decomposition. The corresponding Python class is SpectralDecomposition_EOS_model. The Pydantic config schema is SpectralEOSConfig.

TOV configuration#

The tov section configures the Tolman–Oppenheimer–Volkoff (TOV) equation solver used to compute neutron star structure (mass, radius, tidal deformability). For a conceptual overview of all available solvers, see TOV solvers. The Pydantic base schema is BaseTOVConfig.

Three solver types are supported: "gr" (standard GR), "anisotropy" (phenomenological parametrizations to include pressure anisotropy), and "scalar_tensor" (scalar-tensor gravity). All solvers share the base fields min_nsat_TOV, ndat_TOV, and nb_masses; the beyond-GR solvers additionally require theory parameters that must be included in the prior file.

General Relativity#

The standard GR TOV solver integrates the Tolman–Oppenheimer–Volkoff equations in full General Relativity. It requires no additional theory parameters. The corresponding Python class is GRTOVSolver. The Pydantic config schema is GRTOVConfig.

Pressure anisotropy#

The anisotropy solver extends the standard TOV equations with phenomenological beyond-GR corrections through an additional sigma term in the pressure gradient equation. For the underlying physics, see Pressure anisotropy. The corresponding Python class is AnisotropyTOVSolver.

Anisotropy TOV Solver configuration

tov:
  type: "anisotropy"  # TOV solver type
  min_nsat_TOV: 0.75  # Minimum central density for TOV integration (in units of n_sat)
  ndat_TOV: 100       # Number of data points for TOV integration
  nb_masses: 100      # Number of masses for M-R-Λ family construction

Field Details:

type (str) - Must be "anisotropy" for this solver
min_nsat_TOV (float, default: 0.75) - Minimum central density for TOV integration in units of saturation density
ndat_TOV (int, default: 100) - Number of data points for TOV integration
nb_masses (int, default: 100) - Number of masses to sample when constructing the M-R-Λ family

Required prior parameters:

The following theory parameters must be included in the .prior file:

Parameter	Description
`lambda_BL`	Bowers–Liang coupling constant
`lambda_DY`	Doneva–Yazadjiev (Horvat et al.) coupling constant
`lambda_HB`	Herrera–Barreto (Cosenza et al.) coupling constant
`gamma`	Post-Newtonian gamma coupling
`alpha`	Post-Newtonian alpha coupling
`beta`	Post-Newtonian beta coupling

Any subset of these parameters may be sampled; those omitted default to the GR limit (zero). Setting all coupling constants to zero recovers standard GR.

Prior configuration#

Specify prior distributions for EOS parameters using a .prior specification file. The prior file uses a Python-based syntax (bilby-style) and is parsed by parse_prior_file() into a CombinePrior object. The Pydantic config schema is PriorConfig.

Likelihoods#

The likelihoods section specifies observational constraints to include in the inference. Multiple likelihoods can be combined for multi-messenger analysis; they are assembled into a CombinedLikelihood. For a conceptual overview of all available likelihoods and their physical motivation, see Likelihood constraints.

Gravitational wave observations#

Constrain the EOS using gravitational wave observations of binary neutron star mergers. For the physics and methodology, see Gravitational wave constraints from binary neutron star mergers.

Standard GW likelihood (presampled)#

Standard GW Likelihood (presampled)

- type: "gw"
  enabled: true
  events:                       # List of GW events (see GWEventConfig below)
    - name: "GW170817"
      nf_model_dir: "./NFs/GW170817"
  penalty_value: 0.0            # Log-likelihood penalty for M > M_TOV (default: 0.0)
  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. See GWLikelihood for the full API. For information on training flows from bilby results or NPZ files, see Training normalizing flows.

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

NICER observations#

Constrain the mass–radius relation using NICER X-ray timing observations of millisecond pulsars. For the physics and methodology, see NICER constraints.

NICER flow likelihood (default)#

NICER KDE likelihood (legacy)#

Radio pulsar observations#

Constrain neutron star masses using radio pulsar timing measurements. For the physics and methodology, see Radio timing constraints. The Python class is RadioTimingLikelihood.

Nuclear theory constraints#

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

ChiEFT likelihood#

Constrains the EOS at densities below ~2 \(n_\text{sat}\) using chiral effective field theory (ChiEFT) calculations. The likelihood checks that the predicted pressure–density relation falls within the ChiEFT uncertainty bands. For the physics and the specific bands used, see Chiral effective field theory (ChiEFT). The Python class is ChiEFTLikelihood.

REX likelihood#

Generic constraints#

Apply custom physics-motivated constraints on EOS and TOV observables. These are implemented as likelihoods that return large negative values (i.e., zero probability) when a constraint is violated, and zero otherwise. For the base class interface, see ConstraintEOSLikelihood.

EOS constraints#

TOV constraints#

Symmetry energy 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 backends with different strengths. For a conceptual comparison, see Samplers. The sampler base class is JesterSampler. All samplers produce a SamplerOutput with posterior samples, log-probabilities, and metadata. The base Pydantic schema is BaseSamplerConfig.

Sequential Monte Carlo with random walk#

BlackJAX SMC with adaptive tempering and Gaussian Random Walk kernel. Production-ready and recommended for most analyses. For a detailed explanation of the algorithm, see Sequential Monte Carlo (SMC). The Python class is BlackJAXSMCRandomWalkSampler. The Pydantic config schema is SMCRandomWalkSamplerConfig.

Nested sampling (BlackJAX NS-AW)#

BlackJAX nested sampling with acceptance walk for Bayesian evidence estimation and posterior sampling. For a detailed explanation of the algorithm, see Nested Sampling (NS-AW). The Python class is BlackJAXNSAWSampler. The Pydantic config schema is BlackJAXNSAWConfig.

FlowMC (normalizing flow MCMC)#

Normalizing flow-enhanced MCMC combining local MCMC proposals with global normalizing flow proposals. For a detailed explanation of the algorithm, see FlowMC. The Python class is FlowMCSampler. The Pydantic config schema is FlowMCSamplerConfig.

Sequential Monte Carlo with NUTS#

BlackJAX SMC with adaptive tempering and No-U-Turn Sampler (NUTS) kernel. EXPERIMENTAL — use with caution. For a detailed explanation of the SMC framework, see Sequential Monte Carlo (SMC). The Python class is BlackJAXSMCNUTSSampler. The Pydantic config schema is SMCNUTSSamplerConfig.

Data paths (optional)#

Override default data file locations for likelihoods.

Postprocessing#

Configure automatic plot generation and posterior analysis after inference completes. Results are stored in HDF5 format (see InferenceResult) and postprocessing reads directly from that file.

Complete examples#

Minimal configuration (prior-only)#

A miniam config showing how to sample from the prior distribution without observational constraints.

Advanced multi-messenger configuration#

Several full configurations are available in the examples directory in jester:

examples/inference/anisotropy: Using the metamodel+CSE equation of state and the anisotropy solver, with several of the likelihoods available.
examples/inference/blackjax-ns-aw: Examples of the nested sampler implemented in blackjax
examples/inference/flowmc: Examples of the flowMC sampler
examples/inference/mm_peakcse: Examples of the metamodel+CSE analysis
examples/inference/smc_random_walk: Examples of the SMC sampler with random walk kernel
examples/inference/spectral: Examples of the spectral EOS parameterization
examples/inference/spectral_reparam: Examples of the spectral EOS parameterization, after the reparametrization described in TODO: add the new docs page once it exists