Core Functions and Classes

Core Functions

A set of core mathematical functions, together with functions that create elementary uncertain numbers and functions that can be used to access uncertain number attributes, are defined in the core module. These functions are automatically imported into the GTC namespace, so they are available after performing from GTC import *.

ureal(x, u, df=inf, label=None, independent=True)

Create an elementary uncertain real number

Parameters:
  • x (float) – the value (estimate)
  • u (float) – the standard uncertainty
  • df (float) – the degrees-of-freedom
  • label (str) – a string label
  • independent (bool) – not correlated with other UNs
Return type:

UncertainReal

Example:

>>> ur = ureal(2.5,0.5,3,label='x')
>>> ur
ureal(2.5,0.5,3.0, label='x')
multiple_ureal(x_seq, u_seq, df, label_seq=None)

Return a sequence of related elementary uncertain real numbers

Parameters:
  • x_seq – a sequence of values (estimates)
  • u_seq – a sequence of standard uncertainties
  • df – the degrees-of-freedom
  • label_seq – a sequence of labels
Return type:

a sequence of UncertainReal

Defines an set of uncertain real numbers with the same number of degrees-of-freedom.

Correlation between any pairs of this set of uncertain numbers defined will not invalidate degrees-of-freedom calculations. (see: R Willink, Metrologia 44 (2007) 340-349, Sec. 4.1)

Example:

# Example from GUM-H2
>>> x = [4.999,19.661E-3,1.04446]
>>> u = [3.2E-3,9.5E-6,7.5E-4]
>>> labels = ['V','I','phi']
>>> v,i,phi = multiple_ureal(x,u,4,labels)

>>> set_correlation(-0.36,v,i)
>>> set_correlation(0.86,v,phi)
>>> set_correlation(-0.65,i,phi)

>>> r = v/i*cos(phi)
>>> r
ureal(127.73216992810208,0.06997872798837172,4.0)
multiple_ucomplex(x_seq, u_seq, df, label_seq=None)

Return a sequence of uncertain complex numbers

Parameters:
  • x_seq – a sequence of complex values
  • u_seq – a sequence of standard uncertainties or covariances
  • df – the degrees-of-freedom
  • label_seq – a sequence of labels for the uncertain numbers
Return type:

a sequence of UncertainComplex

This function defines an set of uncertain complex numbers with the same number of degrees-of-freedom.

Correlation between any pairs of these uncertain numbers will not invalidate degrees-of-freedom calculations. (see: R Willink, Metrologia 44 (2007) 340-349, Sec. 4.1)

Example:

# GUM Appendix H2
>>> values = [4.999+0j,0.019661+0j,1.04446j]
>>> uncert = [(0.0032,0.0),(0.0000095,0.0),(0.0,0.00075)]
>>> v,i,phi = multiple_ucomplex(values,uncert,5)

>>> set_correlation(-0.36,v.real,i.real)
>>> set_correlation(0.86,v.real,phi.imag)
>>> set_correlation(-0.65,i.real,phi.imag)

>>> z = v * exp(phi)/ i
>>> z
ucomplex((127.7321699281021+219.8465119126384j), u=[0.06997872798837172,0.29571682684612355], r=-28.582576088518298, df=4.999999999999997)
ucomplex(z, u, df=inf, label=None, independent=True)

Create an elementary uncertain complex number

Parameters:
  • z (complex) – the value (estimate)
  • u (float, 2-element or 4-element sequence) – the standard uncertainty or variance
  • df (float) – the degrees-of-freedom
Return type:

UncertainComplex
Raises:

ValueError if df or u have illegal values.

u can be a float, a 2-element or 4-element sequence.

If u is a float, the standard uncertainty in both the real and imaginary components is taken to be u.

If u is a 2-element sequence, the first element is taken to be the standard uncertainty in the real component and the second element is taken to be the standard uncertainty in the imaginary component.

If u is a 4-element sequence, the sequence is interpreted as a variance-covariance matrix.

Examples:

