skip to navigation
skip to content

uncertainties 1.9

Transparent calculations with uncertainties on the quantities involved (aka "error propagation"); fast calculation of derivatives

Package Documentation

Latest Version: 3.0.2


uncertainties allows calculations such as (2 +/- 0.1)*2 = 4 +/- 0.2 to be performed transparently. Much more complex mathematical expressions involving numbers with uncertainties can also be evaluated directly.

The uncertainties package takes the pain and complexity out of uncertainty calculations.

Detailed information about this package can be found on its main website.

Basic examples

>>> from uncertainties import ufloat

>>> x = ufloat((2, 0.25))
>>> x

>>> square = x**2  # Transparent calculations
>>> square
>>> square.nominal_value
>>> square.std_dev()  # Standard deviation

>>> square - x*x
0.0  # Exactly 0: correlations taken into account

>>> from uncertainties.umath import *  # sin(), etc.
>>> sin(1+x**2)

>>> print (2*x+1000).derivatives[x]  # Automatic calculation of derivatives

>>> from uncertainties import unumpy  # Array manipulation
>>> random_vars = unumpy.uarray(([1, 2], [0.1, 0.2]))
>>> print random_vars
[1.0+/-0.1 2.0+/-0.2]
>>> random_vars.mean()
>>> print unumpy.cos(random_vars)
[0.540302305868+/-0.0841470984808 -0.416146836547+/-0.181859485365]

Main features

  • Transparent calculations with uncertainties: no or little modification of existing code is needed. Similarly, the Python (or IPython) shell can be used as a powerful calculator that handles quantities with uncertainties (print statements are optional, which is convenient).
  • Correlations between expressions are correctly taken into account. Thus, x-x is exactly zero, for instance (most implementations found on the web yield a non-zero uncertainty for x-x, which is incorrect).
  • Almost all mathematical operations are supported, including most functions from the standard math module (sin,…). Comparison operators (>, ==, etc.) are supported too.
  • This module also gives access to the derivatives of any mathematical expression (they are used by error propagation theory, and are thus automatically calculated by this module).
  • Many fast operations on arrays and matrices of numbers with uncertainties are supported.
  • Most uncertainty calculations are performed analytically.

Installation or upgrade

Installation instructions are available on the main web site for this package.


Please send feature requests, bug reports, or feedback to Eric O. LEBIGOT (EOL).

Version history

Main changes:

  • 1.9: Added functions for handling correlation matrices: correlation_matrix() and correlated_values_norm(). (These new functions mirror the covariance-matrix based covariance_matrix() and correlated_values().) UFloat.position_in_sigmas() is now named UFloat.std_score(), so as to follow the common naming convention (standard score). Obsolete functions were removed (from the main module: NumberWithUncert, num_with_uncert, array_u, nominal_values, std_devs).
  • 1.8: Compatibility with Python 3.2 added.
  • 1.7.2: Compatibility with Python 2.3, Python 2.4, Jython 2.5.1 and Jython 2.5.2 added.
  • 1.7.1: New semantics: ufloat('12.3(78)') now represents 12.3+/-7.8 instead of 12.3+/-78.
  • 1.7: ufloat() now raises ValueError instead of a generic Exception, when given an incorrect string representation, like float() does.
  • 1.6: Testing whether an object is a number with uncertainty should now be done with isinstance(..., UFloat). AffineScalarFunc is not imported by from uncertainties import * anymore, but its new alias UFloat is.
  • 1.5.5: The first possible license is now BSD instead of GPLv2, which makes it easier to include this package in other projects.
  • Added umath.modf() and umath.frexp().
  • 1.5.4: ufloat does not accept a single number (nominal value) anymore. This removes some potential confusion about ufloat(1.1) (zero uncertainty) being different from ufloat("1.1") (uncertainty of 1 on the last digit).
  • 1.5.2: float_u, array_u and matrix_u renamed ufloat, uarray and umatrix, for ease of typing.
  • 1.5: Added functions nominal_value and std_dev, and modules unumpy (additional support for NumPy arrays and matrices) and unumpy.ulinalg (generalization of some functions from numpy.linalg). Memory footprint of arrays of numbers with uncertainties divided by 3. Function array_u is 5 times faster. Main function num_with_uncert renamed float_u, for consistency with unumpy.array_u and unumpy.matrix_u, with the added benefit of a shorter name.
  • 1.4.5: Added support for the standard pickle module.
  • 1.4.2: Added support for the standard copy module.
  • 1.4: Added utilities for manipulating NumPy arrays of numbers with uncertainties (array_u, nominal_values and std_devs).
  • 1.3: Numbers with uncertainties are now constructed with num_with_uncert(), which replaces NumberWithUncert(). This simplifies the class hierarchy by removing the NumberWithUncert class.
  • 1.2.5: Numbers with uncertainties can now be entered as NumberWithUncert("1.23+/-0.45") too.
  • 1.2.3: log(x, base) is now supported by umath.log(), in addition to log(x).
  • 1.2.2: Values with uncertainties are now output like 3+/-1, in order to avoid confusing 3+-1 with 3+(-1).
  • 1.2: A new function, wrap(), is exposed, which allows non-Python functions (e.g. Fortran or C used through a module such as SciPy) to handle numbers with uncertainties.
  • 1.1: Mathematical functions (such as cosine, etc.) are in a new uncertainties.umath module; they do not override functions from the math module anymore.
  • 1.0.12: Main class (Number_with_uncert) renamed NumberWithUncert so as to follow PEP 8.
  • 1.0.11: origin_value renamed more appropriately as nominal_value.
  • 1.0.9: correlations() renamed more appropriately as covariance_matrix().
File Type Py Version Uploaded on Size
uncertainties-1.9.tar.gz (md5) Source 2012-11-23 124KB