"""Pydantic models for likelihood configuration."""
import warnings
from typing import Literal, Union, Annotated
from pydantic import (
Field,
field_validator,
model_validator,
ConfigDict,
Discriminator,
)
from jesterTOV.logging_config import get_logger
from ._base import JesterBaseModel
logger = get_logger("jester")
class BaseLikelihoodConfig(JesterBaseModel):
"""Base configuration for all likelihood types."""
model_config = ConfigDict(extra="forbid")
enabled: bool = Field(
default=True, description="Whether this likelihood is enabled in the analysis"
)
class GWEventConfig(JesterBaseModel):
r"""Configuration for a single GW event in the likelihood.
Three modes are supported:
**Mode 1 — pre-trained flow** (default):
Provide ``nf_model_dir`` or omit it to use a built-in preset.
**Mode 2 — from bilby result**:
Provide ``from_bilby_result`` to extract samples from a bilby HDF5 file
and train the flow automatically when running
:func:`~jesterTOV.inference.run_inference.main`.
**Mode 3 — from NPZ file**:
Provide ``from_npz_file`` to train the flow directly from an existing
NPZ file (e.g. one previously produced by the ``jester_extract_gw_posterior_bilby``
CLI tool), skipping the bilby extraction step.
``nf_model_dir`` is mutually exclusive with both ``from_bilby_result`` and
``from_npz_file``. ``from_bilby_result`` and ``from_npz_file`` are also
mutually exclusive with each other. ``flow_config`` and ``retrain_flow``
are valid in both Mode 2 and Mode 3.
Examples
--------
Pre-trained flow (using preset):
.. code-block:: yaml
events:
- name: GW170817
Pre-trained flow (custom path):
.. code-block:: yaml
events:
- name: GW170817
nf_model_dir: ./my_flow
From bilby result:
.. code-block:: yaml
events:
- name: GW170817
from_bilby_result: ./GW170817_result.hdf5
flow_config: ./flow_config.yaml # optional
retrain_flow: false # optional
From NPZ file:
.. code-block:: yaml
events:
- name: GW170817
from_npz_file: ./GW170817_posterior.npz
flow_config: ./flow_config.yaml # optional
retrain_flow: false # optional
"""
model_config = ConfigDict(extra="forbid")
name: str = Field(description="GW event name (e.g. 'GW170817')")
nf_model_dir: str | None = Field(
default=None,
description=(
"Path to a pre-trained normalizing flow model directory. "
"If omitted, uses a built-in preset for known events."
),
)
from_bilby_result: str | None = Field(
default=None,
description=(
"Path to a bilby result HDF5 file. When set, jester will extract "
"posterior samples and train a normalizing flow automatically before "
"running inference."
),
)
from_npz_file: str | None = Field(
default=None,
description=(
"Path to an NPZ file with posterior samples "
"(mass_1_source, mass_2_source, lambda_1, lambda_2). "
"When set, jester will train a normalizing flow directly from this "
"file before running inference, skipping the bilby extraction step."
),
)
flow_config: str | None = Field(
default=None,
description=(
"Path to a YAML file with FlowTrainingConfig overrides. "
"Only meaningful when 'from_bilby_result' or 'from_npz_file' is set."
),
)
retrain_flow: bool = Field(
default=False,
description=(
"Force retraining even if a cached flow already exists. "
"Only meaningful when 'from_bilby_result' or 'from_npz_file' is set."
),
)
@model_validator(mode="after")
def _validate_mode_consistency(self) -> "GWEventConfig":
"""Ensure that the three source modes are not mixed."""
has_pretrained = self.nf_model_dir is not None
has_bilby = self.from_bilby_result is not None
has_npz = self.from_npz_file is not None
if has_pretrained and has_bilby:
raise ValueError(
"Cannot specify both 'from_bilby_result' and 'nf_model_dir'. "
"Use 'from_bilby_result' to extract samples and train a flow, "
"or 'nf_model_dir' to point to an already-trained flow."
)
if has_pretrained and has_npz:
raise ValueError(
"Cannot specify both 'from_npz_file' and 'nf_model_dir'. "
"Use 'from_npz_file' to train a flow from an existing NPZ, "
"or 'nf_model_dir' to point to an already-trained flow."
)
if has_bilby and has_npz:
raise ValueError(
"Cannot specify both 'from_bilby_result' and 'from_npz_file'. "
"Use 'from_bilby_result' to extract samples from a bilby HDF5, "
"or 'from_npz_file' to start directly from an existing NPZ file."
)
# flow_config and retrain_flow only make sense when training a flow
needs_training = has_bilby or has_npz
if not needs_training:
if self.flow_config is not None:
raise ValueError(
"'flow_config' is only valid when 'from_bilby_result' or "
"'from_npz_file' is provided."
)
if self.retrain_flow:
raise ValueError(
"'retrain_flow' is only valid when 'from_bilby_result' or "
"'from_npz_file' is provided."
)
return self
class GWLikelihoodConfig(BaseLikelihoodConfig):
r"""Gravitational wave likelihood configuration (presampled version).
This is the default GW likelihood that pre-samples masses from the
GW posterior for efficient evaluation during MCMC sampling.
Each entry in ``events`` is a :class:`GWEventConfig` that supports three
modes: using a pre-trained normalizing flow (default), automatically
extracting samples from a bilby result file and training the flow, or
training the flow directly from an existing NPZ file.
Examples
--------
.. code-block:: yaml
- type: "gw"
enabled: true
events:
- name: "GW170817"
nf_model_dir: "./NFs/GW170817"
N_masses_evaluation: 2000
"""
type: Literal["gw"] = Field(default="gw", description="Likelihood type identifier")
events: list[GWEventConfig] = Field(
description=(
"List of GW events to include. Each event must have 'name'. "
"Optional 'nf_model_dir' specifies path to normalizing flow model; "
"if omitted, uses preset paths based on event name. "
"Alternatively, set 'from_bilby_result' to train a flow automatically."
),
min_length=1,
)
@field_validator("events")
@classmethod
def _validate_unique_event_names(
cls, v: list[GWEventConfig]
) -> list[GWEventConfig]:
names = [event.name for event in v]
seen: set[str] = set()
duplicates: list[str] = []
for name in names:
if name in seen:
duplicates.append(name)
seen.add(name)
if duplicates:
raise ValueError(
f"Duplicate GW event names found: {sorted(set(duplicates))}. "
"Each event must have a unique name."
)
return v
penalty_value: float = Field(
default=0.0,
description="Log-likelihood penalty returned when M > M_TOV (default: 0.0, i.e. no penalty)",
)
N_masses_evaluation: int = Field(
default=2000,
gt=0,
description="Number of mass samples to pre-sample from GW posterior",
)
N_masses_batch_size: int = Field(
default=1000,
gt=0,
description="Batch size for jax.lax.map processing of mass grid",
)
seed: int = Field(
default=42,
ge=0,
description="Random seed for reproducible mass sampling from GW posterior",
)
class GWResampledLikelihoodConfig(BaseLikelihoodConfig):
"""Gravitational wave likelihood configuration (legacy resampled version).
Legacy version that resamples masses from GW posterior on-the-fly
during each likelihood evaluation. Slower than presampled version.
Examples
--------
.. code-block:: yaml
- type: "gw_resampled"
enabled: true
events:
- name: "GW170817"
N_masses_evaluation: 20
"""
type: Literal["gw_resampled"] = Field(
default="gw_resampled", description="Likelihood type identifier"
)
events: list[dict[str, str]] = Field(
description="List of GW events (see GWLikelihoodConfig for format)",
min_length=1,
)
penalty_value: float = Field(default=0.0)
N_masses_evaluation: int = Field(default=20, gt=0)
N_masses_batch_size: int = Field(default=10, gt=0)
@field_validator("events")
@classmethod
def _validate_events(cls, v: list[dict[str, str]]) -> list[dict[str, str]]:
seen: set[str] = set()
duplicates: list[str] = []
for i, event in enumerate(v):
if "name" not in event:
raise ValueError(f"Event {i} missing required 'name' field")
name = event["name"]
if name in seen:
duplicates.append(name)
seen.add(name)
if duplicates:
raise ValueError(
f"Duplicate GW event names found: {sorted(set(duplicates))}. "
"Each event must have a unique name."
)
return v
class NICERLikelihoodConfig(BaseLikelihoodConfig):
"""NICER X-ray timing likelihood configuration using normalizing flows (DEFAULT).
Constrains mass-radius relation using NICER observations of
millisecond pulsars. Uses pre-trained normalizing flows on M-R
posteriors for efficient likelihood evaluation.
For the legacy KDE-based version, use type: "nicer_kde".
Examples
--------
.. code-block:: yaml
- type: "nicer"
enabled: true
pulsars:
- name: "J0030"
amsterdam_model_dir: "./flows/models/nicer_maf/J00300451/amsterdam_pdtu"
maryland_model_dir: "./flows/models/nicer_maf/J00300451/maryland_2spot_rm"
- name: "J0740"
amsterdam_model_dir: "./flows/models/nicer_maf/J07406620/amsterdam_gamma_nicerxmm"
maryland_model_dir: "./flows/models/nicer_maf/J07406620/maryland_unknown_nicerxmm_rm"
N_masses_evaluation: 100
Notes
-----
Both ``amsterdam_model_dir`` and ``maryland_model_dir`` are REQUIRED for each pulsar.
The schema validator will issue warnings if omitted, but ``NICERLikelihood.__init__``
will raise ``ValueError`` at runtime. Preset model paths are not yet implemented.
"""
type: Literal["nicer"] = Field(
default="nicer", description="Likelihood type identifier"
)
pulsars: list[dict[str, str]] = Field(
description=(
"List of pulsars to include. Each pulsar must have 'name' key. "
"REQUIRED: 'amsterdam_model_dir' and 'maryland_model_dir' keys "
"specify paths to trained flow model directories. "
"NICERLikelihood.__init__ will raise ValueError if either is missing."
),
min_length=1,
)
N_masses_evaluation: int = Field(
default=100,
gt=0,
description="Number of mass samples for likelihood evaluation",
)
N_masses_batch_size: int = Field(
default=20,
gt=0,
description="Batch size for processing mass samples",
)
seed: int = Field(
default=42,
ge=0,
description="Random seed for reproducible mass sampling in NICER likelihood",
)
@field_validator("pulsars")
@classmethod
def _validate_pulsars(cls, v: list[dict[str, str]]) -> list[dict[str, str]]:
seen: set[str] = set()
duplicates: list[str] = []
for i, pulsar in enumerate(v):
if "name" not in pulsar:
raise ValueError(f"Pulsar {i} missing required 'name' field")
name = pulsar["name"]
if name in seen:
duplicates.append(name)
seen.add(name)
# Warn if model directories not provided (will fail at runtime)
if "amsterdam_model_dir" not in pulsar:
logger.warning(
f"Pulsar {i} ({name}) missing 'amsterdam_model_dir'. "
"NICERLikelihood.__init__ will raise ValueError at runtime. "
"Preset model paths are not yet implemented."
)
if "maryland_model_dir" not in pulsar:
logger.warning(
f"Pulsar {i} ({name}) missing 'maryland_model_dir'. "
"NICERLikelihood.__init__ will raise ValueError at runtime. "
"Preset model paths are not yet implemented."
)
if duplicates:
raise ValueError(
f"Duplicate NICER pulsar names found: {sorted(set(duplicates))}. "
"Each pulsar must have a unique name."
)
return v
class NICERKDELikelihoodConfig(BaseLikelihoodConfig):
"""NICER X-ray timing likelihood configuration using KDE (LEGACY).
This is the legacy KDE-based NICER likelihood. For the recommended
flow-based version, use type: "nicer".
Constrains mass-radius relation using NICER observations of
millisecond pulsars. Uses kernel density estimation on M-R
posterior samples from analysis teams.
Examples
--------
.. code-block:: yaml
- type: "nicer_kde"
enabled: true
pulsars:
- name: "J0030"
amsterdam_samples_file: "./data/J0030_amsterdam.npz"
maryland_samples_file: "./data/J0030_maryland.npz"
- name: "J0740"
amsterdam_samples_file: "./data/J0740_amsterdam.npz"
maryland_samples_file: "./data/J0740_maryland.npz"
N_masses_evaluation: 100
"""
type: Literal["nicer_kde"] = Field(
default="nicer_kde", description="Likelihood type identifier"
)
pulsars: list[dict[str, str]] = Field(
description=(
"List of pulsars to include. Each pulsar must have 'name' key. "
"'amsterdam_samples_file' and 'maryland_samples_file' keys "
"specify paths to M-R posterior samples (.npz files)."
),
min_length=1,
)
N_masses_evaluation: int = Field(
default=100,
gt=0,
description="Number of mass grid points for marginalization over pulsar mass",
)
N_masses_batch_size: int = Field(
default=20,
gt=0,
description="Batch size for processing mass grid points",
)
@field_validator("pulsars")
@classmethod
def _validate_pulsars(cls, v: list[dict[str, str]]) -> list[dict[str, str]]:
seen: set[str] = set()
duplicates: list[str] = []
for i, pulsar in enumerate(v):
if "name" not in pulsar:
raise ValueError(f"Pulsar {i} missing required 'name' field")
name = pulsar["name"]
if name in seen:
duplicates.append(name)
seen.add(name)
# Both sample files are required for KDE approach
if "amsterdam_samples_file" not in pulsar:
raise ValueError(
f"Pulsar {i} missing required 'amsterdam_samples_file' field"
)
if "maryland_samples_file" not in pulsar:
raise ValueError(
f"Pulsar {i} missing required 'maryland_samples_file' field"
)
if duplicates:
raise ValueError(
f"Duplicate NICER pulsar names found: {sorted(set(duplicates))}. "
"Each pulsar must have a unique name."
)
return v
[docs]
class RadioLikelihoodConfig(BaseLikelihoodConfig):
"""Radio pulsar timing likelihood configuration.
Constrains neutron star masses using radio timing measurements.
Applies Gaussian mass constraints from pulsar timing observations.
Examples
--------
.. code-block:: yaml
- type: "radio"
enabled: true
pulsars:
- name: "J0740+6620"
mass_mean: 2.08
mass_std: 0.07
penalty_value: 0.0
"""
type: Literal["radio"] = Field(
default="radio", description="Likelihood type identifier"
)
pulsars: list[dict[str, str | float]] = Field(
description=(
"List of pulsars with timing mass measurements. Each pulsar must have "
"'name', 'mass_mean' (solar masses), and 'mass_std' (1-sigma, solar masses) keys."
),
min_length=1,
)
penalty_value: float = Field(
default=0.0,
description="Log-likelihood penalty for invalid TOV solutions (M_TOV ≤ m_min)",
)
@field_validator("pulsars")
@classmethod
def _validate_pulsars(
cls, v: list[dict[str, str | float]]
) -> list[dict[str, str | float]]:
for i, pulsar in enumerate(v):
required = {"name", "mass_mean", "mass_std"}
missing = required - set(pulsar.keys())
if missing:
raise ValueError(f"Pulsar {i} missing required fields: {missing}")
if not isinstance(pulsar["mass_mean"], (int, float)):
raise ValueError(f"Pulsar {i} 'mass_mean' must be a number")
if (
not isinstance(pulsar["mass_std"], (int, float))
or pulsar["mass_std"] <= 0
):
raise ValueError(f"Pulsar {i} 'mass_std' must be a positive number")
return v
[docs]
class ChiEFTLikelihoodConfig(BaseLikelihoodConfig):
"""Chiral effective field theory likelihood configuration.
Constrains EOS at low densities using chiral EFT uncertainty bands.
Checks that predicted pressure-density relation falls within bands.
Examples
--------
.. code-block:: yaml
- type: "chieft"
enabled: true
low_filename: "./data/chiEFT/low.dat"
high_filename: "./data/chiEFT/high.dat"
nb_n: 100
"""
type: Literal["chieft"] = Field(
default="chieft", description="Likelihood type identifier"
)
low_filename: str | None = Field(
default=None,
description=(
"Path to lower bound ChiEFT data file. "
"If None, uses default: data/chiEFT/2402.04172/low.dat"
),
)
high_filename: str | None = Field(
default=None,
description=(
"Path to upper bound ChiEFT data file. "
"If None, uses default: data/chiEFT/2402.04172/high.dat"
),
)
nb_n: int = Field(
default=100,
gt=0,
description="Number of density points to evaluate against ChiEFT bands",
)
class EOSConstraintsLikelihoodConfig(BaseLikelihoodConfig):
"""EOS constraint likelihood configuration.
Applies physics-motivated constraints on equation of state properties:
causality (cs² ≤ 1), thermodynamic stability (cs² ≥ 0), and
monotonic pressure.
Examples
--------
.. code-block:: yaml
- type: "constraints_eos"
enabled: true
penalty_causality: -1e10
penalty_stability: -1e10
penalty_pressure: -1e10
"""
type: Literal["constraints_eos"] = Field(
default="constraints_eos", description="Likelihood type identifier"
)
penalty_causality: float = Field(
default=-1e10,
description="Log-likelihood penalty for causality violation (cs² > 1)",
)
penalty_stability: float = Field(
default=-1e10,
description="Log-likelihood penalty for thermodynamic instability (cs² < 0)",
)
penalty_pressure: float = Field(
default=-1e10,
description="Log-likelihood penalty for non-monotonic pressure",
)
class TOVConstraintsLikelihoodConfig(BaseLikelihoodConfig):
"""TOV constraint likelihood configuration.
Applies penalty for TOV integration failures.
Examples
--------
.. code-block:: yaml
- type: "constraints_tov"
enabled: true
penalty_tov: -1e10
"""
type: Literal["constraints_tov"] = Field(
default="constraints_tov", description="Likelihood type identifier"
)
penalty_tov: float = Field(
default=-1e10,
description="Log-likelihood penalty for TOV integration failure",
)
class EsymConstraintsLikelihoodConfig(BaseLikelihoodConfig):
"""Symmetry energy constraint likelihood configuration (metamodel EOS only).
Penalises metamodel configurations where :math:`e_{\\rm sym}(n) < 0`.
Only applicable when using metamodel, metamodel+CSE, or metamodel+peakCSE
EOS parametrisations.
Examples
--------
.. code-block:: yaml
- type: "constraints_esym"
enabled: true
penalty_esym: -1e10
"""
type: Literal["constraints_esym"] = Field(
default="constraints_esym", description="Likelihood type identifier"
)
penalty_esym: float = Field(
default=-1e10,
description=(
"Log-likelihood penalty per density point where the metamodel symmetry "
"energy e_sym(n) < 0 (unphysical region)."
),
)
class GammaConstraintsLikelihoodConfig(BaseLikelihoodConfig):
"""Gamma constraint likelihood configuration (spectral EOS only).
Applies bounds on spectral decomposition Gamma parameters.
Only applicable when using spectral EOS parametrization.
Examples
--------
.. code-block:: yaml
- type: "constraints_gamma"
enabled: true
penalty_gamma: -1e10
"""
type: Literal["constraints_gamma"] = Field(
default="constraints_gamma", description="Likelihood type identifier"
)
penalty_gamma: float = Field(
default=-1e10,
description=(
"Log-likelihood penalty for Gamma bound violation. "
"Applies bounds Γ ∈ [0.6, 4.5] for spectral decomposition EOS."
),
)
class DeprecatedConstraintsLikelihoodConfig(BaseLikelihoodConfig):
"""Deprecated combined constraint likelihood configuration.
DEPRECATED: Use constraints_eos + constraints_tov instead.
Combined EOS and TOV constraints in a single likelihood.
Examples
--------
.. code-block:: yaml
- type: "constraints"
enabled: true
penalty_tov: -1e10
penalty_causality: -1e10
penalty_stability: -1e10
penalty_pressure: -1e10
"""
type: Literal["constraints"] = Field(
default="constraints", description="Likelihood type identifier"
)
penalty_tov: float = Field(
default=-1e10,
description="Log-likelihood penalty for TOV integration failure",
)
penalty_causality: float = Field(
default=-1e10,
description="Log-likelihood penalty for causality violation (cs² > 1)",
)
penalty_stability: float = Field(
default=-1e10,
description="Log-likelihood penalty for thermodynamic instability (cs² < 0)",
)
penalty_pressure: float = Field(
default=-1e10,
description="Log-likelihood penalty for non-monotonic pressure",
)
def model_post_init(self, __context: object) -> None:
warnings.warn(
"Deprecated: 'constraints' config is removed; use 'constraints_eos' + 'constraints_tov' instead",
DeprecationWarning,
stacklevel=2,
)
class REXLikelihoodConfig(BaseLikelihoodConfig):
"""REX (PREX/CREX) likelihood configuration.
NOT IMPLEMENTED YET - placeholder for future development.
Examples
--------
.. code-block:: yaml
- type: "rex"
enabled: true
experiment_name: "PREX"
"""
type: Literal["rex"] = Field(
default="rex", description="Likelihood type identifier"
)
experiment_name: str = Field(
default="PREX",
description="Name of REX experiment (PREX or CREX)",
)
def model_post_init(self, __context: object) -> None:
raise NotImplementedError("REX likelihood is not implemented")
class ZeroLikelihoodConfig(BaseLikelihoodConfig):
"""Zero likelihood configuration for prior-only sampling.
Returns zero log-likelihood (uniform likelihood) for all EOS configurations.
Use this for prior-only sampling without observational constraints.
Examples
--------
.. code-block:: yaml
- type: "zero"
enabled: true
"""
type: Literal["zero"] = Field(
default="zero", description="Likelihood type identifier"
)
[docs]
class MockMassRadiusLikelihoodConfig(BaseLikelihoodConfig):
"""Mock mass-radius likelihood configuration.
Constrains the M-R relation using one or more synthetic bivariate Gaussian
observations read from a JSON file. Each entry in the JSON file describes
a mock pulsar measurement with a mean mass and radius, their standard
deviations, and the Pearson correlation between the two quantities.
The JSON file must be a list of objects with the following keys:
- ``name`` (str) — pulsar identifier, e.g. ``"PSR0"``
- ``mean_mass`` (float) — mean mass (:math:`M_\\odot`)
- ``mean_radius`` (float) — mean radius (km)
- ``std_mass`` (float) — standard deviation of mass (:math:`M_\\odot`)
- ``std_radius`` (float) — standard deviation of radius (km)
- ``correlation`` (float) — Pearson correlation, strictly in (-1, 1)
Examples
--------
.. code-block:: yaml
- type: "mock_mr"
enabled: true
json_file: "./mock_observations.json"
N_masses_evaluation: 100
seed: 42
The corresponding ``mock_observations.json`` should look like:
.. code-block:: json
[
{
"name": "PSR0",
"mean_mass": 1.4,
"mean_radius": 12.0,
"std_mass": 0.1,
"std_radius": 0.1,
"correlation": 0.1
}
]
"""
type: Literal["mock_mr"] = Field(
default="mock_mr", description="Likelihood type identifier"
)
json_file: str = Field(
description=(
"Path to a JSON file containing the list of mock mass-radius observations. "
"Each entry must have: name, mean_mass, mean_radius, std_mass, std_radius, correlation."
)
)
penalty_value: float = Field(
default=0.0,
description="Log-likelihood penalty when the sampled mass exceeds M_TOV (default: 0.0, i.e. no penalty)",
)
N_masses_evaluation: int = Field(
default=100,
gt=0,
description="Number of mass samples pre-drawn for Monte-Carlo likelihood integration",
)
N_masses_batch_size: int = Field(
default=20,
gt=0,
description="Batch size for jax.lax.map processing of mass samples",
)
seed: int = Field(
default=42,
ge=0,
description="Random seed for reproducible mass pre-sampling",
)
# Discriminated union of all likelihood types
LikelihoodConfig = Annotated[
Union[
GWLikelihoodConfig,
GWResampledLikelihoodConfig,
NICERLikelihoodConfig,
NICERKDELikelihoodConfig,
RadioLikelihoodConfig,
ChiEFTLikelihoodConfig,
EOSConstraintsLikelihoodConfig,
TOVConstraintsLikelihoodConfig,
EsymConstraintsLikelihoodConfig,
GammaConstraintsLikelihoodConfig,
DeprecatedConstraintsLikelihoodConfig,
REXLikelihoodConfig,
ZeroLikelihoodConfig,
MockMassRadiusLikelihoodConfig,
],
Discriminator("type"),
]