Overview

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.

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.

Many fast operations on arrays and matrices of numbers with
uncertainties are supported.

Extensive support for printing numbers with uncertainties
(including LaTeX support and pretty-printing).

Most uncertainty calculations are performed analytically.

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).

Installation or upgrade

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

Contact

Version history

Main changes:

2.4: Extensive support for the formatting of numbers with uncertainties. A zero uncertainty is now explicitly displayed as the integer 0. The new formats are generally understood by ufloat_fromstr(). Abbreviations for the nominal value (n) and the standard deviation (s) are now available.

2.3.6: Full support for limit cases of the power operator umath.pow().

2.3.5: Uncertainties and derivatives can now be NaN (not-a-number). Full support for numbers with a zero uncertainty (sqrt(ufloat(0, 0)) now works). Full support for limit cases of the power operator (x**y).

2.3: Functions wrapped so that they accept numbers with uncertainties instead of floats now have full keyword arguments support (improved wrap() function). Incompatible change: wrap(..., None) should be replaced by wrap(...) or wrap(..., []).

2.2: Creating arrays and matrices of numbers with uncertainties with uarray() and umatrix() now requires two simple arguments (nominal values and standard deviations) instead of a tuple argument. This is consistent with the new, simpler ufloat() interface. The previous usage will be supported for some time. Users are encouraged to update their code, for instance through the newly provided code updater, which in addition now automatically converts .set_std_dev(v) to .std_dev = v.

2.1: Numbers with uncertainties are now created more directly like ufloat(3, 0.1), ufloat(3, 0.1, "pi"), ufloat_fromstr("3.0(1)"), or ufloat_fromstr("3.0(1)", "pi"). The previous ufloat((3, 0.1)) and ufloat("3.0(1)") forms will be supported for some time. Users are encouraged to update their code, for instance through the newly provided code updater.

2.0: The standard deviation is now obtained more directly without an explicit call (x.std_dev instead of x.std_dev()). x.std_dev() will be supported for some time. Users are encouraged to update their code. The standard deviation of a variable can now be directly updated with x.std_dev = 0.1. As a consequence, x.set_std_dev() is deprecated.

1.9.1: Support added for pickling subclasses of UFloat (= Variable).

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.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 the Revised BSD License instead of GPLv2, which makes it easier to include this package in other projects.

1.5.4.2: 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: 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.