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

## Project description

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

## Basic examples

>>> from uncertainties import ufloat >>> x = ufloat(2, 0.25) >>> x 2.0+/-0.25 >>> square = x**2 # Transparent calculations >>> square 4.0+/-1.0 >>> square.nominal_value 4.0 >>> square.std_dev # Standard deviation 1.0 >>> square - x*x 0.0 # Exactly 0: correlations taken into account >>> from uncertainties.umath import * # sin(), etc. >>> sin(1+x**2) -0.95892427466313845+/-0.2836621854632263 >>> print (2*x+1000).derivatives[x] # Automatic calculation of derivatives 2.0 >>> from uncertainties import unumpy # Array manipulation >>> random_vars = unumpy.uarray([1, 2], [0.1, 0.2]) >>> print random_vars [1.0+/-0.1 2.0+/-0.2] >>> print random_vars.mean() 1.50+/-0.11 >>> print unumpy.cos(random_vars) [0.540302305868+/-0.0841470984808 -0.416146836547+/-0.181859485365]

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

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

## Version history

Main changes:

- 3.0: Massive speedup for some operations involving large numbers of numbers with uncertainty, like
`sum(ufloat(1, 1) for _ in xrange(100000))`(this is about 5,000 times faster than before). - 2.4.8: Friendlier completions in Python shells, etc.: internal functions should not appear anymore (for the user modules:
`uncertainties`,`uncertainties.umath`and`uncertainties.unumpy`). Parsing the shorthand notation (e.g.`3.1(2)`) now works with infinite values (e.g.`-inf(inf)`); this mirrors the ability to print such numbers with uncertainty. The Particle Data Group rounding rule is applied in more cases (e.g. printing 724.2±26.2 now gives`724±26`). The shorthand+LaTeX formatting of numbers with an infinite nominal value is fixed.`uncertainties.unumpy.matrix`now uses`.std_devs`instead of`.std_devs()`, for consistency with floats with uncertainty (automatic conversion of code added to`uncertainties.1to2`). - 2.4.7: String formatting now works for
`(-)inf+/-...`numbers. - 2.4.5: String formatting now works for
`NaN+/-...`numbers. - 2.4.4: The documentation license now allows its commercial use.
- 2.4.2: NumPy 1.8 compatibility.
- 2.4.1: In
`uncertainties.umath`, functions`ceil()`,`floor()`,`isinf()`,`isnan()`and`trunc()`now return values of the same type as the corresponding`math`module function (instead of generally returning a value with a zero uncertainty`...+/-0`). - 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.8: Compatibility with Python 3.2 added.
- 1.7.2: Compatibility with Python 2.3, Python 2.4, Jython 2.5.1 and Jython 2.5.2 added.
- 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.2:
`float_u`,`array_u`and`matrix_u`renamed`ufloat`,`uarray`and`umatrix`, for ease of typing. - 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. - 1.4.5: Added support for the standard
`pickle`module. - 1.4.2: Added support for the standard
`copy`module. - 1.4: Added utilities for manipulating NumPy arrays of numbers with
uncertainties (
`array_u`,`nominal_values`and`std_devs`). - 1.3: Numbers with uncertainties are now constructed with
`num_with_uncert()`, which replaces`NumberWithUncert()`. This simplifies the class hierarchy by removing the`NumberWithUncert`class. - 1.2.5: Numbers with uncertainties can now be entered as
`NumberWithUncert("1.23+/-0.45")`too. - 1.2.3:
`log(x, base)`is now supported by`umath.log()`, in addition to`log(x)`. - 1.2.2: Values with uncertainties are now output like 3+/-1, in order to avoid confusing 3+-1 with 3+(-1).
- 1.2: A new function,
`wrap()`, is exposed, which allows non-Python functions (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()`.

## Project details

## Release history Release notifications

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help | File type | Python version | Upload date |
---|---|---|---|

uncertainties-3.0.3.tar.gz (232.2 kB) Copy SHA256 hash SHA256 | Source | None |