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:
x (
UncertainReal
) – abscissay (
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.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 tox
.- Parameters:
y (
UncertainReal
orUncertainComplex
) – an uncertain numberx (
UncertainReal
orUncertainComplex
) – an uncertain number
- Return type:
If
x
andy
are uncertain real, the function callsreporting.u_component()
and returns the magnitude of the result.If either
x
ory
is uncertain complex, the returned value represents the magnitude of the component of uncertainty matrix (this is obtained by applyingreporting.u_bar()
to the result obtained fromreporting.u_component()
).If either
x
ory
is a number, zero is returned.component
can also e used in conjunction withresult()
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:
- Return type:
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 1E6Examples:
>>> 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
moduloy
- Parameters:
x – an
UncertainReal
or a numbery – a number (int or float)
Note
If
x
is not an uncertain number, returnsmath.fmod(x,y)
.Note
When
x
is an uncertain number, it is an untested assumption that the standard uncertainty associated withx
is not greater than the magnitude ofy
.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.
- 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:
- pow(x, y)
Uncertain number power function
Raises
x
to the power ofy
- result(un, label=None)
Create an uncertain number to represent an intermediate result
- Parameters:
un –
UncertainReal
orUncertainComplex
orUncertainArray
label – str or a sequence of str
- Return type:
When
un
is an array, anUncertainArray
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()
ormultiple_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()
orucomplex()
.A
ValueError
is raised when illegal arguments are usedWhen 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:
- Return type:
- Raises:
ValueError
ifdf
oru
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 beu
.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:
- Return type:
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 numberReturns a real number if
x
is an uncertain real numberReturns
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 attributesx
,u
,v
anddf
, for the value, uncertainty, variance and degrees-of-freedom, respectively, of the uncertain number.The function
ureal()
creates elementaryUncertainReal
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 TrueWhen the value of an
UncertainReal
is converted to a string (e.g., bystr
, or byprint()
), 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., byrepr()
) 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:
- property df
Return the degrees of freedom
- Return type:
Note
ur.df
is equivalent todof(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:
- property label
The uncertain-number label
- Return type:
Note
ur.label
is equivalent tolabel(ur)
Example:
>>> ur = ureal(2.5,0.5,label='x') >>> ur.label 'x' >>> label(ur) 'x'
- property real
Return the real component
- Return type:
- property u
Return the standard uncertainty
- Return type:
Note that
ur.u
is equivalent touncertainty(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 touid(un)
New in version 1.3.7.
- property v
Return the standard variance
- Return type:
Note that
ur.v
is equivalent tovariance(ur)
Example:
>>> ur = ureal(2.5,0.5) >>> ur.v 0.25 >>> variance(ur) 0.25
Uncertain Complex Numbers
UncertainComplex
defines an uncertain-number object with attributesx
,u
,v
anddf
, for the value, uncertainty, variance-covariance matrix and degrees-of-freedom, respectively.The function
ucomplex()
creates elementaryUncertainComplex
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 TrueThe built-in function
abs()
returns the magnitude of the value as a Pythonfloat
(usemagnitude()
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 thestr
function or byprint()
), 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., byrepr()
), 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:
- 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:
Note that
uc.df
is equivalent todof(uc)
Example:
>>> uc = ucomplex(1+2j,(.3,.2),3) >>> uc.df 3.0 >>> dof(uc) 3.0
- imag
The imaginary component.
- Type:
- property label
The uncertain-number label
- Return type:
Note that
uc.label
is equivalent tolabel(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:
- real
The real component.
- Type:
- property u
Return standard uncertainties for the real and imaginary components
- Return type:
Note that
uc.u
is equivalent touncertainty(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 touid(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:
Note that
uc.v
is equivalent tovariance(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)