# Core Functions and Classes¶

The functions and classes defined in the core module are automatically available.

Note

In user-defined extension modules, the GTC modules must be imported. For example, from core import * must added at the top of extension module files that use core functions or classes.

## Uncertain Number Types¶

There are two types of uncertain number, one for real quantities and one for complex quantities.

### Uncertain Real Numbers¶

The class UncertainReal represents uncertain real numbers.

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


An UncertainReal may be converted to a real number using the Python function float.

>>> un = ureal(1,1)
>>> math.asin( float(un) )
1.5707963267948966


When an UncertainReal is converted to a string (e.g., by the str function, or by using the %s string-conversion format specifier), the value is embedded between ?‘s. The precision depends on the uncertainty. For example,

>>> x = ureal(1.414141,0.01)
>>> print str(x)
?1.41?
>>> print "%s" % x
?1.41?


When an UncertainReal is converted to its Python representation (e.g., by repr or by using the %r string-conversion format specifier), a string is returned showing the full internal precision of numbers. For example,

>>> x = ureal(1.414141,0.01,5,label='x')
>>> print repr(x)
ureal(1.4141410000000001, 0.01, 5, label=x)
>>> print "%r" % x
ureal(1.4141410000000001, 0.01, 5, label=x)


UncertainReal objects have the attributes x, u, v, df, and s, which obtain the value, uncertainty, variance, degrees-of-freedom and a summary string for the uncertain number, respectively.

The documentation for UncertainReal follows.

class UncertainReal(x, u_comp, i_comp, node, c)

The class implementing uncertain real numbers

df

The degrees of freedom attribute

Returns: float
Example::
>>> ur = ureal(2.5,0.5,3)
>>> ur.df
3


Note

un.df is equivalent to dof(un)

label

The label attribute

A label may be set by assignment.

Note

un.label is equivalent to label(un)

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

>>> y = 5 * x
>>> y.label = 'y'
>>> y.label
'y'

>>> label(y)
'y'

s

A summary string

The format consists of the label (if defined) and three numbers: the value, standard uncertainty and degrees-of-freedom.

The uncertainty is reported to two significant figures and the value uses the same precision. The degrees-of-freedom are rounded down to the nearest integer.

Returns: string
Example::
>>> ur = ureal(2.5,0.5,3,label='x')
>>> ur.s
'x:   2.50, u=0.50, df=3'

>>> ur = ureal(2.5,0.5,3)
>>> ur.s
' 2.50, u=0.50, df=3'


Note

un.s is equivalent to summary(un)

df=nan indicates that the degrees-of-freedom calculation is invalid.

df=inf indicates that the of degrees-of-freedom is greater than 1E6.

u

The standard uncertainty attribute

Returns: float
Example::
>>> ur = ureal(2.5,0.5)
>>> ur.u
0.5


Note

un.u is equivalent to uncertainty(un)

v

The standard variance attribute

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


Note

un.v is equivalent to variance(un)

x

The value attribute

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


Note

un.x is equivalent to value(un)

### Uncertain Complex Numbers¶

The class UncertainComplex represents uncertain complex numbers.

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.99999999999999989, inf)


An UncertainComplex may be converted to a complex number using the Python function complex.

>>> uc = ucomplex(4j,(1,1))
>>> math.sqrt( complex(uc) )
(1.4142135623730951+1.4142135623730949j)


When an UncertainComplex is converted to a string (e.g., by the str function or by using the %s string-conversion format specifier), the value is embedded between ?‘s. The precision depends on the uncertainty. For example,

>>> z = ucomplex(1.333-0.121212j,(0.01,0.01))
>>> print( str(z) )
?(1.33-0.12j)?
>>> print( "%s" % z )
?(1.33-0.12j)?


When an UncertainComplex is converted to its Python representation (e.g., by repr or by using the %r string-conversion format specifier), a string is returned in which the full internal precision of numbers is displayed. For example,

>>> z = ucomplex(1.333-0.121212j,(0.01,0.01),7,label='z')
>>> print( repr(z) )
ucomplex( (1.333-0.121212j), [0.0001,0.0,0.0,0.0001], 7, label=z )
>>> print( "%r" % z )
ucomplex( (1.333-0.121212j), [0.0001,0.0,0.0,0.0001], 7, label=z )


Note that the variance-covariance matrix is shown as a 4-element list.

UncertainComplex objects have attributes x, u, v, df, and s, which obtain the value, uncertainty, variance-covariance matrix, degrees-of-freedom and summary string of the uncertain number, respectively.

The documentation of UncertainComplex follows.

class UncertainComplex(r, i)

A class representing uncertain complex numbers

df

The degrees-of-freedom attribute

When the object is not an elementary uncertain number, the effective degrees-of-freedom is calculated by the function willink_hall.

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


Note

uc.df is equivalent to dof(uc)

label

The label attribute

A label may be set by assignment.

Note

un.label is equivalent to label(un)

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

