Uncertainties

The uncertainties package is an open source Python library for doing calculations on numbers that have uncertainties (like 3.14±0.01) that are common in many scientific fields. The calculations done with this package will propagate the uncertainties to the result of mathematical calculations. The uncertainties package takes the pain and complexity out of uncertainty calculations and error propagation. Here is a quick taste of how to use uncertainties:

>>> from uncertainties import ufloat
>>> x = ufloat(2, 0.1)   # x = 2+/-0.1
>>> y = ufloat(3, 0.2)   # y = 3+/-0.2
>>> print(2*x)
4.00+/-0.20
>>> print(x+y)
5.00+/-0.22
>>> print(x*y)
6.0+/-0.5

The uncertainties library calculates uncertainties using linear error propagation theory by automatically calculating derivatives and analytically propagating these to the results. Correlations between variables are automatically handled. This library can also yield the derivatives of any expression with respect to the variables that have uncertain values. For other approaches, see soerp (using higher-order terms) and mcerp (using a Monte-Carlo approach).

The source code for the uncertainties package is licensed under the Revised BSD License. This documentation is licensed under the CC-SA-3 License.

Version 4.0 Coming Soon

The uncertainties team is working on developing a new major release. This release modernizes the uncertainties codebase and simplifies the underlying architecture used for uncertainty propagation. These changes greatly improve the maintainability of this code base which helps guarantee its functionality and support into the future. At the heart of the architecture change is the idea that UFloat objects should closely resemble mathematical random variables. Here are some specific benefits from the architecture update.

  • UFloat objects will now be immutable and hashing them will follow the python

    data model rule that two objects which are equal should have the same hash.

  • Previously, UFloat instances did not preserve correlations upon copying,

    pickling, or any other form of serialization. Now UFloat instances will preserve correlations upon copying and pickling.

  • Previously when users generated a number with uncertainties, the resulting object may

    have been a Variable or AffineScalarFunc instance depending on how the object was created. Now all numbers with uncertainty are uniformly represented by UFloat instances. AffineScalarFunc and Variable remain as legacy names for UFloat.

In addition to reformating the underlying architecture, this update makes a number of changes and simplifications to the API to improve consistency. Some of these API changes break backwards compatibility. Notable changes are

  • Elimination of the AffineScalarFunc.derivatives property.

  • Replacing the AffineScalarFunc.error_components() method with the

    UFloat.error_components property.

  • Elimination of a number of UFloat instance methods and umath module

    functions which do not make sense for random variables such as comparison methods and modulo methods and functions. These changes are recorded in the 3.2 series changelog. These deprecated methods and functions emit warnings in the most recent uncertainties versions.

Note that basic usage of the uncertainties package including creating numbers with uncertainty and manipulating them using basic arithmetic or math methods and functions (other than those which have been removed) will still work as it did previously.

There will continue to be support for the latest version 3 release as the community transitions to the new version.

Table of Contents