PyUncertainNumber

This package is underpinned by a framework of uncertain numbers which allows for a closed computation ecosystem whereby trustworthy computations can be conducted in a rigorous manner. It provides capabilities across the typical uncertainty analysis pipeline, encompassing uncertainty characterisation, aggregation, propagation, model updating, and applications including reliability analysis and optimisation under uncertainty, especially with a focus on imprecise probabilities.

Note

Uncertain Number refers to a class of mathematical objects useful for risk analysis that generalize real numbers, intervals, probability distributions, interval bounds on probability distributions (i.e. probability boxes), and finite DempsterShafer structures. Refer to the source code repository of this package for additional introduction.

Capabilities

• PyUncertainNumber is a Python package for generic computational tasks focussing on rigorous uncertainty analysis, which provides a research-grade computing environment for uncertainty characterisation, propagation, validation and uncertainty extrapolation.

• PyUncertainNumber supports probability bounds analysis to rigorously bound the prediction for the quantity of interest with mixed uncertainty propagation.

• PyUncertainNumber also features great natural language support as such characterisation of input uncertainty can be intuitively done by using natural language like about 7 or simple expression like [15 +- 10%], without worrying about the elicitation.

• Interoperability via serialization: features the save and loading of Uncertain Number objects to work with downstream applications.

• Yields informative results during the computation process such as the combination that leads to the maximum in vertex method.

Tip

pyuncertainnumber exposes APIs at different levels. It features high-level APIs best suited for new users to quickly start with uncertainty computations with [uncertain numbers], and also low-level APIs allowing experts to have additional controls over mathematical constructs such as p-boxes, Dempster Shafer structures, probability distibutions, etc.

Quick start: uncertainty characterisation and propagation

PyUncertainNumber can be used to easily create an UncertainNumber object, which may embody a mathematical construct such as PBox, Interval, Distribution, or DempsterShafer structure.

from pyuncertainnumber import UncertainNumber as UN
import pyuncertainnumber as pun

# shortcut to create uncertain numbers
a = pun.normal([2,3], [1])
b = pun.normal([10,14], [1])

PyUncertainNumber supports a duck-typing way of doing probability arithmetic, such that users can directly compute with uncertain numbers through a Python function by drop-in replacements as if they were real numbers.

a - b * a + b**2

Besides, many propagation methodologies are provided to rigorously propagate the uncertainty through the computational pipeline, intrusively or non-intrusively.

# specify a response function
def foo(x): return x[0] ** 3 + x[1] + 2

# duck-typing signature which allows for drop-in replacements
response = foo([a, b])

# alternatively, one can use a more generic call signature suitable for black-box models
p = pun.Propagation(vars=[a, b], func=foo, method='slicing', interval_strategy='direct')
response = p.run(n_slices=50)

Attention

The libary is under active develpment, so APIs will change across different versions.

Tip

If looking for deeper controls and customisation, refer to the Low-level pba APIs for advanced usage.

Installation

Note

• See installation for additional details.

• Requirement: Python >=3.11

PyUncertainNumber can be installed from PyPI. Upon activation of your virtual environment, use your terminal. While we’d like to refer to the library as PyUncertainNumberin PascalCase, we use all lowercase (i.e. pyuncertainnumber) when installing from PyPI following PEP 8 convention. For additional details, refer to installation guide.

pip install pyuncertainnumber

UQ multiverse

UQ is a big world (like Marvel multiverse) consisting of abundant theories and software implementations on multiple platforms. Some notable examples include OpenCossan UQlab in Matlab and ProbabilityBoundsAnalysis.jl in Julia, and many others of course. We focus mainly on the imprecise probability frameworks. PyUncertainNumber is rooted in Python and has close ties with the Python scientific computing ecosystem, it builds upon and greatly extends a few pioneering projects, such as intervals, scipy-stats and pba-for-python to generalise probability and interval arithmetic. Beyond arithmetic calculations, PyUncertainNumber has offered a wide spectrum of algorithms and methods for uncertainty characterisation, propagation, surrogate modelling, and optimisation under uncertainty, allowing imprecise uncertainty analysis in both intrusive and non-intrusive manner. PyUncertainNumber is under active development and will continue to be dedicated to support imprecise analysis in engineering using Python.

Acknowledgements

PyUncertainNumber was originally developed for use in the DAWS2 project. It has the capacity to serve as a full-fleged UQ softwware to work beyond to fulfill general UQ challenges.

Citation

Yu Chen, Scott Ferson (2025). Imprecise uncertainty management with uncertain numbers to facilitate trustworthy computations., SciPy proceedings 2025.

A downloadable version can be accessed here.

@inproceedings{chen2025scipyproceed,
  title = {Imprecise uncertainty management with uncertain numbers to facilitate trustworthy computations},
  booktitle = {SciPy Proceedings},
  year = {2025},
  author = {Chen, Yu and Ferson, Scott},
  doi = {10.25080/ahrt5264}
}

@software{chen_2025_17235456,
  author       = {Chen, (Leslie) Yu},
  title        = {PyUncertainNumber},
  publisher    = {Zenodo},
  version      = {0.1.1},
  doi          = {10.5281/zenodo.17235456},
  url          = {https://doi.org/10.5281/zenodo.17235456},
}