Package: pycertainties
pycertaintiesFor all functions, where each valuehas an associated uncertainty, the uncertainty of the function, is equal to:This module contains various utilities for working determining, calculating, and working with values with uncertainties. All of the functions and types in the submodules below are also accesible directly from thepycertaintiesmodule.pycertainties.valThevalsubmodule provides a single type,Val, that can be used to store values that have an associated uncertainty, and perform calculations on those value as if they were any other number.For example, the value 10.33 Â± 0.12 is represented byVal(10.33, 0.12).Thestrconversion returns a sensible representation of theVal.>>> Val(10.33, 0.12)
10.33 Â± 0.12
>>> Val(3.21856e-10, 3.24e-12)
(3.22 Â± 0.03)e-10
>>> Val(0.02094495456, 9.541774545e-05)
0.020945 Â± 0.000095We can use the usual operators withValtypes.>>> Val(10.33, 0.12) * 4
41.3 Â± 0.5
>>> Val(41.32, 0.48) / 4
10.33 Â± 0.12
>>> Val(10.33, 0.12) + Val(3, .5)
13.3 Â± 0.5
>>> Val(10.33, 0.12) - Val(3, .5)
7.3 Â± 0.5
>>> Val(10.33, 0.12) ** 2
107 Â± 2
>>> Val(10.33, 0.12).sqrt()
3.21 Â± 0.02
>>> Val(10.33, 0.12).sin()
-0.79 Â± 0.07
>>> Val(10.33, 0.12).log()
2.335 Â± 0.012pycertainties.calculationsOne possible concern with usingVals are accumulated round-off errors. Especially for computing uncertainties of more complex functions, the amount of intermediate steps can be signifigant, and the round-off errors add up.
If these errors are a concern, thecalculations.calculate(...)function provides a way to first calculate the uncertainty equation of an equation symoblically (usingsympyunder the hood), and then calculate the value of that uncertainty equation as the last step.For example:>>> calculate("x*y + z", x=Val(3, 0.1), y=Val(3, 1), z=4)
13 Â± 3
>>> calculate("x*y + z", x=Val(3, 0.1), y=[Val(3, 1), [Val(5, 1)]], z=4)
[13 Â± 3, [19 Â± 3]]
>>> import numpy as np
>>> np.array(calculate("x*y + z", x=Val(3, 0.1), y=np.array([[Val(3, 1), Val(5e10, 1e10)], [5, 6]]), z=4))
  [[(13 Â± 3) (1.5 Â± 0.3)e11] 
 [(19.0 Â± 0.5) (22.0 Â± 0.6)]]For a modest speed-up the first argument can also be a sympy expression so that the equation string only needs to be parsed once.>>> from sympy.parsing.sympy_parser import parse_expr
>>> f = parse_expr("x*y + z")
>>> calculate(f, x=Val(3, 0.1), y=[Val(3, 1), [Val(5, 1)]], z=4) 
[13 Â± 3, [19 Â± 3]]The uncertainty equation can also be determined without any values to calculate the final result. This expression can then be used in later calculations or converted to a sympy-parseable string or pretty string. This can be done by callingcalculations.uncertainty(expr, *variables)where the variables are all symbols that have an associated uncertainty (equivalent to an uncertainty of 0).>>> df = uncertainty("x*y + z", "x", "y")
>>> repr(df)
sqrt(x**2*Î´y**2 + y**2*Î´x**2)
>>> df
   _________________
  â•±  2   2    2   2
â•²â•±  x â‹…Î´y  + y â‹…Î´xpycertainties.pprintingThis submodule contains two functions that provide easy ways of visualizing results. Thepprinting.pprint_uncertainty(...)function takes arguments of the same form ascalculations.uncertainty(...). It will pretty-print the original equation as well as its uncertainty equation.>>> pprint_uncertainty("x*y + z", "x", "y")
f(...) = xâ‹…y + z
             _________________
            â•±  2   2    2   2
Î´f(...) = â•²â•±  x â‹…Î´y  + y â‹…Î´xThepprinting.pprint_calculation(...)function  takes arguments of the same form ascalculations.calculate(...). It will pretty-print the original equation, its calculated result, the uncertainty equation, and its calculated result.>>> pprint_calculation("x*y + z", x=Val(3, 0.1), y=Val(3, 3), z=4)
f(...) = xâ‹…y + z
        -> 13.0
             _________________
            â•±  2   2    2   2
Î´f(...) = â•²â•±  x â‹…Î´y  + y â‹…Î´x
        -> 9.00499861188218pycertainties.stringsThis submodule provides a single public function,strings.uncertainty_str(...)that will return a proper string representation of a value and its uncertainty. The expressionstr(Val(x, y))is equivilent touncertainty_str(x, y).>>> uncertainty_str(10.33, 0.12)
10.33 Â± 0.12
>>> uncertainty_str(3.21856e-10, 3.24e-12)
(3.22 Â± 0.03)e-10
>>> uncertainty_str(0.02094495456, 9.541774545e-05)
0.020945 Â± 0.000095pycertainties.utilitiesThis submodule provides a few useful functions for working with uncertainties innumpy.Theutilities.to_val_array(...)function converts two numpy arrays of int/float types to a single numpy array ofValtype. Theutilities.from_val_arary(...)function converts a single numpy array of typeValto two numpy arrays of int/float types.>>> to_val_array(np.array([10, 100, 80]), np.array([.1, .15, .35]))
[Val(10, 0.1) Val(100, 0.15) Val(80, 0.35)]
>>> from_val_array(np.array([Val(10, 0.1), Val(100, 0.15), Val(80, 0.35)]))
([ 10. 100.  80.], [0.1  0.15 0.35])Theutilities.weighted_average(...)function calculates a weighted average of a list ofValobjects usingnumpy.>>> weighted_average([Val(5, .1), Val(100,` 30), Val(10, 1), Val(15, .4)])
5.63 Â± 0.13`Note that the large value of 100 does not appreciably contribute to the average.