>>> zz = z * z.conjugate()
>>> zz.label = 'zz'
>>> label(zz)
'zz'

s

A summary string

The summary string is composed of the label (when defined), the value, the standard uncertainties, the correlation coefficient and the degrees-of-freedom.

Returns: string
Example ::
>>> uc = ucomplex(1+2j,(.3,.2),3,label='x')
>>> uc.s
'x: (1.00,2.00), u=[0.30,0.20], r=0.00, df=3'

>>> uc = ucomplex(1+2j,(.3,.2),3)
>>> uc.s
'(1.00,2.00), u=[0.30,0.20], r=0.00, df=3'


Note

uc.s is equivalent to summary(uc)

The calculation of degrees-of-freedom is invalid if df=nan.

When df=inf is indicated, the of degrees-of-freedom is greater than 1E6.

u

The standard uncertainty attribute (real and imaginary components)

Returns: 2-element sequence of float
Example::
>>> uc = ucomplex(1+2j,(.5,.5))
>>> uc.u
standard_uncertainty(real=0.5, imag=0.5)


Note

uc.u is equivalent to uncertainty(uc)

v

The variance-covariance attribute

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

Returns: 4-element sequence of float
Example::
>>> uc = ucomplex(1+2j,(.5,.5))
>>> uc.v
variance_covariance(rr=0.25, ri=0.0, ir=0.0, ii=0.25)


Note

uc.v is equivalent to variance(uc)

x

The value attribute

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


Note

uc.x is equivalent to value(uc)

## Core Functions¶

A set of mathematical functions is defined in the core module, together with functions that create elementary uncertain numbers and functions that access uncertain number attributes.

### Basic functions for uncertainty calculations¶

#### Uncertain number math functions¶

ureal(x, u, df=inf, label=None, dependent=False)

Create an elementary uncertain real number

Parameters: x (float) – the value (estimate) u (float) – the standard uncertainty df (float) – the degrees-of-freedom label (string) – a string label dependent (Boolean) – allows setting a correlation coefficient UncertainReal

Example:

>>> ur = ureal(2.5,0.5,3,label='x')
>>> ur
ureal(2.5,0.5,3,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 a sequence of UncertainReal

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

Correlation between any pairs of the uncertain numbers defined does 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)
>>> summary(r)
'127.732, u=0.070, df=4'
>>> reporting.uncertainty_interval(r)
expanded_uncertainty(lower=127.53788813535775, upper=127.92645172084642)

ucomplex(z, u, df=inf, label=None, dependent=False)

Create an elementary uncertain complex number

Parameters: z (complex) – the value (estimate) u (a float, 2-element or 4-element sequence) – the standard uncertainty or variance df (float) – the degrees-of-freedom label (string) – a string label dependent (Boolean) – allows setting a correlation coefficient UncertainComplex

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 equal to u.

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

If u is a 4-element sequence, it is associated with a variance-covariance matrix. If the variance-covariance matrix has a non-zero off diagonal element (meaning that the real and imaginary components are correlated), the dependent flag will be set automatically.

A RuntimeError is raised if df or u have illegal values.

Examples:

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

>>> cv = (1.2,0.7,0.7,2.2)
>>> uc = ucomplex(0.2-.5j, cv)
>>> variance(uc)
variance_covariance(rr=1.1999999999999997, ri=0.7, ir=0.7, ii=2.2)

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 (estimates) u_seq – a sequence of standard uncertainties or covariances df – the degrees-of-freedom label_seq – a sequence of labels for the uncertain numbers a sequence of UncertainComplex

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

Correlation between pairs of these uncertain numbers does 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.73216992810208+219.84651191263839j),
u=[0.069978727988371722,0.29571682684612355],
r=-0.59099999999999997,
df=5
)
>>> reporting.uncertainty_interval(z.real)
expanded_uncertainty(lower=127.55228662093492, upper=127.91205323526924)

result(un, label=None)

Declare un as an intermediate uncertain number ‘result’

Parameters: un – an uncertain number

:arg label: - a label string

result is used when intermediate results that are part of a larger calculation needs to be reported. It allows the dependence of other uncertain numbers on this intermediate result can evaluated. This dependence can also be stored in an archive.

Example:

# The dependence of P on V can be evaluated

