derivkit 1.0.0__py3-none-any.whl

derivkit/forecasting/getdist_dali_samples.py

@@ -0,0 +1,429 @@
+"""Provides GetDist sampling helpers for DALI approximate posteriors.
+
+This module converts DALI-expanded posteriors into GetDist-compatible
+:class:`getdist.MCSamples` for plotting and analysis.
+
+Two backends are provided:
+
+- Importance sampling using a Fisher-Gaussian kernel centered on ``theta0``.
+- ``emcee`` ensemble MCMC targeting the same DALI log-posterior.
+
+The target log-posterior is evaluated with
+:func:`derivkit.forecasting.expansions.build_logposterior_dali`, optionally
+including user-defined priors and parameter support bounds.
+
+Note: GetDist's ``loglikes`` field stores ``-log(posterior)``, not ``-log(likelihoods)``.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any, Callable, Sequence
+
+import emcee
+import numpy as np
+from getdist import MCSamples
+from numpy.typing import NDArray
+
+from derivkit.forecasting.expansions import build_logposterior_dali
+from derivkit.forecasting.priors_core import build_prior
+from derivkit.forecasting.sampling_utils import (
+    apply_parameter_bounds,
+    init_walkers_from_fisher,
+    kernel_samples_from_fisher,
+    log_gaussian_kernel,
+)
+from derivkit.utils.validate import validate_dali_shape
+
+__all__ = [
+    "dali_to_getdist_importance",
+    "dali_to_getdist_emcee",
+]
+
+
+def _resolve_support_bounds(
+    *,
+    n_params: int,
+    prior_bounds: Sequence[tuple[float | None, float | None]] | None,
+    sampler_bounds: Sequence[tuple[float | None, float | None]] | None,
+) -> Sequence[tuple[float | None, float | None]] | None:
+    """Computes the effective parameter-support bounds used by the sampler.
+
+    This function combines two optional sources of support constraints:
+
+    - ``prior_bounds``, which truncate the prior (and therefore the posterior support).
+    - ``sampler_bounds``, restrict the sampling domain used for rejection/initialization.
+
+    When both are provided, the returned bounds are their intersection, computed
+    component-wise for each parameter. Each bound is a ``(low, high)`` pair where
+    either endpoint may be ``None`` to indicate no constraint.
+
+    Args:
+        n_params: Number of parameters (expected length of any provided bounds sequence).
+        prior_bounds: Optional per-parameter prior truncation bounds.
+        sampler_bounds: Optional per-parameter sampling-domain bounds.
+
+    Returns:
+        The effective per-parameter bounds to use for support filtering, or ``None``
+        if neither set of bounds is provided.
+
+    Raises:
+        ValueError: If a provided bounds sequence does not have length ``n_params``,
+            or if the intersection of ``prior_bounds`` and ``sampler_bounds`` is empty
+            for any parameter (i.e., the resulting lower bound exceeds the upper bound).
+    """
+    if sampler_bounds is not None and len(sampler_bounds) != n_params:
+        raise ValueError(
+            f"sampler_bounds must have length p={n_params}; got len(sampler_bounds)={len(sampler_bounds)}."
+        )
+
+    if prior_bounds is not None and len(prior_bounds) != n_params:
+        raise ValueError(
+            f"prior_bounds must have length p={n_params}; got len(prior_bounds)={len(prior_bounds)}."
+        )
+
+    if sampler_bounds is None:
+        return prior_bounds
+    if prior_bounds is None:
+        return sampler_bounds
+
+    bounds = []
+    for i, ((hlo, hhi), (plo, phi)) in enumerate(zip(sampler_bounds, prior_bounds, strict=True)):
+        lo = None if (hlo is None and plo is None) else max(x for x in (hlo, plo) if x is not None)
+        hi = None if (hhi is None and phi is None) else min(x for x in (hhi, phi) if x is not None)
+
+        if lo is not None and hi is not None and lo > hi:
+            raise ValueError(
+                f"Empty support for parameter index {i}: "
+                f"intersection gives ({lo}, {hi}). "
+                "Check prior_bounds and sampler_bounds."
+            )
+
+        bounds.append((lo, hi))
+
+    return bounds
+
+
+def dali_to_getdist_importance(
+    theta0: NDArray[np.floating],
+    dali: dict[int, tuple[NDArray[np.floating], ...]],
+    *,
+    forecast_order: int | None = 2,
+    names: Sequence[str],
+    labels: Sequence[str],
+    n_samples: int = 50_000,
+    kernel_scale: float = 1.5,
+    seed: int | None = None,
+    prior_terms: Sequence[tuple[str, dict[str, Any]] | dict[str, Any]] | None = None,
+    prior_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    logprior: Callable[[NDArray[np.floating]], float] | None = None,
+    sampler_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    label: str = "DALI (importance)",
+) -> MCSamples:
+    """Returns :class:`getdist.MCSamples` for a DALI posterior via importance sampling.
+
+    The target log-posterior is evaluated with
+    :func:`derivkit.forecasting.expansions.build_logposterior_dali`. Samples
+    are drawn from a Fisher–Gaussian kernel centered on ``theta0`` and
+    reweighted by the difference between the target log-posterior and the
+    kernel log-density.
+
+    Args:
+        theta0: Fiducial parameter vector with shape ``(p,)`` for ``p`` parameters.
+        dali: Dictionary returned by :func:`derivkit.forecasting.build_dali`.
+        forecast_order: Maximum order of the DALI expansion to include
+            (e.g., 2 for doublet, 3 for triplet).
+        names: Parameter names used to label the returned samples (length ``p``).
+        labels: LaTeX-formatted parameter labels used to label the returned samples (length ``p``).
+        n_samples: Number of importance samples to draw.
+        kernel_scale: Scale factor applied to the Fisher covariance for the kernel.
+        seed: Random seed for kernel sampling.
+        prior_terms: Optional prior term specifications used to build a prior via
+            :func:`derivkit.forecasting.priors.core.build_prior`. Mutually exclusive with ``logprior``.
+            Can be combined with ``prior_bounds`` to truncate prior support.
+        prior_bounds: Optional per-parameter bounds passed to
+            :func:`derivkit.forecasting.priors.core.build_prior` to truncate the prior support.
+            If provided with no ``prior_terms``, this corresponds to a bounded-uniform (top-hat) prior.
+            A bounded-uniform prior is proper (normalizable), unlike an unbounded flat prior which is improper.
+            Mutually exclusive with ``logprior``.
+        logprior: Optional custom log-prior ``logprior(theta)``. Mutually exclusive with
+            ``prior_terms``/``prior_bounds``. If none of these are provided, a flat (typically improper)
+            prior is used.
+        sampler_bounds: Optional per-parameter sampling-domain bounds used for early rejection
+            and walker initialization.
+        label: Label attached to the returned samples output (e.g., used by GetDist in plot legends/titles).
+
+    Returns:
+        :class:`getdist.MCSamples` containing the importance ``weights``.
+        :attr:`getdist.MCSamples.loglikes` stores ``-log(posterior) (likelihoods x prior)``
+        up to an additive constant, consistent with GetDist's convention.
+
+    Raises:
+        ValueError: If shapes are inconsistent, mutually exclusive options are provided,
+            or the effective support bounds are invalid (e.g., an empty intersection).
+        RuntimeError: If all samples are rejected by bounds or prior support.
+    """
+    fiducial = np.asarray(theta0, dtype=float).reshape(-1)
+
+    if not isinstance(dali, dict):
+        raise TypeError(
+            "dali must be the dict form returned by build_dali.")
+
+    validate_dali_shape(fiducial, dali)
+
+    # Fisher for the Gaussian proposal kernel comes from dali[1]
+    if 1 not in dali.keys():
+        raise ValueError("dali must contain key 1 with dali[1] == (F,).")
+
+    fisher_matrix = np.asarray(dali[1][0], dtype=float)
+
+    n_params = int(fiducial.size)
+    n_names = len(names)
+    n_labels = len(labels)
+    if n_names != n_params:
+        raise ValueError(f"names must have length p={n_params}; got len(names)={n_names}.")
+    if n_labels != n_params:
+        raise ValueError(f"labels must have length p={n_params}; got len(labels)={n_labels}.")
+
+    if logprior is not None and (prior_terms is not None or prior_bounds is not None):
+        raise ValueError(
+            "Ambiguous prior specification: pass either `logprior` or (`prior_terms` and/or `prior_bounds`), not both."
+        )
+
+    support_bounds = _resolve_support_bounds(
+        n_params=n_params,
+        prior_bounds=prior_bounds,
+        sampler_bounds=sampler_bounds,
+    )
+
+    # Computing the prior once prevents rebuilding inside logposterior_dali
+    logprior_fn = logprior
+    if logprior_fn is None and (
+            prior_terms is not None or prior_bounds is not None):
+        logprior_fn = build_prior(terms=prior_terms, bounds=prior_bounds)
+
+    kernel_samples = kernel_samples_from_fisher(
+        fiducial,
+        fisher_matrix,
+        n_samples=int(n_samples),
+        kernel_scale=float(kernel_scale),
+        seed=seed,
+    )
+
+    kernel_samples = apply_parameter_bounds(kernel_samples, support_bounds)
+    if kernel_samples.shape[0] == 0:
+        raise RuntimeError("All kernel samples rejected by bounds.")
+
+    target_logpost = np.array(
+        [
+            build_logposterior_dali(
+                theta,
+                fiducial,
+                dali,
+                forecast_order=forecast_order,
+                logprior=logprior_fn,
+            )
+            for theta in kernel_samples
+        ],
+        dtype=float,
+    )
+
+    keep = np.isfinite(target_logpost)
+    kernel_samples = kernel_samples[keep]
+    target_logpost = target_logpost[keep]
+    if kernel_samples.shape[0] == 0:
+        raise RuntimeError(
+            "All kernel samples were rejected: the target log-posterior "
+            "was -inf for every sample "
+            "(outside prior/support bounds or invalid model evaluation)."
+        )
+
+    kernel_logpdf = log_gaussian_kernel(
+        kernel_samples,
+        fiducial,
+        fisher_matrix,
+        kernel_scale=float(kernel_scale),
+    )
+
+    log_weights = target_logpost - kernel_logpdf
+    log_weights -= np.max(log_weights)
+    weights = np.exp(log_weights)
+
+    loglikes = -target_logpost
+
+    ranges = None
+    if support_bounds is not None:
+        ranges = {n: [lo, hi] for n, (lo, hi) in zip(names, support_bounds, strict=True)}
+
+    return MCSamples(
+        samples=kernel_samples,
+        weights=weights,
+        loglikes=loglikes,
+        names=list(names),
+        labels=list(labels),
+        ranges=ranges,
+        label=label,
+    )
+
+
+def dali_to_getdist_emcee(
+    theta0: NDArray[np.floating],
+    dali: dict[int, tuple[NDArray[np.floating], ...]],
+    *,
+    forecast_order: int | None = 2,
+    names: Sequence[str],
+    labels: Sequence[str],
+    n_steps: int = 10_000,
+    burn: int = 2_000,
+    thin: int = 2,
+    n_walkers: int | None = None,
+    init_scale: float = 0.5,
+    seed: int | None = None,
+    prior_terms: Sequence[tuple[str, dict[str, Any]] | dict[str, Any]] | None = None,
+    prior_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    logprior: Callable[[NDArray[np.floating]], float] | None = None,
+    sampler_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    label: str = "DALI (emcee)",
+) -> MCSamples:
+    """Returns :class:`getdist.MCSamples` from ``emcee`` sampling of a DALI posterior.
+
+    The target log-posterior is evaluated with
+    :func:`derivkit.forecasting.expansions.build_logposterior_dali`.
+    Walkers are initialized from a Fisher–Gaussian cloud around ``theta0`` and
+    evolved with :class:`emcee.EnsembleSampler`. Optional priors and support
+    bounds are applied through the target log-posterior.
+
+    Args:
+        theta0: Fiducial parameter vector with shape ``(p,)`` with ``p`` parameters.
+        dali: Dictionary returned by :func:`derivkit.forecasting.build_dali`.
+        forecast_order: Maximum order of the DALI expansion to include (e.g., 2 for doublet, 3 for triplet).
+        names: Parameter names used to label the returned samples (length ``p``).
+        labels: LaTeX-formatted parameter labels used to label the returned samples (length ``p``).
+        n_steps: Total number of MCMC steps.
+        burn: Number of initial MCMC steps discarded as burn-in, allowing the chain to
+            forget its initial starting positions before samples are retained.
+        thin: Thinning factor applied after burn-in; only every ``thin``-th sample is kept
+            to reduce autocorrelation in the chain.
+        n_walkers: Number of walkers. Defaults to ``max(32, 8 * p)``.
+        init_scale: Initial scatter scale for walker initialization.
+        seed: Random seed for walker initialization.
+        prior_terms: Optional prior term specifications used to build a prior via
+            :func:`derivkit.forecasting.priors.core.build_prior`. Mutually exclusive with ``logprior``.
+            Can be combined with ``prior_bounds`` to truncate prior support.
+        prior_bounds: Optional per-parameter bounds passed to
+            :func:`derivkit.forecasting.priors.core.build_prior` to truncate the prior support.
+            If provided with no ``prior_terms``, this corresponds to a bounded-uniform (top-hat) prior.
+            A bounded-uniform prior is proper (normalizable), unlike an unbounded flat prior which is improper.
+            Mutually exclusive with ``logprior``.
+        logprior: Optional custom log-prior ``logprior(theta)``. Mutually exclusive with
+            ``prior_terms``/``prior_bounds``. If none of these are provided, a flat (typically improper)
+            prior is used.
+        sampler_bounds: Optional per-parameter sampling-domain bounds used for early rejection
+            and walker initialization.
+        label: Label attached to the returned samples output (e.g., used by GetDist in plot legends/titles).
+
+    Returns:
+        :class:`getdist.MCSamples` containing MCMC chains.
+        :attr:`getdist.MCSamples.loglikes` stores ``-log(posterior) (likelihoods x prior)``
+        up to an additive constant, consistent with GetDist's convention.
+
+    Raises:
+        ValueError: If shapes are inconsistent, mutually exclusive options are provided,
+            or the effective support bounds are invalid (e.g., an empty intersection).
+        RuntimeError: If walker initialization fails (no valid starting points).
+    """
+    fiducial = np.asarray(theta0, dtype=float).reshape(-1)
+
+    if not isinstance(dali, dict):
+        raise TypeError(
+            "dali must be the dict form returned by build_dali.")
+
+    validate_dali_shape(fiducial, dali)
+
+    if 1 not in dali.keys():
+        raise ValueError("dali must contain key 1 with dali[1] == (F,).")
+
+    fisher_matrix = np.asarray(dali[1][0], dtype=float)
+
+    n_params = int(fiducial.size)
+    n_names = len(names)
+    n_labels = len(labels)
+    if n_names != n_params:
+        raise ValueError(f"names must have length p={n_params}; got len(names)={n_names}.")
+    if n_labels != n_params:
+        raise ValueError(f"labels must have length p={n_params}; got len(labels)={n_labels}.")
+
+    if n_walkers is None:
+        n_walkers = max(32, 8 * n_params)
+
+    if logprior is not None and (prior_terms is not None or prior_bounds is not None):
+        raise ValueError(
+            "Ambiguous prior specification: pass either `logprior` or (`prior_terms` and/or `prior_bounds`), not both."
+        )
+
+    support_bounds = _resolve_support_bounds(
+        n_params=n_params,
+        prior_bounds=prior_bounds,
+        sampler_bounds=sampler_bounds,
+    )
+
+    # Compute prior once, as this prevents rebuilding inside logposterior_dali.
+    logprior_fn = logprior
+    if logprior_fn is None and (
+            prior_terms is not None or prior_bounds is not None):
+        logprior_fn = build_prior(terms=prior_terms, bounds=prior_bounds)
+
+    walker_init = init_walkers_from_fisher(
+        fiducial,
+        fisher_matrix,
+        n_walkers=int(n_walkers),
+        init_scale=float(init_scale),
+        seed=seed,
+        sampler_bounds=support_bounds,
+    )
+
+    walker_init = np.asarray(walker_init, dtype=float)
+    if walker_init.ndim != 2 or walker_init.shape[0] == 0 or walker_init.shape[1] != n_params:
+        raise RuntimeError(
+            "Walker initialization failed: no valid starting points. "
+            "The provided bounds/prior support likely exclude the Fisher kernel around theta0. "
+            "Try loosening bounds, increasing init_scale, or checking theta0 is inside support."
+        )
+
+    _base_log_prob = partial(
+        build_logposterior_dali,
+        theta0=fiducial,
+        dali=dali,
+        forecast_order=forecast_order,
+        logprior=logprior_fn,
+    )
+
+    def log_prob(theta: NDArray[np.floating]) -> float:
+        """Target log-posterior with hard support bounds (returns -inf outside)."""
+        if support_bounds is not None:
+            th = np.asarray(theta, dtype=float).reshape(1, -1)
+            if apply_parameter_bounds(th, support_bounds).shape[0] == 0:
+                return -np.inf
+        return float(_base_log_prob(theta))
+
+    sampler = emcee.EnsembleSampler(int(n_walkers), n_params, log_prob)
+    sampler.run_mcmc(walker_init, int(n_steps), progress=True)
+
+    chains = sampler.get_chain(discard=int(burn), thin=int(thin))
+    log_posteriors = sampler.get_log_prob(discard=int(burn), thin=int(thin))
+
+    chain_list = [chains[:, walker_idx, :] for walker_idx in range(chains.shape[1])]
+    loglikes_list = [-log_posteriors[:, walker_idx] for walker_idx in range(log_posteriors.shape[1])]
+
+    ranges = None
+    if support_bounds is not None:
+        ranges = {n: [lo, hi] for n, (lo, hi) in zip(names, support_bounds, strict=True)}
+
+    return MCSamples(
+        samples=chain_list,
+        loglikes=loglikes_list,
+        names=list(names),
+        labels=list(labels),
+        ranges=ranges,
+        label=label,
+    )

derivkit/forecasting/getdist_fisher_samples.py

@@ -0,0 +1,235 @@
+"""Provides conversion helpers for Fisher–Gaussian forecasts and GetDist objects.
+
+This module converts Fisher-matrix Gaussian approximations into
+GetDist-compatible representations for plotting and analysis.
+
+Two outputs are supported:
+
+- An analytic Gaussian approximation via :class:`getdist.gaussian_mixtures.GaussianND`
+  with mean ``theta0`` and covariance from the (pseudo-)inverse Fisher matrix.
+- Monte Carlo samples drawn from the Fisher Gaussian as :class:`getdist.MCSamples`, with
+  optional prior support hard bounds, and :attr:`getdist.MCSamples.loglikes`.
+
+These helpers are intended for quick visualization (e.g. triangle plots) and
+simple prior truncation without running an MCMC sampler.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Sequence
+
+import numpy as np
+from getdist import MCSamples
+from getdist.gaussian_mixtures import GaussianND
+from numpy.typing import NDArray
+
+from derivkit.forecasting.priors_core import build_prior
+from derivkit.forecasting.sampling_utils import (
+    apply_parameter_bounds,
+    fisher_to_cov,
+    kernel_samples_from_fisher,
+)
+from derivkit.utils.validate import validate_fisher_shape
+
+__all__ = [
+    "fisher_to_getdist_gaussiannd",
+    "fisher_to_getdist_samples",
+]
+
+
+def fisher_to_getdist_gaussiannd(
+    theta0: NDArray[np.floating],
+    fisher: NDArray[np.floating],
+    *,
+    names: Sequence[str] | None = None,
+    labels: Sequence[str] | None = None,
+    label: str = "Fisher (Gaussian)",
+    rcond: float | None = None,
+) -> GaussianND:
+    """Returns :class:`getdist.gaussian_mixtures.GaussianND` for the Fisher Gaussian.
+
+    Args:
+        theta0: Fiducial parameter vector with shape ``(p,)`` with ``p`` parameters.
+        fisher: Fisher matrix with shape ``(p, p)``.
+        names: Optional parameter names (length ``p``).
+            Defaults to ``["p" + str(x) for x in range(len(theta0))]``.
+        labels: Optional parameter labels (length ``p``).
+            Defaults to ``["p" + str(x) for x in range(len(theta0))]``.
+        label: Label attached to the returned object.
+        rcond: Cutoff passed to the Fisher (pseudo-)inverse when forming the covariance.
+
+    Returns:
+        A :class:`getdist.gaussian_mixtures.GaussianND` with mean ``theta0`` and covariance from ``fisher``.
+
+    Raises:
+        ValueError: If ``names``/``labels`` lengths do not match ``p``.
+    """
+    theta0 = np.asarray(theta0, dtype=float)
+    fisher = np.asarray(fisher, dtype=float)
+    validate_fisher_shape(theta0, fisher)
+
+    n_params = int(theta0.size)
+
+    default_names = [f"p{i}" for i in range(n_params)]
+    default_labels = [rf"p_{{{i}}}" for i in range(n_params)]
+
+    param_names = list(default_names if names is None else names)
+    param_labels = list(default_labels if labels is None else labels)
+
+    if len(param_names) != n_params:
+        raise ValueError(
+            f"`names` must have length {n_params} (number of parameters), got {len(param_names)}."
+        )
+    if len(param_labels) != n_params:
+        raise ValueError(
+            f"`labels` must have length {n_params} (number of parameters), got {len(param_labels)}."
+        )
+
+    covariance = fisher_to_cov(fisher, rcond=rcond)
+
+    return GaussianND(
+        mean=theta0,
+        cov=covariance,
+        names=param_names,
+        labels=param_labels,
+        label=label,
+    )
+
+
+def fisher_to_getdist_samples(
+    theta0: NDArray[np.floating],
+    fisher: NDArray[np.floating],
+    *,
+    names: Sequence[str],
+    labels: Sequence[str],
+    n_samples: int = 30_000,
+    seed: int | None = None,
+    kernel_scale: float = 1.0,
+    prior_terms: Sequence[tuple[str, dict[str, Any]] | dict[str, Any]] | None = None,
+    prior_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    logprior: Callable[[NDArray[np.floating]], float] | None = None,
+    hard_bounds: Sequence[tuple[float | None, float | None]] | None = None,
+    store_loglikes: bool = True,
+    label: str = "Fisher (samples)",
+) -> MCSamples:
+    """Draws samples from the Fisher Gaussian as :class:`getdist.MCSamples`.
+
+    Samples are drawn from a multivariate Gaussian with mean ``theta0`` and
+    covariance ``kernel_scale**2 * pinv(fisher)``. Optionally, samples are
+    truncated by hard bounds and/or by a prior (via ``logprior`` or
+    ``prior_terms``/``prior_bounds``).
+
+    GetDist stores :attr:`getdist.MCSamples.loglikes` as ``-log(posterior)`` up to an additive
+    constant. When ``store_loglikes=True``, this function stores::
+
+        -log p(theta|d) = 0.5 * (theta-theta0)^T F (theta-theta0) - logprior(theta) + C
+
+    where ``C`` is an arbitrary additive constant and ``F`` defines the Fisher-Gaussian
+    approximation to ``-log(likelihoods)`` around ``theta0``.
+    In this implementation, ``C`` is effectively zero since no additional shifting is applied.
+    If no prior is provided, the prior term is omitted.
+
+    Args:
+        theta0: Fiducial parameter vector with shape ``(p,)`` with ``p`` parameters.
+        fisher: Fisher matrix with shape ``(p, p)``.
+        names: Parameter names (length ``p``).
+        labels: Parameter labels (length ``p``).
+        n_samples: Number of samples to draw.
+        seed: Random seed.
+        kernel_scale: Multiplicative scale applied to the Gaussian covariance.
+        prior_terms: Optional prior term specifications used to build a prior.
+            Can be provided with or without ``prior_bounds``.
+        prior_bounds: Optional bounds used to truncate prior support.
+            Can be provided with or without ``prior_terms``.
+        logprior: Custom log-prior callable. Mutually exclusive with
+            ``prior_terms``/``prior_bounds``.
+        hard_bounds: Hard bounds applied by rejection (samples outside are dropped).
+            Mutually exclusive with encoding support via ``prior_terms``/``prior_bounds``.
+        store_loglikes: If ``True``, compute and store :attr:`getdist.MCSamples.loglikes`.
+        label: Label for the returned :class:`getdist.MCSamples`.
+
+    Returns:
+        :class:`getdist.MCSamples` containing the retained samples and
+        optional :attr:`getdist.MCSamples.loglikes`.
+
+    Raises:
+        ValueError: If ``n_samples`` is non-positive, if ``names`` or ``labels`` have
+            incorrect length, or if mutually exclusive options are provided.
+        RuntimeError: If all samples are rejected by bounds or prior support.
+    """
+    theta0 = np.asarray(theta0, dtype=float)
+    fisher = np.asarray(fisher, dtype=float)
+    validate_fisher_shape(theta0, fisher)
+
+    n_params = int(theta0.size)
+
+    if len(names) != n_params:
+        raise ValueError(
+            f"`names` must have length {n_params} (number of parameters), got {len(names)}."
+        )
+    if len(labels) != n_params:
+        raise ValueError(
+            f"`labels` must have length {n_params} (number of parameters), got {len(labels)}."
+        )
+
+    n_samples = int(n_samples)
+    if n_samples <= 0:
+        raise ValueError("n_samples must be a positive integer")
+
+    if logprior is not None and (prior_terms is not None or prior_bounds is not None):
+        raise ValueError(
+            "Ambiguous prior specification: pass either `logprior` or `prior_terms` and `prior_bounds`, not both. "
+            "`prior_terms` and `prior_bounds` can be provided independently."
+        )
+
+    if hard_bounds is not None and (prior_terms is not None or prior_bounds is not None):
+        raise ValueError(
+            "Ambiguous support: choose either `hard_bounds` or prior-based support "
+            "via (`prior_terms`/`prior_bounds`)."
+        )
+
+    samples = kernel_samples_from_fisher(
+        theta0,
+        fisher,
+        n_samples=n_samples,
+        kernel_scale=float(kernel_scale),
+        seed=seed,
+    )
+
+    samples = apply_parameter_bounds(samples, hard_bounds)
+    if samples.shape[0] == 0:
+        raise RuntimeError("All samples rejected by hard bounds (no samples left).")
+
+    delta = samples - theta0[None, :]
+    theta_quad = np.einsum("ni,ij,nj->n", delta, fisher, delta).astype(float, copy=False)
+
+    loglikes: NDArray[np.floating] | None = None
+    if store_loglikes:
+        logprior_fn: Callable[[NDArray[np.floating]], float] | None = None
+        if logprior is not None:
+            logprior_fn = logprior
+        elif prior_terms is not None or prior_bounds is not None:
+            logprior_fn = build_prior(terms=prior_terms, bounds=prior_bounds)
+
+        log_prior_vals: NDArray[np.floating] | None = None
+        if logprior_fn is not None:
+            log_prior_vals = np.array([float(logprior_fn(s)) for s in samples], dtype=float)
+            keep = np.isfinite(log_prior_vals)
+            samples = samples[keep]
+            theta_quad = theta_quad[keep]
+            log_prior_vals = log_prior_vals[keep]
+            if samples.shape[0] == 0:
+                raise RuntimeError(
+                    "All samples were rejected by the prior: logprior evaluated to -inf for every sample, "
+                    "indicating zero prior density outside the allowed prior support."
+                )
+
+        loglikes = 0.5 * theta_quad if log_prior_vals is None else (0.5 * theta_quad - log_prior_vals)
+
+    return MCSamples(
+        samples=samples,
+        loglikes=loglikes,
+        names=list(names),
+        labels=list(labels),
+        label=label,
+    )