styne 0.2.0

A Python library for high-dimensional Bayesian inference

Pre-1.0 (v0.2.0)

A Python library for Bayesian inference designed for high-dimensional problems and computationally expensive forward models.

The library separates forward models from inference algorithms through a small set of interfaces. Existing simulators, PDE solvers and other application-specific models can therefore be combined with any compatible sampler, while new inference algorithms can be developed independently of the underlying model implementation.

This architecture naturally supports Gaussian-process priors, including the DNA parametrisation, latent Gaussian models such as spatial GLMMs, surrogate-assisted algorithms such as DART, and hierarchical Bayesian models. These are not separate frameworks but compositions of the same underlying interfaces and components.

Install

Requires Python 3.10+.

pip install styne

The example scripts save plots and require the plotting extra:

pip install styne[plotting]

Quickstart

The runnable version is examples/01_quickstart.py, showing a minimal Bayesian linear regression example end to end. The essential wiring is summarised below.

# prior definition
priorCov = IIDCovarianceMatrix(2, 6.0)
prior = Gaussian(priorCov, mean=Vector(np.zeros(2)))

# likelihood definition
noiseModel = GaussianResponse(IIDCovarianceMatrix(nObs, noiseVar))
forwardModel = LinearModel(features)
likelihood = RegressionLikelihood(data, forwardModel, noiseModel)

# posterior definition
posterior = UnnormalisedPosterior(prior, likelihood)

# MCMC setup
factory = MRWFactory()
factory.target = posterior
factory.proposalCovariance = DiagonalCovarianceMatrix([0.02, 0.08])

sampler = factory.create()

# run MCMC
nSteps = 20000
initState = Vector(np.zeros(2))
sampler.run(nSteps, initState)

The example is intentionally assembled from interchangeable components. Most objects shown here can be replaced independently, either by alternative library implementations or by user-defined ones implementing the corresponding interface, without changing the surrounding code. The principal extension points are custom forward models (Model), likelihoods (LikelihoodInterface) and samplers (MCMCSampler).

Usage

Start with the four runnable examples in examples/.

• 01_quickstart.py: Bayesian linear regression, the shortest complete wiring from prior to posterior.
• 02_gp.py: interchangeable Gaussian-process representations.
• 03_sglmm.py: a spatial GLMM with Poisson observations.
• 04_pde_inverse_problem.py: a custom PDE inverse problem.

Components

Sampling algorithms. Random-walk Metropolis, MALA, pCN, pMALA, multilevel delayed acceptance (MLDA), and DART, a surrogate-assisted delayed-acceptance algorithm developed alongside the library.

Gaussian-process simulation and priors. Dense Cholesky, B-spline and DNA parametrisations provide interchangeable ways to sample Gaussian-process realisations, evaluate them on spatial grids and use the corresponding Gaussian measures as priors in Bayesian inverse problems. DNA is particularly useful when efficient simulation of high-dimensional Gaussian fields is itself part of the workflow.

Models. Ready-to-use implementations of Bayesian linear regression and spatial GLMMs, together with the Model interface for wrapping arbitrary application-specific forward models, including expensive PDE solvers and other simulators.

Infrastructure. Common factory interfaces, automatic proposal tuning, and composable abstractions for hierarchical and multilevel Bayesian models.

Design

Parameter ..> Model ---+
                       |
ResponseFamily --------+--> Likelihood ---+
                       |                  |
Data ------------------+                  |
                                          |
GaussianProcess --> Prior ----------------+
                                          |
                                          +--> Posterior --> Sampler

Model, ResponseFamily and Data compose into the Likelihood. GaussianProcess builds the Prior. Prior and Likelihood compose into the Posterior, and the Sampler targets it.

This diagram shows the simplest configuration: a single Gaussian-process prior and a single sampler. The same composition naturally extends to directly sampled priors, hierarchical models with hyperpriors, multilevel methods, and the other sampling algorithms provided by the library.

The architecture separates models, likelihoods, priors and samplers along clear constructor boundaries. Each component depends only on the interfaces of its immediate neighbours, allowing individual parts of a Bayesian model to evolve independently.

This supports two complementary workflows. Existing simulators and forward models can be wrapped in a Model subclass and immediately used with every compatible sampler. Conversely, new inference algorithms can be developed against the density interfaces without knowledge of, or dependence on, individual models.

In many uncertainty-quantification problems the forward model dominates the computational cost. The Model interface therefore acts as the communication boundary between the parameter space and the expensive computation producing the model prediction. Surrogate-assisted methods such as DART are designed around this boundary.

Mathematical correspondence

This section describes the particular factorisation of a Bayesian sampling problem represented by the styne interfaces.

Mathematical object	Role in the formulation	styne object	Examples
Parameter	Coordinate representation of the unknown	Parameter, Vector, Function, BlockParameter	regression coefficients; latent GP coefficients; PDE coefficient representation
Prior / reference measure	Distribution before conditioning on data, or reference measure for a target	ProbabilityMeasure, Gaussian, gp.measure	IID Gaussian prior in the quickstart; DNA Gaussian-process prior in the PDE example; latent-field prior in hierarchical SGLMMs
Model evaluation / predictor	Deterministic quantity computed from the parameter and passed to the response family	Model	LinearModel; SGLMM; custom EllipticForwardModel
Response family / measurement model	Conditional law of observations given the model evaluation	ResponseFamily	GaussianResponse; PoissonResponse; BinomialResponse
Likelihood	Data-dependent log-density contribution	LikelihoodInterface, RegressionLikelihood, SGLMMLikelihood	Gaussian regression likelihood; Poisson SGLMM likelihood
Target	Measure or unnormalised density sampled by an algorithm	DensityInterface, RadonNikodym, UnnormalisedPosterior	UnnormalisedPosterior(prior, likelihood); RadonNikodym(prior, likelihood); direct targets such as GaussianDensity and GaussianMixtureDensity
Markov transition / sampler	Transition mechanism targeting the chosen measure or density	MCMCSampler, GibbsSampler, MetropolisHastings	MRW in the quickstart; MALA for the SGLMM; pCN for the PDE inverse problem; DART and Gibbs samplers in the manuscript examples

The main compression is the Model interface. Mathematically, one may separate a forward map $\mathcal{G}$, an observation functional $F$, and a response model. In styne, the model returns the deterministic quantity passed to the response family, corresponding at the software boundary to $F(\mathcal{G}(\theta))$. Its internals may contain interpolation, a PDE solve, a simulator or any other application-specific computation. The model owns the deterministic computation, while the response family owns the observation law.

The Gaussian-process layer follows a similar convention. A GaussianProcess combines a covariance function with a parametrisation engine. The engine maps white-noise coordinates to a GP realisation, while gp.measure supplies the corresponding Gaussian reference measure. Dense Cholesky, B-spline and DNA are therefore different parametrisations of the prior, not different model classes.

Citation

If you use styne in academic work, please cite the archived version on Zenodo: . The DOI resolves to the latest archived release. For exact reproducibility, please cite the DOI of the specific release version used.

Licence

MIT. See LICENSE.