The uncertainties package is a free, cross-platform program that transparently handles calculations with numbers with uncertainties (like 3.14±0.01). It can also yield the derivatives of any expression.
The uncertainties package takes the pain and complexity out of uncertainty calculations. Error propagation is not to be feared anymore!
Calculations of results with uncertainties, or of derivatives, can be performed either in an interactive session, or in programs written in the Python programming language. Existing calculation code can run with no or little change.
Whatever the complexity of the calculation, this package returns the result with its uncertainty as predicted by linear error propagation theory. It automatically calculates derivatives and uses them for calculating uncertainties. Correlations between variables are thus autoamatically handled, which sets it apart from many existing error propagation codes.
Let’s now see how to use these unique features!
Calculations involving numbers with uncertainties can be performed even without knowing anything about the Python programming language. After installing this package and invoking the Python interpreter, calculations with automatic error propagation can be performed transparently (i.e., through the usual syntax for mathematical formulas):
>>> from uncertainties import ufloat
>>> from uncertainties.umath import * # sin(), etc.
>>> x = ufloat((1, 0.1)) # x = 1+/-0.1
>>> print 2*x
2.0+/-0.2
>>> sin(2*x) # In a Python shell, "print" is optional
0.90929742682568171+/-0.083229367309428481
Thus, existing calculation code designed for regular numbers can run with numbers with uncertainties with no or little modification.
Another strength of this package is its correct handling of correlations. For instance, the following quantity is exactly zero even though x has an uncertainty:
>>> x-x
0.0
Many other error propagation codes return the incorrect value 0±0.1414… because they assume that the two subtracted quantities are independent random variables.
Arrays of numbers with uncertainties are transparently handled too.
Derivatives are similarly very easy to obtain:
>>> (2*x+1000).derivatives[x]
2.0
They are calculated with a fast method.
The User Guide details many of the features of this package.
The part Uncertainties in arrays describes how arrays of numbers with uncertainties can be created and used.
The Technical Guide gives advanced technical details.
A PDF version of the documentation is also available.
Additional information is available through the pydoc command, which gives access to many of the documentation strings included in the code.
One of the automatic installation or upgrade procedures below might work on your system, if you have a Python package installer or use certain Linux distributions.
Under Unix, it may be necessary to prefix the commands below with sudo, so that the installation program has sufficient access rights to the system.
If you have pip, you can try to install the latest version with
pip install --upgrade uncertainties
If you have setuptools, you can try to automatically install or upgrade this package with
easy_install --upgrade uncertainties
The uncertainties package is also available on the following Linux distributions and software platforms: Ubuntu, openSUSE, Debian and Maemo. It may also be included in Christoph Gohlke’s Base distribution of scientific Python packages for Windows.
Alternatively, you can simply download the package archive from the Python Package Index (PyPI) and unpack it. The package can then be installed by going into the unpacked directory (uncertainties-…), and running the provided setup.py program with
python setup.py install
or, for an installation in the user Python library (no additional access rights needed):
python setup.py install --user
or, for an installation in a custom directory my_directory:
python setup.py install --install-lib my_directory
or, if additional access rights are needed (Unix):
sudo python setup.py install
You can also simply move the uncertainties-py* directory that corresponds best to your version of Python to a location that Python can import from (directory in which scripts using uncertainties are run, etc.); the chosen uncertainties-py* directory should then be renamed uncertainties. Python 3 users should finally run 2to3 -w uncertainties so as to automatically adapt the code to Python 3.
The latest code and documentation source are available on GitHub. The uncertainties package is written in pure Python and has no external dependency (the NumPy package is optional). It contains about 4000 lines of code. 75 % of those lines are documentation strings and comments. The remaining 25 % are equally split between unit tests and the calculation code proper. uncertainties is thus a lightweight, portable package with abundant documentation and tests.
Planned future developments include:
Please support the continued development of this program by donating $10 or more through PayPal (no PayPal account necessary)!
Please send feature requests, bug reports, or feedback to the creator of uncertainties, Eric O. LEBIGOT (EOL).
If you use this package for a publication (in a journal, on the web, etc.), please cite it by including as much information as possible from the following: Uncertainties: a Python package for calculations with uncertainties, Eric O. LEBIGOT, http://packages.python.org/uncertainties. Adding the version number is optional.
The author wishes to thank all the people who made generous donations: they help keep this project alive by providing positive feedback.
I would also like to thank users who contributed with feedback and suggestions, which greatly helped improve this program: Joaquin Abian, Jason Moore, Martin Lutz, Víctor Terrón and many others.
I greatly appreciated getting key technical input from Arnaud Delobelle, Pierre Cladé, and Sebastian Walter. Patches by Pierre Cladé, Tim Head, and José Sabater Montes are gratefully acknowledged.
I am also grateful to the Linux distribution maintainers of this package, and to Christoph Gohlke for including it in his Base distribution of scientific Python packages for Windows.
This software is released under a dual license; one of the following options can be chosen: