Package: uncertainties
Overviewuncertaintiesallowscalculationssuch as (2 +/- 0.1)*2 = 4 +/-
0.2 to beperformed transparently.  Much more complex mathematical
expressions involving numbers with uncertainties can also be evaluated
directly.Theuncertaintiespackagetakes the pain and complexity outof uncertainty calculations.Detailed informationabout this package can be found on itsmain
website.Basic examples>>>fromuncertaintiesimportufloat>>>x=ufloat(2,0.25)>>>x2.0+/-0.25>>>square=x**2# Transparent calculations>>>square4.0+/-1.0>>>square.nominal_value4.0>>>square.std_dev# Standard deviation1.0>>>square-x*x0.0# Exactly 0: correlations taken into account>>>fromuncertainties.umathimport*# sin(), etc.>>>sin(1+x**2)-0.95892427466313845+/-0.2836621854632263>>>print(2*x+1000).derivatives[x]# Automatic calculation of derivatives2.0>>>fromuncertaintiesimportunumpy# Array manipulation>>>random_vars=unumpy.uarray([1,2],[0.1,0.2])>>>printrandom_vars[1.0+/-0.12.0+/-0.2]>>>printrandom_vars.mean()1.50+/-0.11>>>printunumpy.cos(random_vars)[0.540302305868+/-0.0841470984808-0.416146836547+/-0.181859485365]Main featuresTransparent calculations with uncertainties:no or little
modification of existing codeis needed.  Similarly, thePython(orIPython) shell can be used asa powerful calculatorthat
handles quantities with uncertainties (printstatements are
optional, which is convenient).Correlationsbetween expressions are correctly taken into
account.  Thus,x-xis exactly zero, for instance (most
implementations found on the web yield a non-zero uncertainty forx-x, which is incorrect).Almost all mathematical operationsare supported, including most
functions from the standardmathmodule (sin,…).  Comparison
operators (>,==, etc.) are supported too.Manyfast operations on arrays and matricesof numbers with
uncertainties are supported.Extensive support for printingnumbers with uncertainties
(including LaTeX support and pretty-printing).Most uncertainty calculations are performedanalytically.This module also gives access to thederivativesof any
mathematical expression (they are used by error
propagation theory, and are thus automatically calculated by this
module).Installation or upgradeInstallation instructions are available on themain web sitefor this package.ContactPlease sendfeature requests, bug reports, or feedbacktoEric O.LEBIGOT (EOL).Version historyMain changes:3.1.6: The pretty-print and LaTeX format can now be customized.3.1.5: Added a “p” formatting option, that makes sure that there are always
parentheses around the … ± … part of printed numbers.3.1.4: Python 2.7+ is now required.3.1.2: Fix for NumPy 1.17 andunumpy.ulinalg.pinv().3.1: Variables built through a correlation or covariance matrix, and that
have uncertainties that span many orders of magnitude are now
calculated more accurately (improvedcorrelated_values()andcorrelated_values_norm()functions).3.0: Massive speedup for some operations involving large numbers of numbers with uncertainty, likesum(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.umathanduncertainties.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 gives724±26). The shorthand+LaTeX formatting of numbers with an infinite nominal value is fixed.uncertainties.unumpy.matrixnow uses.std_devsinstead of.std_devs(), for consistency with floats with uncertainty (automatic conversion of code added touncertainties.1to2).2.4.7: String formatting now works for(-)inf+/-...numbers.2.4.5: String formatting now works forNaN+/-...numbers.2.4.4: The documentation license now allows its commercial use.2.4.2:NumPy 1.8 compatibility.2.4.1: Inuncertainties.umath, functionsceil(),floor(),isinf(),isnan()andtrunc()now return values of
the same type as the correspondingmathmodule function
(instead of generally returning a value with a zero uncertainty...+/-0).2.4: Extensive support for theformattingof numbers with uncertainties.
A zero uncertainty is now explicitly displayed as the integer 0.
The new formats are generally understood byufloat_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 operatorumath.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
(improvedwrap()function). Incompatible change:wrap(...,None)should be replaced bywrap(...)orwrap(...,[]).2.2: Creating arrays and matrices of numbers with uncertainties
withuarray()andumatrix()now requires two simple arguments
(nominal values and standard deviations) instead of a tuple argument.
This is consistent with the new, simplerufloat()interface.
The previous
usage will be supported for some time. Users are encouraged to update
their code, for instance through the newly providedcode 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 likeufloat(3, 0.1),ufloat(3, 0.1, "pi"),ufloat_fromstr("3.0(1)"), orufloat_fromstr("3.0(1)","pi").
The previousufloat((3,0.1))andufloat("3.0(1)")forms
will be supported for some time. Users are encouraged to update
their code, for instance through the newly providedcode updater.2.0: The standard deviation is now obtained more directly without an
explicit
call (x.std_devinstead ofx.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 withx.std_dev = 0.1. As a consequence,x.set_std_dev()is deprecated.1.9.1: Support added for pickling subclasses ofUFloat(=Variable).1.9: Added functions for handling correlation matrices:correlation_matrix()andcorrelated_values_norm(). (These new functions mirror the
covariance-matrix basedcovariance_matrix()andcorrelated_values().)UFloat.position_in_sigmas()is
now namedUFloat.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, likefloat()does.1.6: Testing whether an object is a number with uncertainty should now
be done withisinstance(...,UFloat).AffineScalarFuncis not imported byfrom uncertainties import *anymore, but its new aliasUFloatis.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: Addedumath.modf()andumath.frexp().1.5.4:ufloatdoes not accept a single number (nominal value) anymore.
This removes some potential confusion aboutufloat(1.1)(zero uncertainty) being different fromufloat("1.1")(uncertainty of 1 on the last digit).1.5.2:float_u,array_uandmatrix_urenamedufloat,uarrayandumatrix, for ease of typing.1.5:  Added functionsnominal_valueandstd_dev, and
modulesunumpy(additional support forNumPyarrays and
matrices) andunumpy.ulinalg(generalization of some
functions fromnumpy.linalg).
Memory footprint of arrays of numbers with uncertainties
divided by 3.
Functionarray_uis 5 times faster.
Main functionnum_with_uncertrenamedfloat_u, for consistency withunumpy.array_uandunumpy.matrix_u, with the added benefit of a shorter name.1.4.5: Added support for the standardpicklemodule.1.4.2: Added support for the standardcopymodule.1.4: Added utilities for manipulatingNumPyarrays of numbers with
uncertainties (array_u,nominal_valuesandstd_devs).1.3: Numbers with uncertainties are now constructed withnum_with_uncert(), which replacesNumberWithUncert().  This
simplifies the class hierarchy by removing theNumberWithUncertclass.1.2.5: Numbers with uncertainties can now be entered asNumberWithUncert("1.23+/-0.45")too.1.2.3:log(x, base)is now supported byumath.log(), in addition
tolog(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 themathmodule anymore.1.0.12: Main class (Number_with_uncert) renamedNumberWithUncertso as to followPEP 8.1.0.11:origin_valuerenamed more appropriately asnominal_value.1.0.9:correlations()renamed more appropriately ascovariance_matrix().