>>> uc = ucomplex(1+2j,(.5,.5),3,label='x')
>>> uc
ucomplex((1+2j), u=[0.5,0.5], r=0.0, df=3.0, label=x)

>>> cv = (1.2,0.7,0.7,2.2)
>>> uc = ucomplex(0.2-.5j, cv)
>>> variance(uc)
VarianceCovariance(rr=1.1999999999999997, ri=0.7, ir=0.7, ii=2.2)
constant(x, label=None)

Create a constant uncertain number (with no uncertainty)

Parameters:x (float or complex) – a number
Return type:UncertainReal or UncertainComplex

If x is complex, return an uncertain complex number.

If x is real return an uncertain real number.

Example:

>>> e = constant(math.e,label='Euler')
>>> e
ureal(2.718281828459045,0.0,inf, label='Euler')
value(x)

Return the value

Returns a complex number if x is an uncertain complex number

Returns a real number if x is an uncertain real number

Returns x otherwise.

Example:

>>> un = ureal(3,1)
>>> value(un)
3.0
>>> un.x
3.0
uncertainty(x)

Return the standard uncertainty

If x is an uncertain complex number, return a 2-element sequence containing the standard uncertainties of the real and imaginary components.

If x is an uncertain real number, return the standard uncertainty.

Otherwise, return 0.

Examples:

>>> ur = ureal(2.5,0.5,3,label='x')
>>> uncertainty(ur)
0.5
>>> ur.u
0.5

>>> uc = ucomplex(1+2j,(.5,.5),3,label='x')
>>> uncertainty(uc)
StandardUncertainty(real=0.5, imag=0.5)
variance(x)

Return the standard variance

If x is an uncertain real number, return the standard variance.

If x is an uncertain complex number, return a 4-element sequence containing elements of the variance-covariance matrix.

Otherwise, return 0.

Examples:

>>> ur = ureal(2.5,0.5,3,label='x')
>>> variance(ur)
0.25
>>> ur.v
0.25

>>> uc = ucomplex(1+2j,(.5,.5),3,label='x')
>>> variance(uc)
VarianceCovariance(rr=0.25, ri=0.0, ir=0.0, ii=0.25)
dof(x)

Return the degrees-of-freedom

Returns inf when the degrees of freedom is greater than 1E6

Examples:

>>> ur = ureal(2.5,0.5,3,label='x')
>>> dof(ur)
3.0
>>> ur.df
3.0

>>> uc = ucomplex(1+2j,(.3,.2),3,label='x')
>>> dof(uc)
3.0
label(x)

Return the label

component(y, x)

Return the magnitude of the component of uncertainty in y due to x.

Parameters:
Return type:

float

If x and y are uncertain real, the function calls reporting.u_component() and returns the magnitude of the result.

If either x or y is uncertain complex, the returned value represents the magnitude of the component of uncertainty matrix (this is obtained by applying reporting.u_bar() to the result obtained from reporting.u_component()).

If either x or y is a number, zero is returned.

component can also e used in conjunction with result() to evaluate a component of uncertainty with respect to an intermediate uncertain number.

Examples:

>>> x1 = ureal(2,1)
>>> x2 = ureal(5,1)
>>> y = x1/x2
>>> reporting.u_component(y,x2)
-0.08
>>> component(y,x2)
0.08

>>> z1 = ucomplex(1+2j,1)
>>> z2 = ucomplex(3-2j,1)
>>> y = z1 - z2
>>> reporting.u_component(y,z2)
ComponentOfUncertainty(rr=-1.0, ri=0.0, ir=0.0, ii=-1.0)
>>> component(y,z2)
1.0

>>> I = ureal(1E-3,1E-5)
>>> R = ureal(1E3,1)
>>> V = result( I*R )
>>> P = V**2/R
>>> component(P,V)
2.0099751242241783e-05
get_covariance(arg1, arg2=None)

Evaluate covariance.

The input arguments can be a pair of uncertain numbers, or a single uncertain complex number.

When a pair of uncertain real numbers is supplied, the correlation between the two arguments is returned as a real number.

