mp_units::utility::uncertain

A representation type for values with uncertainties

Synopsis

Declared in <mp-units/utility/uncertain.h>

template<typename T>
  requires RealScalar<T> && (!disable_representation<T>) && requires { representation_values<T>::zero(); }
class uncertain;

Description

This class represents a value with its associated uncertainty (standard deviation), providing automatic uncertainty propagation through mathematical operations.

Uncertainty Propagation:

The class implements first-order uncertainty propagation (linear approximation) using standard formulas from error analysis:

• Addition/Subtraction: σ² = σx² + σy² (quadrature sum)
• Multiplication: σf² = (y·σx)² + (x·σ_y)² (partial derivatives in quadrature)
• Division: σf² = (σx/y)² + (x·σ_y/y²)²
• Functions: σf = |df/dx| × σx (derivative times uncertainty)

Important Assumptions and Limitations:

1. Independent Variables: All values are assumed to be statistically independent. Operations like x - x will give non-zero uncertainty (should be zero for perfectly correlated variables). For correlated values, a more sophisticated approach with covariance matrices would be needed.

2. First-Order Approximation: Uses linear approximation (first derivative only). This is accurate when uncertainties are small relative to the values. For large relative uncertainties or highly non-linear functions, higher-order terms may be needed.

3. Gaussian Distribution: Assumes uncertainties represent one standard deviation (σ) of normally distributed errors. Not suitable for systematic errors or non-Gaussian distributions without additional consideration.

4. No Correlation Tracking: The class does not track which values are derived from common sources, so it cannot detect or handle correlations automatically.

When to Use:

• Combining independent measurements from different instruments
• Propagating random uncertainties through calculations
• Working with measured physical constants (see measurement_of)

When NOT to Use:

• When values are correlated (e.g., f(x,x) where x appears multiple times)
• When systematic uncertainties dominate
• When uncertainties are large relative to values (>10%)
• For Monte Carlo simulations (use direct sampling instead)

Example:

quantity length = uncertain{10.0, 0.1} * m;  // 10.0 ± 0.1 m
quantity width = uncertain{5.0, 0.05} * m;   // 5.0 ± 0.05 m
quantity area = length * width;              // 50.0 ± 0.71 m²

Friends

Name	Description
mp_units::utility::atan2	Two-argument arc tangent (result in radians)
mp_units::utility::atan	Arc tangent of an uncertain value (result in radians)
mp_units::utility::acos	Arc cosine of an uncertain value (result in radians)
mp_units::utility::asin	Arc sine of an uncertain value (result in radians)
mp_units::utility::tan	Tangent of an uncertain value (argument in radians)
mp_units::utility::cos	Cosine of an uncertain value (argument in radians)
mp_units::utility::sin	Sine of an uncertain value (argument in radians)
mp_units::utility::cbrt	Cube root of an uncertain value
mp_units::utility::log2	Binary (base-2) logarithm of an uncertain value
mp_units::utility::log10	Common (base-10) logarithm of an uncertain value
mp_units::utility::log	Natural logarithm of an uncertain value
mp_units::utility::exp	Exponential function of an uncertain value
mp_units::utility::sqrt	Square root of an uncertain value
mp_units::utility::pow	Power function with runtime exponent
mp_units::utility::abs	Absolute value of an uncertain value
mp_units::utility::operator<<	Stream insertion operator
mp_units::utility::fold_conversion_uncertainty	Adds the uncertainty of a unit conversion factor to the value
mp_units::utility::operator/	Division of an exact scalar by an uncertain value
mp_units::utility::operator/	Division by an exact scalar
mp_units::utility::operator/	Division of two uncertain values
mp_units::utility::operator*	Multiplication by an exact scalar (commutative)
mp_units::utility::operator*	Multiplication by an exact scalar
mp_units::utility::operator*	Multiplication of two uncertain values
mp_units::utility::operator-	Subtraction of two uncertain values
mp_units::utility::operator+	Addition of two uncertain values

Template Parameters

Name	Description
T	The underlying real scalar type (e.g., double, float)