Core Functions and Classes

Core Functions

Functions that create elementary uncertain numbers and functions that access uncertain-number attributes, are defined in the core module. There is also a set of standard mathematical functions (e.g.: sqrt(), sin(), log10(), etc) for uncertain numbers. These functions can be applied to the numeric Python types too.

All core functions are automatically imported into the GTC namespace (i.e., they are available after from GTC import *).

acos(x)

Uncertain number arc-cosine function

Note

There is a singularity in the uncertainty if the value of x is unity. For example,

>>> acos(ureal(1, 1))
Traceback (most recent call last):
...
ZeroDivisionError: float division by zero

More generally, uncertainty in the inverse cosine function becomes large when \(x\) is close to unity. This may be an indication that the measurement model is ill-formed or that a GUM calculation of uncertainty is not appropriate.

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.

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.

asin(x)

Uncertain number arcsine function

Note

There is a singularity in the uncertainty if the value of x is unity. For example,

>>> asin(ureal(1, 1))
Traceback (most recent call last):
...
ZeroDivisionError: float division by zero

More generally, uncertainty in the inverse sine function becomes large when \(x\) is close to unity. This may be an indication that the measurement model is ill-formed or that a GUM calculation of uncertainty is not appropriate.

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.

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.

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

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
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')
cos(x)

Uncertain number cosine function

cosh(x)

Uncertain number hyperbolic cosine function

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
exp(x)

Uncertain number exponential function

fmod(x, y)

Return x modulo y

Parameters:
  • x – an UncertainReal or a number

  • y – a number (int or float)

Note

If x is not an uncertain number, returns math.fmod(x,y).

Note

When x is an uncertain number, it is an untested assumption that the standard uncertainty associated with x is not greater than the magnitude of y.

New in version 1.4.0.

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.

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.

label(x)

Return the label

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.

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

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
>>> print(z)
(+127.732(70)+219.847(296)j)
>>> z.r
-0.591484610818998...
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.732169928102...,0.0699787279883717...,4.0)
phase(z)
Parameters:

z (UncertainComplex) – an uncertain complex number

Returns:

the phase in radians

Return type:

UncertainReal

pow(x, y)

Uncertain number power function

Raises x to the power of y

result(un, label=None)

Create an uncertain number to represent an intermediate result

Parameters:
Return type:

UncertainReal or UncertainComplex or UncertainArray

When un is an array, an UncertainArray is returned containing the intermediate uncertain number objects.

The component of uncertainty, or the sensitivity, of an uncertain number with respect to an intermediate result can be evaluated.

Declaring intermediate results also enables uncertain numbers to be stored in an archive.

Note

This function will usually be applied to a temporary object.

Note

Applying this function to an elementary uncertain number does not create an intermediate intermediate result. If a label is already assigned to the elementary uncertain number, it will not be changed and a warning will be raised, otherwise result() will assign a label.

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
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)
sin(x)

Uncertain number sine function

sinh(x)

Uncertain number hyperbolic sine function

sqrt(x)

Uncertain number square root function

Note

There is a singularity in the uncertainty if the value of x is zero. For example,

>>> sqrt(ureal(0,1))
Traceback (most recent call last):
...
ZeroDivisionError: float division by zero

More generally, uncertainty in \(\sqrt{x}\) becomes large when \(x\) is close to zero. This may be an indication that the measurement model is ill-formed or that a GUM calculation of uncertainty is not appropriate.

Note

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

tan(x)

Uncertain number tangent function

tanh(x)

Uncertain number hyperbolic tangent function

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)
uid(x)

Return the GTC unique identifier for the uncertain number or None

New in version 1.3.7.

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)
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')
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
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)

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

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

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) applied to uncertain-number objects use the value attribute. 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 displayed 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 between 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

property df

Return the degrees of freedom

Return type:

float

Note ur.df is equivalent to dof(ur)

Example:

>>> ur = ureal(2.5,0.5,3)
>>> ur.df
3.0
>>> dof(ur)
3.0
property imag

Returns the imaginary component

Return type:

UncertainReal

property label

The uncertain-number label

Return type:

str

Note ur.label is equivalent to label(ur)

Example:

>>> ur = ureal(2.5,0.5,label='x')
>>> ur.label
'x'
>>> label(ur)
'x'
property real

Return the real component

Return type:

UncertainReal

property u

Return the standard uncertainty

Return type:

float

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

Example:

>>> ur = ureal(2.5,0.5)
>>> ur.u
0.5
>>> uncertainty(ur)
0.5
property uid

Return the unique identifier for the uncertain number, or None.

Note that un.uid is equivalent to uid(un)

New in version 1.3.7.

property v

Return the standard variance

Return type:

float

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

Example:

>>> ur = ureal(2.5,0.5)
>>> ur.v
0.25
>>> variance(ur)
0.25
property x

Return the value

Return type:

float

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

Example:

>>> ur = ureal(2.5,0.5)
>>> ur.x
2.5
>>> value(ur)
2.5

Uncertain Complex Numbers

UncertainComplex defines an uncertain-number object with attributes x, u, v and df, for 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 !=) applied to uncertain-complex-number objects use the value attribute. For example,

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

The built-in function abs() returns the magnitude of the value as a Python float (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 will determine the precision displayed. 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 between 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

property 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
>>> dof(uc)
3.0
imag

The imaginary component.

Type:

UncertainReal

property label

The uncertain-number label

Return type:

str

Note that uc.label is equivalent to label(uc)

Example:

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

Return the correlation coefficient between real and imaginary components

Return type:

float

real

The real component.

Type:

UncertainReal

property u

Return standard uncertainties for the real and imaginary components

Return type:

StandardUncertainty

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)
>>> uncertainty(uc)
StandardUncertainty(real=0.5, imag=0.5)
property uid

Return the unique identifier for the uncertain number, or None.

Note that un.uid is equivalent to uid(un)

New in version 1.3.7.

property 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:

VarianceCovariance

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)
>>> variance(uc)
VarianceCovariance(rr=0.25, ri=0.0, ir=0.0, ii=0.25)
property 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)
>>> value(uc)
(1+2j)