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 *
).
-
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')
-
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)
-
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 -28.5825760885182...
-
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)
-
constant
(x, label=None)¶ Create a constant uncertain number (with no uncertainty)
Parameters: x (float or complex) – a number Return type: UncertainReal
orUncertainComplex
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 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
-
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 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
-
label
(x)¶ Return the label
-
component
(y, x)¶ Return the magnitude of the component of uncertainty in
y
due tox
.Parameters: - y (
UncertainReal
orUncertainComplex
) – an uncertain number - x (
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
- y (
-
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()
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)
-
result
(un, label=None)¶ Declare an uncertain number to be an intermediate result
Parameters: - un – an uncertain number or
UncertainArray
- label – a string or sequence of strings
When
un
is an array, anUncertainArray
is returned containing the intermediate uncertain number objects.Note
This function does not affect the argument
un
. Rather, a new intermediate result object is created. So, this function will usually be applied to a temporary object.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 the dependencies of uncertain numbers to be stored in an archive.
Parameters: - un –
UncertainReal
orUncertainComplex
orUncertainArray
- label – str or a sequence of str
Return type: UncertainReal
orUncertainComplex
orUncertainArray
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
- un – an uncertain number or
-
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.5235987755982989,1.0,inf) >>> math.degrees( theta.x ) 30.000000000000004
- x (
-
exp
(x)¶ Uncertain number exponential function
-
pow
(x, y)¶ Uncertain number power function
Raises
x
to the power ofy
-
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.
-
phase
(z)¶ Parameters: z ( UncertainComplex
) – an uncertain complex numberReturns: 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¶
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: UncertainReal
-
df
¶ Return the degrees of freedom
Return type: float Note
un.df
is equivalent todof(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 tolabel(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 touncertainty(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 tovariance(un)
- Example::
>>> ur = ureal(2.5,0.5) >>> ur.v 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: 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 todof(uc)
- Example::
>>> uc = ucomplex(1+2j,(.3,.2),3) >>> uc.df 3.0
-
imag
¶ The imaginary component.
Type: UncertainReal
-
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'
-
real
¶ The real component.
Type: UncertainReal
-
u
¶ Return standard uncertainties for the real and imaginary components
Return type: 2-element sequence of float Note that
uc.u
is equivalent touncertainty(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 tovariance(uc)
Example:
>>> uc = ucomplex(1+2j,(.5,.5)) >>> uc.v VarianceCovariance(rr=0.25, ri=0.0, ir=0.0, ii=0.25)
-