# Uncertainties

The uncertainties package is an open source Python library for doing calculations on numbers that have uncertainties (like 3.14±0.01) that are common in many scientific fields. The calculations done with this package will propagate the uncertainties to the result of mathematical calculations. The `uncertainties` package takes the pain and complexity out of uncertainty calculations and error propagation. Here is a quick taste of how to use `uncertainties`:

    >>> from uncertainties import ufloat
    >>> x = ufloat(2, 0.1)   # x = 2+/-0.1
    >>> y = ufloat(3, 0.2)   # y = 3+/-0.2
    >>> print(2*x)
    4.00+/-0.20
    >>> print(x+y)
    5.00+/-0.22
    >>> print(x*y)
    6.0+/-0.5

The `uncertainties` library calculates uncertainties using linear error propagation theory by automatically calculating derivatives and analytically propagating these to the results. Correlations between variables are automatically handled. This library can also yield the derivatives of any expression with respect to the variables that have uncertain values. For other approaches, see soerp (using higher-order terms) and mcerp (using a Monte-Carlo approach).

The source code for the uncertainties package is licensed under the Revised BSD License. This documentation is licensed under the CC-SA-3 License.

# Version 4.0 Coming Soon

The `uncertainties` team is working on developing a new major release. This release modernizes the `uncertainties` codebase and simplifies the underlying architecture used for uncertainty propagation. These changes greatly improve the maintainability of this code base which helps guarantee its functionality and support into the future. At the heart of the architecture change is the idea that `UFloat` objects should closely resemble mathematical random variables. Here are some specific benefits from the architecture update.

- `UFloat` objects will now be immutable and hashing them will follow the python

    data model rule that two objects which are equal should have the same hash.

- Previously, `UFloat` instances did not preserve correlations upon copying,

    pickling, or any other form of serialization. Now `UFloat` instances will preserve correlations upon copying and pickling.

- Previously when users generated a number with uncertainties, the resulting object may

    have been a `Variable` or `AffineScalarFunc` instance depending on how the object was created. Now all numbers with uncertainty are uniformly represented by `UFloat` instances. `AffineScalarFunc` and `Variable` remain as legacy names for `UFloat`.

In addition to reformating the underlying architecture, this update makes a number of changes and simplifications to the API to improve consistency. Some of these API changes break backwards compatibility. Notable changes are

- Elimination of the `AffineScalarFunc.derivatives` property.

- Replacing the `AffineScalarFunc.error_components()` method with the

    `UFloat.error_components` property.

- Elimination of a number of `UFloat` instance methods and `umath` module

    functions which do not make sense for random variables such as comparison methods and modulo methods and functions. These changes are recorded in the 3.2 series changelog. These deprecated methods and functions emit warnings in the most recent `uncertainties` versions.

Note that basic usage of the `uncertainties` package including creating numbers with uncertainty and manipulating them using basic arithmetic or math methods and functions (other than those which have been removed) will still work as it did previously.

There will continue to be support for the latest version 3 release as the community transitions to the new version.

# Table of Contents

- Installation and Credits
  - Download and Installation
  - Source code and Development Version
  - Getting Help
  - Credits
  - How to cite this package
  - Acknowledgments
  - License
- User Guide
  - Basic usage
  - Creating Variables: numbers with uncertainties
  - Basic math with uncertain Variables
  - Mathematical operations with uncertain Variables
  - Comparison operators
  - Handling NaNs and infinities
  - Power Function Behavior
  - Automatic correlations
  - Access to the individual sources of uncertainty
  - Covariance and correlation matrices
  - Correlated variables
  - Making custom functions accept numbers with uncertainties
  - Miscellaneous utilities
  - Derivatives
  - Additional information
- Uncertainties and numpy arrays
  - Arrays of uncertainties Variables
  - The unumpy package
  - Storing arrays in text format
  - Additional array functions: unumpy.ulinalg
- Formatting Variables with uncertainties
  - Printing
- Advanced Topics
  - API: Application Programming Interface
  - Special Technical Topics