# Welcome to the uncertainties package¶

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 (as with a calculator), or in programs written in the Python programming language. Existing calculation code can run with little or no change.

Whatever the complexity of a calculation, this package returns its result with an uncertainty as predicted by linear error propagation theory. It automatically calculates derivatives and uses them for calculating uncertainties. Almost all uncertainty calculations are performed analytically.

Correlations between variables are automatically handled, which sets this module apart from many existing error propagation codes.

You may want to check the following related uncertainty calculation Python packages to see if they better suit your needs: soerp (higher-order approximations) and mcerp (Monte-Carlo approach).

## An easy-to-use calculator¶

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.00+/-0.20
>>> sin(2*x)  # In a Python shell, "print" is optional
0.9092974268256817+/-0.08322936730942848
```

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+/-0
```

Many other error propagation codes return the incorrect value 0±0.1414… because they wrongly 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.

## Available documentation¶

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.

### Important note¶

The installation commands below should be run in a DOS or Unix command shell (not in a Python shell).

Under Windows (version 7 and earlier), a command shell can be obtained by running `cmd.exe` (through the Run… menu item from the Start menu). Under Unix (Linux, Mac OS X,…), a Unix shell is available when opening a terminal (in Mac OS X, the Terminal program is found in the Utilities folder, which can be accessed through the Go menu in the Finder).

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 for Windows through the Python(x,y) distribution. It may also be included in Christoph Gohlke’s Base distribution of scientific Python packages.

Mac OS X users who use the MacPorts package manager can install `uncertainties` with `sudo port install py**-uncertainties`, and upgrade it with ```sudo port upgrade py**-uncertainties``` where `**` represents the desired Python version (`27`, `33`, etc.).

The `uncertainties` package is also available through the following Linux distributions and software platforms: Ubuntu, Fedora, openSUSE, Debian and Maemo.

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
```

(where the default `python` interpreter must generally be replaced by the version of Python for which the package should be installed: `python3`, `python3.3`, etc.).

For an installation with Python 2.6+ in the user Python library (no additional access rights needed):

```python setup.py install --user
```

For an installation in a custom directory `my_directory`:

```python setup.py install --install-lib my_directory
```

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 then run `2to3 -w .` from inside this directory so as to automatically adapt the code to Python 3.

### Source code¶

The latest, bleeding-edge but working 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 7000 lines of code. 75 % of these lines are documentation strings and comments. The remaining 25 % are split between unit tests (15 % of the total) and the calculation code proper (10 % of the total). `uncertainties` is thus a lightweight, portable package with abundant documentation and tests.

## Migration from version 1 to version 2¶

Some incompatible changes were introduced in version 2 of `uncertainties` (see the version history). While the version 2 line will support the version 1 syntax for some time, it is recommended to update existing programs as soon as possible. This can be made easier through the provided automatic updater.

The automatic updater works like Python’s 2to3 updater. It can be run (in a Unix or DOS shell) with:

```python -m uncertainties.1to2
```

For example, updating a single Python program can be done with

```python -m uncertainties.1to2 -w example.py
```

All the Python programs contained under a directory `Programs` (including in nested sub-directories) can be automatically updated with

```python -m uncertainties.1to2 -w Programs
```

Backups are automatically created, unless the `-n` option is given.

Some manual adjustments might be necessary after running the updater (incorrectly modified lines, untouched obsolete syntax).

While the updater creates backup copies by default, it is generally useful to first create a backup of the modified directory, or alternatively to use some version control system. Reviewing the modifications with a file comparison tool might also be useful.

## What others say¶

• Superb,” “wonderful,” “It’s like magic.” (Joaquin Abian)
• pretty amazing” (John Kitchin)
• An awesome python package” (Jason Moore)
• Utterly brilliant” (Jeffrey Simpson)
• An amazing time saver” (Paul Nakroshis)
• Seems to be the gold standard for this kind of thing” (Peter Williams)
• This package has a great interface and makes error propagation something to stop fearing.” (Dr Dawes)
• uncertainties makes error propagation dead simple.” (enrico documentation)
• many inspiring ideas” (Abraham Lee)
• Those of us working with experimental data or simulation results will appreciate this.” (Konrad Hinsen)
• PyPI’s uncertainties rocks!” (Siegfried Gevatter)
• A very cool Python module” (Ram Rachum)
• Holy f*** this would have saved me so much f***ing time last semester.” (reddit)

## Future developments¶

Planned future developments include (starting from the most requested ones):

• handling of complex numbers with uncertainties;
• increased support for NumPy: Fourier Transform with uncertainties, automatic wrapping of functions that accept or produce arrays, standard deviation of arrays, more convenient matrix creation, new linear algebra methods (eigenvalue and QR decompositions, determinant,…), input of arrays with uncertainties as strings (like in NumPy),…;
• JSON support;
• addition of `real` and `imag` attributes, for increased compatibility with existing code (Python numbers have these attributes);
• addition of new functions from the `math` module;
• fitting routines that conveniently handle data with uncertainties;
• a re-correlate function that puts correlations back between data that was saved in separate files;
• support for multi-precision numbers with uncertainties.

Call for contributions: I got multiple requests for complex numbers with uncertainties, Fourier Transform support, and the automatic wrapping of functions that accept or produce arrays. Please contact me if you are interested in contributing. Patches are welcome. They must have a high standard of legibility and quality in order to be accepted (otherwise it is always possible to create a new Python package by branching off this one, and I would still be happy to help with the effort).

Please support the continued development of this program by donating \$10 or more through PayPal (no PayPal account necessary). I love modern board games, so this will go towards giving my friends and I some special gaming time!

## Contact¶

Feature requests, bug reports, or feedback are much welcome. They can be sent to the creator of `uncertainties`, Eric O. LEBIGOT (EOL).

## How to cite this package¶

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://pythonhosted.org/uncertainties/. Adding the version number is optional.

## Acknowledgments¶

The author wishes to thank all the people who made generous donations: they help keep this project alive by providing positive feedback.

I greatly appreciate having gotten key technical input from Arnaud Delobelle, Pierre Cladé, and Sebastian Walter. Patches by Pierre Cladé, Tim Head, José Sabater Montes, Martijn Pieters, Ram Rachum, Christoph Deil, Gabi Davar and Roman Yurchak are gratefully acknowledged.

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, Matt Newville, Matthew Peel, Don Peterson, Mika Pflueger, Albert Puig, Abraham Lee, Arian Sanusi, Martin Laloux, Jonathan Whitmore, Federico Vaggi, Marco A. Ferra, Hernan Grecco, David Zwicker, James Hester, Andrew Nelson, and many others.

I am also grateful to Gabi Davar and Pierre Raybaut for including it in Python(x,y), to Christoph Gohlke for including it in his Base distribution of scientific Python packages for Windows, and to the Anaconda, macOS and Linux distribution maintainers of this package (Jonathan Stickel, David Paleino, Federico Ceratto, Roberto Colistete Jr, Filipe Pires Alvarenga Fernandes, and Felix Yan).