Nested Sampling wrapper

Nested-sampling wrapper for PyXspec.

Provides a thin Python layer around the C++ nest command that returns a NestedResult object holding the FITS output's data and metadata. Heavy lifting (the NS algorithm itself) happens in C++ via nest run.

Usage:

import xspec
xspec.AllData.dummyrsp(0.5, 7.0, 200)
m = xspec.Model("powerlaw")
m.powerlaw.PhoIndex = 2.0
m.powerlaw.norm     = 1e-3
xspec.AllData.fakeit(1, xspec.FakeitSettings(exposure=3e4))
xspec.Fit.perform()
# Set a Jeffreys prior on the norm parameter (mandatory because its
# default [hard_lo, hard_hi] = [0, 1e24] is too wide for nested sampling).    
# Run NS.
result = xspec.runNested("posterior.fits",
                         nLive=400, dlogZTol=0.5)
print("log Z =", result.logZ, "+/-", result.logZerr)
print("samples shape:", result.samples.shape)
print("weights shape:", result.weights.shape)
class xspec.NestedResult(file_name)

In-memory view of a `nest run` output FITS file.

Attributes:

  • samplesnp.ndarray, shape (N, P)

    Weighted posterior draws in physical-parameter space.

  • weightsnp.ndarray, shape (N,)

    Normalized importance weights (sum to 1).

  • log_weightsnp.ndarray, shape (N,)

    Log-weights as written by the NS algorithm (sum to logZ).

  • log_likelihoodnp.ndarray, shape (N,)

    log L at each sample.

  • param_labelslist[str]

    Column-name labels from the FITS NEST extension.

  • equal_weight_samplesnp.ndarray, shape (M, P)

    Importance-resampled equal-weight draws from the CHAIN extension. Compatible with chain-load consumers.

  • equal_weight_statistic : np.ndarray

  • logZ : float

  • logZerr : float

  • info_H : float

  • n_live, n_like, n_iter, n_modes : int

  • converged : bool

  • termination : str

  • file_name : str

xspec.runNested(file_name, nLive=400, dlogZTol=0.5, maxClusters=16, enlargement=1.2, resampleN=4000, overwrite=True, checkpointEvery=200, parallel=None)

Run the nested-sampling algorithm and return a NestedResult.

Args:

file_name : str, path for the output FITS file.

nLive : int, number of live points (default 400).

dlogZTol : float, Skilling termination tolerance (default 0.5).

maxClusters : int, max ellipsoid count (1 = single-ellipsoid).

enlargement : float, bounding-ellipsoid enlargement factor.

resampleN : int, # equal-weight draws in the CHAIN extension.

overwritebool, if True overwrite the output file AND discard

any existing <file_name>.ckpt.fits checkpoint so the run starts fresh. If False and a compatible checkpoint is present, the run auto-resumes.

checkpointEveryint, write a FITS checkpoint every N outer

iterations (0 disables; default 200).

parallelint or None, if set issues parallel nest <K>

before the run so K worker processes evaluate likelihoods in parallel via the K-point removal scheme (silently capped at floor(nLive/10) by the sampler to keep the K-batch logZ bias well below dlogZTol per Buchner 2014). None leaves the current parallel nest setting alone (default 1 = single-threaded).

Returns:

NestedResult instance.

Raises:

Exception if nest run fails (e.g. wide-prior refusal).

The function does NOT set up the priors. Callers should configure them via the bayes <par> <type> UI before calling. In particular, parameters whose default hard limits span more than 4 dex (such as powerlaw norm with hard_hi = 1e24) will cause nest run to refuse.

Resume: a <file_name>.ckpt.fits is written every checkpointEvery iterations using an atomic tmp+rename, so a SIGKILL mid-run never corrupts the file. If runNested is called again with overwrite=False and the same file_name + same nPars/nLive, it auto-resumes from the final checkpoint. On successful completion the checkpoint is auto-removed.