When one, or both, arguments are uncertain complex numbers, a CovarianceMatrix is returned, representing a 2-by-2 variance-covariance matrix.

get_correlation(arg1, arg2=None)

Return correlation

The input arguments may be a pair of uncertain numbers, or a single uncertain complex number.

When a pair of uncertain real numbers is provided, the correlation between the arguments is returned as a real number.

When one, or both, arguments are uncertain complex numbers, a CorrelationMatrix is returned, representing a 2-by-2 matrix of correlation coefficients.

set_correlation(r, arg1, arg2=None)

Set correlation between elementary uncertain numbers

The input arguments can be a pair of uncertain numbers (the same type, real or complex), or a single uncertain complex number.

The uncertain number arguments must be elementary uncertain numbers.

If the arguments have finite degrees of freedom, they must be declared together using either multiple_ureal() or multiple_ucomplex().

If the uncertain number arguments have infinite degrees of freedom they can, alternatively, be declared by setting the argument independent=False when calling ureal() or ucomplex().

A ValueError is raised when illegal arguments are used

When a pair of uncertain real numbers is provided, r is the correlation coefficient between them.

When a pair of uncertain complex number arguments is provided, r must be a 4-element sequence containing correlation coefficients between the components of the complex quantities.

Examples:

>>> x1 = ureal(2,1,independent=False)
>>> x2 = ureal(5,1,independent=False)
>>> set_correlation(.3,x1,x2)
>>> get_correlation(x1,x2)
0.3

>>> z = ucomplex(1+0j,(1,1),independent=False)
>>> z
ucomplex((1+0j), u=[1.0,1.0], r=0.0, df=inf)
>>> set_correlation(0.5,z)
>>> z
ucomplex((1+0j), u=[1.0,1.0], r=0.0, df=inf)

>>> x1 = ucomplex(1,(1,1),independent=False)
>>> x2 = ucomplex(1,(1,1),independent=False)
>>> correlation_mat = (0.25,0.5,0.75,0.5)
>>> set_correlation(correlation_mat,x1,x2)
>>> get_correlation(x1,x2)
CorrelationMatrix(rr=0.25, ri=0.5, ir=0.75, ii=0.5)
result(un, label=None)

Declare un to be an uncertain-number ‘result’

un - an uncertain number label - a label can be assigned

This function must be called before other uncertain numbers are derived from the uncertain number.

The dependence of other uncertain numbers on a declared intermediate result evaluated.

Declaring intermediate results also enables these results and the dependence of other uncertain numbers to be stored in an archive.

Parameters:
Return type:

UncertainReal or UncertainComplex

Example:

>>> I = ureal(1.3E-3,0.01E-3)
>>> R = ureal(995,7)
>>> V = result( I*R )
>>> P = V**2/R
>>> component(P,V)
3.505784505642068e-05
cos(x)

Uncertain number cosine function

sin(x)

Uncertain number sine function

tan(x)

Uncertain number tangent function

acos(x)

Uncertain number arc-cosine function

Note

In the complex case there are two branch cuts: one extends right, from 1 along the real axis to \(\infty\), continuous from below; the other extends left, from -1 along the real axis to \(-\infty\), continuous from above.

asin(x)

Uncertain number arcsine function

Note

In the complex case there are two branch cuts: one extends right, from 1 along the real axis to \(\infty\), continuous from below; the other extends left, from -1 along the real axis to \(-\infty\), continuous from above.

atan(x)

Uncertain number arctangent function

Note

In the complex case there are two branch cuts: One extends from \(\mathrm{j}\) along the imaginary axis to \(\mathrm{j}\infty\), continuous from the right. The other extends from \(-\mathrm{j}\) along the imaginary axis to \(-\mathrm{j}\infty\), continuous from the left.

atan2(y, x)

Two-argument uncertain number arctangent function

Parameters:

Note

this function is not defined for uncertain complex numbers (use phase())

Example:

>>> x = ureal(math.sqrt(3)/2,1)
>>> y = ureal(0.5,1)
>>> theta = atan2(y,x)
>>> theta
ureal(0.5235987755982989,1.0,inf)
>>> math.degrees( theta.x )
30.000000000000004
exp(x)

