uncertainties 1.2

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

uncertainties allows calculations such as (0.2 +/- 0.01)*2 = 0.4 +/- 0.02 to be performed transparently; much more complex mathematical expressions involving numbers with uncertainties can also be evaluated transparently.

Correlations between expressions are correctly taken into account. x-x is thus exactly zero, for instance (more naive implementations found on the web yield a non-zero uncertainty for x-x, which is incorrect). Whatever the complexity of the calculation and the number of steps involved, the uncertainties produced by this program are what is predicted by error propagation theory.

Basic examples:

import uncertainties
from uncertainties.umath import *  # sin(), etc.

# Mathematical operations:
x = uncertainties.NumberWithUncert((0.20, 0.01))  # x = 0.20+-0.01
x = uncertainties.NumberWithUncert("0.20(1)")  # Other representation
print x**2  # Square: prints "0.04+-0.004"
print sin(x**2)  # Prints "0.0399...+-0.00399..."

print x.position_in_sigmas(0.17)  # Prints "-3.0": deviation of -3 sigmas

# Access to the nominal value, and to the uncertainty:
square = x**2  # Square
print square  # Prints "0.04+-0.004"
print square.nominal_value  # Prints "0.04"
print square.std_dev()  # Prints "0.004..."

print square.derivatives[x]  # Partial derivative: prints "0.4" (= 2*0.20)

print square - x*x  # Exactly zero: correlations taken into account

The Python (or IPython) shell can thus be used as a powerful calculator that handles quantities with uncertainties (print statements are optional, which is convenient).

Almost all mathematical operations are supported, including most functions from the standard math module (sin,…) and functions from the third-party numpy module (fast operations on arrays and matrices). Comparison operators (>, ==, etc.) are supported too. There is no restriction on the complexity of mathematical expressions, or on the number of variables involved (x-sin(x)+y**2-tan(y*x) can for example be calculated, whether x and y are quantities with uncertainties or not).

Another possible use of this module is the calculation of partial derivatives of mathematical functions.

Additional examples and information can be obtained with pydoc uncertainties and pydoc uncertainties.umath after installation.

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

Installation: sudo easy_install uncertainties might be sufficient, depending on your installation (this does not require any manual download, but requires setuptools). For additional installation methods, download the source archive, and see the README.txt file that it contains.

Version history (main changes only):

• 1.2: a new function, wrap(), is exposed, which allows non-Python code (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().