Skip to content

Solver

Solver

Bases: object

observed_spectrum property

Return the observed spectrum read from xspec

parameter_names property

Return unique parameter names aligned with XSPEC ordering.

Returns:

Type Description
list[str]

Parameter names augmented with component identifiers to avoid duplicates.

__init__(prior, outputfiles_basename='./sixsa', overwrite=False, n_jobs=os.cpu_count(), *, backend)

Initialise the Bayesian X-ray spectral analysis solver.

Reads the currently loaded xspec model, builds the prior distribution from prior, and prepares a multiprocessing pool for parallel likelihood evaluations.

Parameters:

Name Type Description Default
prior

Prior specification forwarded to build_prior. Accepts the same formats as build_prior.

 required
outputfiles_basename

Directory where backend output files (chains, checkpoints, traces) are stored. Created automatically if it does not exist.

 './sixsa'
overwrite

If True, clear outputfiles_basename when it already contains files. Defaults to False.

 False
n_jobs

Number of worker processes for the multiprocessing pool. Defaults to cpu_count().

 cpu_count()
backend

Backend configuration object. The solver infers the backend at construction time from this mandatory config.

 required

build_dataframe(distribution='posterior', num_samples=10000)

Build a posterior sample table from a named distribution.

Parameters:

Name Type Description Default
distribution str

Key in self.distributions to sample from. Defaults to "posterior".

 'posterior'
num_samples

Number of samples to draw. Defaults to 10_000.

 10000

Returns:

Type Description
DataFrame

Table with parameter samples.

build_inference_data(distribution='posterior', num_samples=10000, include_prior=True, include_observed=True, include_log_likelihood=True)

Build an ArviZ InferenceData object from the fitted model.

Mirrors build_dataframe but returns a richer container that is understood by the ArviZ ecosystem (diagnostics, plotting, I/O, and model comparison via az.compare).

Parameters:

Name Type Description Default
distribution str

Key in self.distributions to sample posterior draws from. Defaults to "posterior".

 'posterior'
num_samples int

Number of posterior draws. Defaults to 10_000.

 10000
include_prior bool

If True, draw prior samples and attach them as the prior group. Defaults to True.

 True
include_observed bool

If True, attach the observed spectrum as the observed_data group. Requires an active XSPEC session. Defaults to True.

 True
include_log_likelihood bool

If True, simulate the posterior samples through the instrument response and compute per-bin Poisson log-likelihoods. Required for az.compare. Defaults to True.

 True

Returns:

Type Description
InferenceData

Inference data with posterior (and optionally prior,
InferenceData

observed_data, log_likelihood) groups.

log_prob_fn(theta, x_o, from_unit_cube=False)

Return the log-posterior probability, defined as \(\mathcal{LL} = -\frac{1}{2} \texttt{Cstat}\). Include the log-likelihood and any prior term defined in xspec.

On x_o parameter

x_o is a dummy parameter used for compatibility with sbi as the true spectrum is directly extracted from xspec. sbi require this parameter as in normal workflow, this function can be conditioned on any x_o.

Parameters:

Name Type Description Default
theta

Array of samples on the unit cube.

 required
x_o

Observed value, pass None if needed.

 required

sample_parameters(n_samples, distribution_name='prior')

Draw parameter samples from one of the registered distributions.

Parameters:

Name Type Description Default
n_samples int

Number of draws to generate.

 required
distribution_name str

Key of the distribution in self.distributions. Defaults to "prior".

 'prior'

Returns:

Type Description

Raw samples returned by the selected distribution.

simulate(parameters, return_kind='full_model_counts', progress_bar=True)

Fold parameters through xspec and stack simulation outputs.

Parameters:

Name Type Description Default
parameters

Array-like batch of parameter vectors.

 required
return_kind

One of "cstat", "full_model_counts", or "models_and_components".

 'full_model_counts'

Returns:

Type Description

Stacked outputs returned by parallel_folding.

Raises:

Type Description
ValueError

If any parameter values are NaN or Inf.

likelihood_per_bin(observed, model)

Per-bin Poisson log-likelihood (Cash statistic). For a bin with observed counts \(S_i\) and predicted counts \(\mathcal{M}_i\):

\[ \log \mathcal{L}_i = S_i \ln(\mathcal{M}_i) − \mathcal{M}_i \]

where \(\mathcal{M}_i > 0\)

Parameters:

Name Type Description Default
observed ndarray

Observed counts, shape (n_bins,).

 required
model ndarray

Predicted model counts, shape (n_bins,) or (n_samples, n_bins).

 required

Returns:

Type Description
ndarray

Per-bin log-likelihood with the same shape as model.