Skip to content

K-Dense-AI/scientific-agent-skills / skills/uncertainty-and-units

uncertainty-and-units

Verified

Tracks physical units and propagates measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.

references/uncertainties-recipes.md

View on GitHub
# uncertainties recipes

Verified against uncertainties 3.2.3 with NumPy 2.5.3 and SciPy 1.18.1. The package
performs first-order (linear) propagation with automatic differentiation (mostly analytic elementary derivatives), tracking
correlations automatically through every operation. This implements first-order variance propagation, a part of the GUM
uncertainty framework; it does not perform Monte Carlo propagation and does not check
whether linearization was appropriate.

## Variables and the correlation they carry

```python
from uncertainties import ufloat

x = ufloat(1.0, 0.1)
x - x                    # 0.0+/-0        the same variable, perfectly correlated
x - ufloat(1.0, 0.1)     # 0.00+/-0.14    two independent variables
```

That pair of lines is the whole design. A `ufloat` is an *identity*, not a number with
an attached error bar, and the difference of a variable with itself is exactly zero.
This is the correct answer, and it is why arithmetic on ufloats beats manual quadrature
in any expression where a quantity appears more than once.

The corollary is the most common defect:

```python
copy = ufloat(x.nominal_value, x.std_dev)   # a NEW, independent variable
x - copy                                    # 0.00+/-0.14, not 0
```

Rebuilding a variable from `.nominal_value` and `.std_dev` throws away every correlation
it carried. So does serializing to JSON and back, storing in a DataFrame column of
floats, or passing through any interface that speaks in pairs of numbers.
`scripts/audit_units.py` flags this construction as `UNC004`.

## Correlated inputs

```python
import numpy as np
from uncertainties import correlated_values, correlation_matrix, covariance_matrix

cov = np.array([[0.04, 0.012],
                [0.012, 0.09]])
a, b = correlated_values([1.0, 2.0], cov)

a + b                            # 3.0+/-0.4
correlation_matrix([a, b])[0][1] # 0.19999999999999987
```

`correlated_values` is how a fit's covariance matrix enters the calculation intact.
`correlation_matrix` returns a NumPy array; `covariance_matrix` returns a nested list —
index it as `[i][j]`, not `[i, j]`.

`correlated_values_norm` takes `[(value, std_dev), ...]` plus a *correlation* matrix
instead of a covariance matrix, which is usually what a paper reports.

## Functions

Ordinary `math` and `numpy` functions have no derivative rule for these objects and
fail, loudly on scalars and inside the ufunc loop on arrays:

```python
import math, numpy as np
from uncertainties import umath, unumpy

math.sqrt(a)   # TypeError: can't convert an affine function ... to float
np.sqrt(a)     # TypeError: loop of ufunc does not support argument 0 of type AffineScalarFunc
umath.sqrt(a)  # 1.00+/-0.10
```

`umath` mirrors `math`: sqrt, exp, log, log10, log1p, expm1, the trigonometric and
hyperbolic functions and their inverses, atan2, hypot, degrees, radians, and erf. `abs(UFloat)` and `umath.fabs` are deprecated
in 3.2.3; the bundled evaluator uses `uncertainties.wrap` with an explicit derivative
for absolute value and rejects the undefined derivative at zero.

For arrays, `unumpy` provides the wrapped versions plus constructors and accessors:

```python
arr = unumpy.uarray([1.0, 2.0], [0.1, 0.2])
unumpy.sqrt(arr)             # [1.0+/-0.05 1.4142135623730951+/-0.07071067811865475]
unumpy.nominal_values(arr)   # [1. 2.]
unumpy.std_devs(arr)         # [0.1 0.2]
np.mean(arr)                 # 1.50+/-0.11    -- works: object-array reduction
np.sqrt(arr)                 # TypeError      -- fails: ufunc loop
```

The split is worth internalizing: reductions written in terms of Python arithmetic
(`mean`, `sum`, `dot`) work on object arrays, while ufuncs do not. When in doubt use
`unumpy`.

## Formatting