Uncertain number exponential function

pow(x, y)

Uncertain number power function

Raises x to the power of y

log(x)

Uncertain number natural logarithm

Note

In the complex case there is one branch cut, from 0 along the negative real axis to \(-\infty\), continuous from above.

log10(x)

Uncertain number common logarithm (base-10)

Note

In the complex case there is one branch cut, from 0 along the negative real axis to \(-\infty\), continuous from above.

sqrt(x)

Uncertain number square root function

Note

In the complex case there is one branch cut, from 0 along the negative real axis to \(-\infty\), continuous from above.

sinh(x)

Uncertain number hyperbolic sine function

cosh(x)

Uncertain number hyperbolic cosine function

tanh(x)

Uncertain number hyperbolic tangent function

acosh(x)

Uncertain number hyperbolic arc-cosine function

Note

In the complex case there is one branch cut, extending left from 1 along the real axis to \(-\infty\), continuous from above.

asinh(x)

Uncertain number hyperbolic arcsine function

Note

In the complex case there are two branch cuts: one extends from \(\mathrm{j}\) along the imaginary axis to \(\mathrm{j}\infty\), continuous from the right; the other extends from \(-\mathrm{j}\) along the imaginary axis to \(-\mathrm{j}\infty\), continuous from the left.

atanh(x)

Uncertain number hyperbolic arctangent function

Note

In the complex case there are two branch cuts: one extends from 1 along the real axis to \(\infty\), continuous from below; the other extends from -1 along the real axis to \(-\infty\), continuous from above.

mag_squared(x)

Return the squared magnitude of x.

Note

If x is an uncertain number, the magnitude squared is returned as an uncertain real number, otherwise :func:abs(x)**2 is returned.

magnitude(x)

Return the magnitude of x

Note

If x is not an uncertain number type, returns abs(x).

phase(z)
Parameters:z (UncertainComplex) – an uncertain complex number
Returns:the phase in radians
Return type:UncertainReal

Uncertain Number Types

There are two types of uncertain number, one to represent real-valued quantities (UncertainReal) and one to represent real-complex quantities (UncertainComplex).

Uncertain Real Numbers

The UncertainReal class defines an uncertain-number object with the attributes x, u, v and df, to obtain the value, uncertainty, variance and degrees-of-freedom for the uncertain number, respectively.

The function ureal() creates elementary UncertainReal objects. For example,

>>> x = ureal(1.414141,0.01)
>>> x
ureal(1.414141,0.01,inf)

All logical comparison operations (e.g., <, >, ==, etc) are applied to the value of an uncertain number. For example,

>>> un = ureal(2.5,1)
>>> un > 3
False
>>> un == 2.5
True

When the value of an UncertainReal is converted to a string (e.g., by str, or by print()), the precision depends on the uncertainty. The two least significant digits of the value correspond to the two most significant digits of the standard uncertainty. The value of standard uncertainty is appended to the string in parentheses.

For example,

>>> x = ureal(1.414141,0.01)
>>> str(x)
'1.414(10)'
>>> print(x)
1.414(10)

When an UncertainReal is converted to its Python representation (e.g., by repr()) a string is returned that shows the representation of the elements that define the uncertain number.

For example,

>>> x = ureal(1.4/3,0.01,5,label='x')
>>> repr(x)
"ureal(0.4666666666666666,0.01,5.0, label='x')"
class UncertainReal(x, u_comp, d_comp, i_comp, node=None)

An UncertainReal holds information about the measured value of a real-valued quantity

conjugate()

Return the complex conjugate

Return type:UncertainReal
df

Return the degrees of freedom

Return type:float

Note un.df is equivalent to dof(un)

Example::
>>> ur = ureal(2.5,0.5,3)
>>> ur.df
3.0
imag

Returns the imaginary component

label

The uncertain-number label

Return type:str

Note un.label is equivalent to label(un)

Example::
>>> x = ureal(2.5,0.5,label='x')
>>> x.label
'x'

