styne 0.2.2

Pre-1.0 (v0.2.2)

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.

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.