The format spec extends the standard one. `u` counts significant digits *in the
uncertainty*, and the value is rounded to match:

```python
from uncertainties import ufloat
v = ufloat(12.3456, 0.0234)

f"{v:.2u}"    # 12.346+/-0.023
f"{v:.2uS}"   # 12.346(23)          concise notation
f"{v:.1uP}"   # 12.35±0.02          pretty Unicode
f"{v:.2uL}"   # 12.346 \pm 0.023    LaTeX
f"{ufloat(0.00012345, 0.0000023):.2ue}"   # (1.234+/-0.023)e-04
```

This handles the GUM rounding rule for you. `scripts/format_result.py` covers the cases
this does not: an expanded uncertainty with a stated k, the accompanying sentence, and
the warnings about reporting one digit when the leading digit is 1 or 2.

## Where the uncertainty came from

```python
x = ufloat(1.0, 0.2)
y = ufloat(2.0, 0.3)
result = x**2 + y
result.derivatives[x]        # 2.0 -- partial with respect to this independent input
result.error_components()    # contributions keyed by independent Variable objects
```

For independent original `ufloat` inputs this is a useful budget. For
`correlated_values`, derivatives and components are keyed by internally constructed
independent variables, not by the correlated derived objects `a` and `b` above.
`result.derivatives[a]` therefore does not return a physical partial derivative.
Compute sensitivities using independent placeholders and combine them with the full
original covariance matrix; report covariance terms separately.

## Fitted parameters

The covariance matrix from a fit contains parameter variances and covariances, and discarding
it is a routine error:

```python
import numpy as np
from scipy.optimize import curve_fit
from uncertainties import correlated_values

# Illustrative integration: define model, x, y and standard uncertainties sigma.
popt, pcov = curve_fit(model, x, y, sigma=sigma, absolute_sigma=True)
slope, intercept = correlated_values(popt, pcov)   # keeps the correlation
```

Taking `np.sqrt(np.diag(pcov))` and building independent ufloats discards it, and for a
straight-line fit the slope-intercept correlation is strongly negative — predictions
near the centroid of the data come out far too uncertain.

`absolute_sigma` decides what `pcov` means, and the default is not what most users
assume:

```python
popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=False)  # default
# pcov is rescaled by the reduced chi-square: parameter uncertainties absorb the
# goodness of fit. Relative sigma weights remain; this is not generally an unweighted fit.

popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=True)
# pcov reflects the standard uncertainties you supplied.
```

On one synthetic straight-line fit the two give parameter standard deviations of
`[0.0364, 0.2154]` and `[0.0477, 0.2820]` — a 31% difference, with no warning. Pass
`absolute_sigma=True` whenever `sigma` holds real standard uncertainties;
`scripts/audit_units.py` flags the omission as `UNC001`.

## Limits

- **First order only.** For a strongly nonlinear model the reported std_dev is the
  linearized one, and the package cannot tell you that. Cross-check with
  `scripts/propagate_uncertainty.py`, which runs Monte Carlo alongside.
- **No distribution.** A ufloat carries a standard deviation, not a shape. Rectangular
  and normal inputs with the same u are indistinguishable to it.
- **No degrees of freedom.** Coverage factors are your problem; use
  `scripts/uncertainty_budget.py`.
- **`float()` fails**, deliberately, on anything with an uncertainty. Ordering comparisons are deprecated in 3.2.3; explicitly compare `.nominal_value`
  only when that is intended. Equality also depends on uncertainty/correlation and
  is not a statistical hypothesis test.
- **Object arrays are slow.** For large arrays, propagate analytically or by Monte Carlo
  rather than element-wise.

Current references: [user guide](https://uncertainties.readthedocs.io/en/latest/user_guide.html),
[technical guide](https://uncertainties.readthedocs.io/en/latest/tech_guide.html), and
[SciPy curve_fit](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html).
`absolute_sigma=True` does not repair a wrong model, dependence ignored in sigma, poor
conditioning, or the local linear approximation behind `pcov`. A 2-D `sigma` is the
observation covariance matrix; a 1-D `sigma` is observation standard deviations.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall