UQPyL: Uncertainty Quantification Python Lab

English | 中文 | Documentation

UQPyL is a Python library for uncertainty quantification, optimization, inference, calibration, and surrogate modeling. It defines problems once and reuses them across UQ workflows.

What UQPyL solves

UQPyL provides a shared problem interface for common uncertainty quantification workflows.

Define the model or decision problem once, then reuse it for:

• design of experiments
• sensitivity and uncertainty analysis
• optimization
• Bayesian-style inference
• model calibration
• surrogate modeling

After a problem is defined, all UQPyL modules can work with the same object and remain connected across workflows.

Problem abstraction

Problem is the main entry point of UQPyL. It turns a model, benchmark function, or decision task into a reusable object that other modules can use.

To build a Problem, define:

For example:

import numpy as np

from UQPyL.problem import Problem


def objFunc(X):
    X = np.atleast_2d(X)
    return np.sum(X**2, axis=1, keepdims=True)


problem = Problem(
    # Input space
    nInput=2, lb=-1.0, ub=1.0,

    # Evaluation rule
    nObj=1, objFunc=objFunc,

    # Additional information
    optType="min", name="Sphere2D",
)

This is enough for workflows that only need evaluated objectives or constraints, including DOE, analysis, optimization, inference, and surrogate modeling.

For many hydrological simulation problems, the workflow needs more than final objective values. Calibration and uncertainty analysis may need the simulated and observed time series, and the valid observation mask to remain available throughout the method.

ModelProblem extends Problem for this case. It adds:

Use Problem by default. Use ModelProblem when a method needs simulation-process semantics, such as calibration methods that compare sim with obs. See the documentation for detailed usage.

For hydrological applications, the hard part is often not the UQ algorithm itself, but connecting an external model, preparing inputs, running simulations, and collecting outputs. hydroPilot is designed for that model-operation layer. It can be used with UQPyL when you want hydroPilot to manage hydrological model runs and UQPyL to handle sampling, analysis, calibration, optimization, inference, or surrogate modeling.

Architecture overview

UQPyL is organized around one shared problem abstraction and a set of functional modules built around it.

Quick start

Optimization with Problem

import numpy as np

from UQPyL.problem import Problem
from UQPyL.optimization.soea import SCE_UA


def objFunc(X):
    X = np.atleast_2d(X)
    return np.sum(X**2, axis=1, keepdims=True)


problem = Problem(
    nInput=2, nObj=1,
    ub=1.0, lb=-1.0,
    objFunc=objFunc, optType="min",
    name="Sphere2D",
)

algorithm = SCE_UA(maxFEs=200)

result = algorithm.run(problem, seed=123)

print(result.bestDecs)
print(result.bestObjs)

Calibration with ModelProblem

import numpy as np

from UQPyL.calibration import GLUE
from UQPyL.problem import ModelProblem

obs = np.array([1.0, 2.0, 3.0])


def simFunc(X):
    X = np.atleast_2d(X)
    # Here we assume each parameter sample returns one simulated series
    # with 3 time steps, so the output shape is (n_samples, 3).
    sim = np.zeros((X.shape[0], 3))
    sim[:, 0] = X[:, 0] * 1.0
    sim[:, 1] = X[:, 0] * 2.0
    sim[:, 2] = X[:, 0] * 3.0
    return sim


problem = ModelProblem(
    nInput=1, nObj=1,
    lb=0.0, ub=2.0,
    simFunc=simFunc, obs=obs,
    name="LinearScaleModel",
)

X = np.linspace(0.5, 1.5, 32).reshape(-1, 1)
result = GLUE(metric="rmse").run(problem, X, threshold=0.2)

Modules at a glance

The table lists representative methods, not the full API. See the documentation for complete module-specific usage and API details.

Runtime output and saving

Most runnable methods expose three common runtime controls.

algorithm = SCE_UA(maxFEs=200, verboseFlag=True, logFlag=True, saveFlag=True)
result = algorithm.run(problem, seed=123)

Example terminal output:

Algorithm: SCE-UA
Problem: Sphere2D
nInput: 2
nObj: 1
maxFEs: 200
maxIters: 1000
SCE-UA | iter=10 eval=84 best=4.3210e-03 cv=0 time=0.0s
SCE-UA | iter=20 eval=154 best=2.1500e-04 cv=0 time=0.0s
Optimization finished
  algorithm        : SCE-UA
  status           : finished
  iterations       : 27
  evaluations      : 203
  best value       : 1.0000e-04
  best X           : [1.0000e-02, -0.0000e+00]
  constraint viol. : 0
  elapsed          : 0.0s

With saveFlag=True, a run can produce saved artifacts for later reading by module-specific readers.

More examples

Sensitivity analysis with Sobol:

import numpy as np

from UQPyL.analysis import Sobol
from UQPyL.doe import SaltelliDesign
from UQPyL.problem import Problem

def objFunc(X):
    X = np.atleast_2d(X)
    y = np.sin(X[:, 0]) + 7 * np.sin(X[:, 1])**2 + 0.1 * X[:, 2]**4 * np.sin(X[:, 0])
    return y[:, None]

problem = Problem(
    nInput=3, nObj=1,
    lb=-np.pi, ub=np.pi,
    objFunc=objFunc, name="Ishigami",
)

X, meta = SaltelliDesign(secondOrder=True).sampleWithMeta(problem, 512)
Y = problem.evaluate(X, target="objs").objs
result = Sobol(verboseFlag=False).analyze(problem, X, Y, meta=meta, target="objs")

Installation

UQPyL requires Python 3.10 or newer.

The development branch targets CPython 3.10–3.14; CI builds and tests installed wheels on Linux, Windows, and macOS. Python 3.14 support does not include free-threaded builds.

pip install -U UQPyL

With plotting utilities:

pip install -U "UQPyL[viz]"

From source:

git clone https://github.com/smasky/UQPyL.git
cd UQPyL
pip install .

Citation

For UQPyL 2.0, please cite the preprint:

Wu, M., Sun, R., Xu, P., Yang, X., Hu, P., & Duan, Q. UQPyL 2.0: An Open-Source Python Package for Uncertainty Quantification and Optimization. Available at SSRN: https://ssrn.com/abstract=5393295 or http://dx.doi.org/10.2139/ssrn.5393295

@misc{wu2025uqpyl2,
  title = {UQPyL 2.0: An Open-Source Python Package for Uncertainty Quantification and Optimization},
  author = {Wu, Mengtian and Sun, Ruochen and Xu, Pengcheng and Yang, Xu and Hu, Pengjie and Duan, Qingyun},
  year = {2025},
  note = {SSRN preprint},
  doi = {10.2139/ssrn.5393295},
  url = {https://ssrn.com/abstract=5393295}
}

For UQPyL 1.0, please cite:

Wang, C., Duan, Q., Tong, C. H., Di, Z., & Gong, W. (2016). A GUI platform for uncertainty quantification of complex dynamical models. Environmental Modelling & Software, 76, 1-12. https://doi.org/10.1016/j.envsoft.2015.11.004

@article{wang2016uqpyl,
  title = {A GUI platform for uncertainty quantification of complex dynamical models},
  author = {Wang, Chen and Duan, Qingyun and Tong, Charles H. and Di, Zhenhua and Gong, Wei},
  journal = {Environmental Modelling & Software},
  volume = {76},
  pages = {1--12},
  year = {2016},
  doi = {10.1016/j.envsoft.2015.11.004}
}

Contributing

Contributions are welcome. Useful areas include new algorithms, model interfaces, benchmark problems, examples, tests, and documentation improvements.

License

UQPyL is released under the MIT License. See LICENSE.md.