I = ureal(1E-3,1E-5)
R = ureal(1E3,1)
V = result( I*R )
P = V**2/R
u_PV = 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 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.71828,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)
standard_uncertainty(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)
variance_covariance(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

Returns nan when the calculation is invalid

Note

This function calls reporting.variance_and_dof, which evaluates both the variance and the degrees-of-freedom. It may be more efficient to call that function directly in some situations.

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

Returns None when no label has been assigned

Example:

>>> x1 = ureal(2,1,label='x1')
>>> label(x1)
'x1'
>>> x1.label
'x1'

summary(x)

Return a summary string

The string format is

label : value, uncertainty, dof


or, if no label is defined,

value, uncertainty, dof


The precision used to display the value depends on the uncertainty

For an uncertain real, the standard uncertainty is shown.

For an uncertain complex, a pair of standard uncertainties for the real and imaginary components is shown.

When df=inf the degrees of freedom is greater than 1E6.

If x is not an uncertain number, the Python representation is returned.

Examples:

>>> x1 = ureal(2.1213,0.5,label='x1')
>>> summary(x1)
'x1: 2.12, u=0.50, df=inf'

>>> z1 = ucomplex(1.24242-3.14141j,(0.1,0.1),5,label='z1')
>>> summary(z1)
'z1: (1.24-3.14j), u=[0.10,0.10], r=0.00, df=5'

component(y, x)

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

Parameters: y (UncertainReal or UncertainComplex) – an uncertain number x (UncertainReal or UncertainComplex) – an uncertain number float

If x and y are uncertain real, the magnitude of reporting.u_component is returned.

If either x or y is uncertain complex, the returned value represents the magnitude of the component of uncertainty matrix (see also: reporting.u_component and reporting.u_bar).

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

component can be 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)
u_components(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)

Return the covariance

The arguments arg1 and arg2 may be:

• a pair of uncertain real numbers,
• a single uncertain complex number
• a pair of uncertain complex numbers.

The return value may be a real number or a sequence of four real numbers.

When a pair of uncertain real numbers are given, return the covariance between them.

When a single uncertain complex number is given, return the covariance between the real and imaginary components.

When there are two arguments and at least one is a complex number, or an uncertain complex number, a 4-element sequence is returned.

When two uncertain complex arguments are given, the 4-element sequence representing the covariance between the real and imaginary components is returned.

If a numerical argument is used, zero, or a 4-element sequence of zeros, is returned.

Raises RuntimeError when illegal arguments types are used

Example:

>>> x1 = ureal(2,0.5)
>>> x2 = ureal(5,2.1)
>>> x3 = ureal(5,0.75)
>>> x4 = x1 + x2
>>> x5 = x2 + x3
>>> get_covariance(x4,x5)
4.41

>>> x1 = ucomplex(1,(0.5,1.2),dependent=True)
>>> x2 = ucomplex(1,(1.3,1.9),dependent=True)
>>> correlation_mat = (0.25,0.5,0.75,0.5)
>>> set_correlation(correlation_mat,x1,x2)
>>> get_covariance(x1,x2)
covariance_matrix(rr=0.1625, ri=0.475, ir=1.17, ii=1.14)

get_correlation(arg1, arg2=None)

Return the correlation coefficient

arg1 and arg2 may be:

• a pair of uncertain real numbers,
• a single uncertain complex number
• a pair of uncertain complex numbers.

The return value may be a real number or a sequence of four real numbers.

When a pair of uncertain real numbers are used, return the correlation between them.

When a single uncertain complex number is used, return the correlation between the real and imaginary components.

When there are two arguments and at least one is a complex number, or an uncertain complex number, return a 4-element sequence.

When two uncertain complex number are given, a 4-element sequence representing the correlation coefficients between the real and imaginary components is returned.

If a number is given as an argument, zero, or a sequence of zeros, is returned.

Raises RuntimeError when illegal arguments types are used

Example:

>>> x1 = ureal(2,1)
>>> x2 = ureal(5,1)
>>> x3 = ureal(5,1)
>>> x4 = x1 + x2
>>> x5 = x2 + x3
>>> get_correlation(x4,x5)
0.5

>>> x1 = ucomplex(1,(1,1),dependent=True)
>>> x2 = ucomplex(1,(1,1),dependent=True)
>>> correlation_mat = (0.25,0.5,0.75,0.5)
>>> set_correlation(correlation_mat,x1,x2)
>>> get_correlation(x1,x2)
correlation_matrix(rr=0.25, ri=0.5, ir=0.75, ii=0.5)

set_correlation(r, arg1, arg2=None)

Set the correlation between elementary uncertain numbers

The input arguments may 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.

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

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

RuntimeError is raised when illegal arguments are used

A warning will be issued if the uncertain number arguments have not been declared as dependent.

Examples:

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

>>> z = ucomplex(1+0j,(1,1),dependent=True)
>>> z
ucomplex((1+0j), u=[1,1], r=0, df=inf)
>>> set_correlation(0.5,z)
>>> z
ucomplex((1+0j), u=[1,1], r=0.5, df=inf)

>>> x1 = ucomplex(1,(1,1),dependent=True)
>>> x2 = ucomplex(1,(1,1),dependent=True)
>>> correlation_mat = (0.25,0.5,0.75,0.5)
>>> set_correlation(correlation_mat,x1,x2)
>>> get_correlation(x1,x2)
correlation_matrix(rr=0.25, ri=0.5, ir=0.75, ii=0.5)

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: x (UncertainReal) – abscissa y (UncertainReal) – ordinate

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.523598775598299,1,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)

Return an uncertain real number for the phase

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