>>> label(x)
'x'
real

Return the real component

u

Return the standard uncertainty

Return type:float

Note that un.u is equivalent to uncertainty(un)

Example:

>>> ur = ureal(2.5,0.5)
>>> ur.u
0.5
v

Return the standard variance

Return type:float

Note that un.v is equivalent to variance(un)

Example::
>>> ur = ureal(2.5,0.5)
>>> ur.v
0.25
x

Return the value

Return type:float

Note that un.x is equivalent to value(un)

Example::
>>> ur = ureal(2.5,0.5)
>>> ur.x
2.5

Uncertain Complex Numbers

The class UncertainComplex defines an uncertain-number object with the attributes x, u, v and df, to obtain the value, uncertainty, variance-covariance matrix and degrees-of-freedom, respectively.

The function ucomplex() creates elementary UncertainComplex objects, for example

>>> z = ucomplex(1.333-0.121212j,(0.01,0.01))

Equality comparison operations (== and !=) are applied to the value of uncertain complex numbers. For example,

>>> uc = ucomplex(3+3j,(1,1))
>>> uc == 3+3j
True

The built-in function abs() returns the magnitude of the value of the uncertain number (use magnitude() if uncertainty propagation is required). For example,

>>> uc = ucomplex(1+1j,(1,1))
>>> abs(uc)
1.4142135623730951

>>> magnitude(uc)
ureal(1.4142135623730951,0.9999999999999999,inf)

When an UncertainComplex is converted to a string (e.g., by the str function or by print()), the precision depends on the uncertainty.

The lesser of the uncertainties in the real and imaginary components is used for formatting. The two least significant digits of the formated component values will correspond to the two most significant digits of this standard uncertainty. Values of standard uncertainty are appended to the component values in parentheses.

For example,

>>> z = ucomplex(1.333-0.121212j,(0.01,0.002))
>>> print(z)
(1.3330(100)-0.1212(20)j)

When an UncertainComplex is converted to its Python representation ( e.g., by repr() ), a string is returned that shows the representation of the elements that define the uncertain number.

For example,

>>> z = ucomplex(1.333-0.121212j,(0.01,0.002))
>>> repr(z)
'ucomplex((1.333-0.121212j), u=[0.01,0.002], r=0.0, df=inf)'
class UncertainComplex(r, i)

An UncertainComplex holds information about the measured value of a complex-valued quantity

conjugate()

Return the complex conjugate

An UncertainComplex object is created by negating the imaginary component.

Return type:UncertainComplex
df

Return the degrees-of-freedom

When the object is not an elementary uncertain number, the effective degrees-of-freedom is calculated using the method described by Willink and Hall in Metrologia 2002, 39, pp 361-369.

Return type:float

Note that uc.df is equivalent to dof(uc)

Example::
>>> uc = ucomplex(1+2j,(.3,.2),3)
>>> uc.df
3.0
label

The label attribute

Return type:str

Note that``un.label`` is equivalent to label(un)

Example::
>>> z = ucomplex(2.5+.3j,(1,1),label='z')
>>> z.label
'z'
r

Return the correlation coefficient between real and imaginary components

Return type:float
u

Return standard uncertainties for the real and imaginary components

Return type:2-element sequence of float

Note that uc.u is equivalent to uncertainty(uc)

Example:

>>> uc = ucomplex(1+2j,(.5,.5))
>>> uc.u
StandardUncertainty(real=0.5, imag=0.5)
v

Return the variance-covariance matrix

The uncertainty of an uncertain complex number can be associated with a 4-element variance-covariance matrix.

Return type:4-element sequence of float

Note that uc.v is equivalent to variance(uc)

Example:

>>> uc = ucomplex(1+2j,(.5,.5))
>>> uc.v
VarianceCovariance(rr=0.25, ri=0.0, ir=0.0, ii=0.25)
x

Return the value

Return type:complex

Note that uc.x is equivalent to value(uc)

Example::
>>> uc = ucomplex(1+2j,(.3,.2))
>>> uc.x
(1+2j)