---

name: uncertainty-and-units description: Track physical units and propagate 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. license: MIT compatibility: Requires Python 3.12+. The numeric CLIs need pint, uncertainties, NumPy, and SciPy; the static auditor is standard-library only. All bundled tooling runs locally with no network access. allowed-tools: Read Write Edit Bash metadata: version: "1.1" skill-author: K-Dense Inc.

Uncertainty and units

Scope

Use this skill whenever a calculation carries physical units or a reported number needs an uncertainty. Concretely:

• converting between units, including conversions that need a physical context (wavelength to photon energy, mass to amount of substance, energy to temperature);
• propagating uncertainty through a measurement model, with or without correlated inputs;
• building a GUM uncertainty budget from calibration certificates, specifications, and repeatability data;
• choosing a coverage factor and deciding whether k = 2 is defensible;
• rounding and writing a result so a reader knows what the ± means;
• extracting parameter uncertainties from a curve fit without discarding correlations;
• reviewing existing analysis code for silent unit and uncertainty defects;
• checking that a dimensionally consistent answer is also physically possible — the order of magnitude, the dimensionless group, and the regime it implies.

This skill covers the metrology and the two libraries that implement it. It does not cover statistical inference, model selection, or study design — see statistical-analysis, statistical-power, and experimental-design.

Current release and installation

Verified 2026-07-26:

• pint 0.25.3, released 2026-03-19; requires Python 3.11+.
• uncertainties 3.2.3, released 2025-04-21; requires Python 3.8+.
• NumPy 2.5.1 and SciPy 1.18.0; both require Python 3.12+.
• scipy.constants in SciPy 1.18.0 serves CODATA 2022. SciPy 1.11 and earlier served CODATA 2018, and several recommended values differ between them.

uv venv --python 3.13
source .venv/bin/activate
uv pip install "pint==0.25.3" "uncertainties==3.2.3" "numpy==2.5.1" "scipy==1.18.0"

pint-pandas and pint-xarray add unit-aware columns and arrays and are separate installs.

Non-negotiable workflow

1. Attach units at input and strip them only at output. Convert at function boundaries with ureg.wraps or m_as("unit"), never mid-calculation.
2. Write the measurement model explicitly before computing anything, including corrections whose estimated value is zero. A correction left out of the model leaves its uncertainty out of the budget.
3. Give every input four things: an estimate, a standard uncertainty, the distribution the uncertainty came from, and its degrees of freedom.
4. Convert Type B statements with the right divisor. A certificate's expanded uncertainty divides by its stated k; rectangular limits divide by sqrt(3).
5. Identify correlations before combining. Inputs calibrated against the same standard, measured on the same instrument, or drawn from the same fit are correlated.
6. Compute sensitivity coefficients, and read the budget from c_i * u(x_i) rather than from the raw uncertainties.
7. Check the linearization. Run Monte Carlo alongside the GUM framework and apply the JCGM 101 clause 8 comparison. Report the Monte Carlo result when it fails.
8. Choose k from the effective degrees of freedom, not by habit.
9. Round the uncertainty first, then the value to the same decimal place.
10. State what the ± is — standard or expanded, with k, the coverage probability, and the method.
11. Sanity-check the magnitude before reporting. A dimensionally consistent result can still be impossible. Compare it against a known scale or a dimensionless group, and confirm every assumption you relied on still holds in that regime.

The failures this skill exists to prevent

Each of the following runs without error and produces a plausible number.

A unit stripped at an unknown scale

length = (12.7 * ureg.mm).magnitude          # 12.7 -- of what?
length = (12.7 * ureg.mm).m_as("m")          # 0.0127 metres, stated

.magnitude returns whatever the quantity happened to be carrying. Name the unit at the point of extraction, every time.

Offset temperature arithmetic

Q(20, "degC") + Q(5, "degC")     # OffsetUnitCalculusError -- correctly refused
Q(20, "degC") + Q(5, "delta_degC")   # 25 degree_Celsius
Q(25, "degC") - Q(20, "degC")        # 5 delta_degree_Celsius

Celsius and Fahrenheit are interval scales. An uncertainty on a temperature is always a difference and belongs in a delta_ unit: converting 20 ± 0.5 degC to Fahrenheit gives 68 degF ± 0.9 delta_degF, two different conversions on one line.

Logarithmic units that add by multiplying

Q(10, "dBm") + Q(10, "dBm")   # 0.0001 kilogram**2 * meter**4 / second**6

That is 10 mW × 10 mW, not 20 mW and not 13 dBm. Nothing raises. Convert to a linear unit before any arithmetic.

A correlation destroyed by a round trip

x = ufloat(1.0, 0.1)
x - x                                     # 0.0+/-0
x - ufloat(x.nominal_value, x.std_dev)    # 0.00+/-0.14

Rebuilding a variable from its nominal value and standard deviation creates an independent variable. So does any serialization that passes through a pair of floats. Use correlated_values(values, covariance_matrix) to rebuild a correlated set.

A covariance matrix silently rescaled

popt, pcov = curve_fit(f, x, y, sigma=sigma)                        # default
popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=True)

The default rescales pcov by the reduced chi-square, so the parameter uncertainties absorb the goodness of fit and match what you would get by passing no sigma at all. On one synthetic straight-line fit the two give [0.0364, 0.2154] and [0.0477, 0.2820] — a 31% difference. Pass absolute_sigma=True whenever sigma holds real standard uncertainties.

A linearization that was never checked

For y = x² with x = 1.0 ± 0.5, the GUM framework gives y = 1.0, u_c = 1.0, and a 95% interval of [-0.96, 2.96] — mostly negative, for a squared quantity. Monte Carlo gives a mean of 1.25, u_c = 1.06, and a shortest 95% interval of [0, 3.32]. Nothing in a linear-propagation library will tell you this happened.

Bundled local CLIs

All helpers run offline, reject URLs and symlinks, bound their inputs, write output atomically with private permissions, and refuse to overwrite without --force.

python skills/uncertainty-and-units/scripts/propagate_uncertainty.py --help
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --help
python skills/uncertainty-and-units/scripts/format_result.py --help
python skills/uncertainty-and-units/scripts/convert_units.py --help
python skills/uncertainty-and-units/scripts/audit_units.py --help
python skills/uncertainty-and-units/scripts/check_plausibility.py --help

propagate_uncertainty.py

Runs both propagation methods on the same model and applies the JCGM 101 clause 8 validation test.

python skills/uncertainty-and-units/scripts/propagate_uncertainty.py \
  --expression "m / (pi * (d / 2) ** 2 * h)" \
  --variable "m=250.0,0.05" \
  --variable "d=20.0,0.02,rectangular" \
  --variable "h=40.0,0.05,rectangular" \
  --measurand density --unit "g/cm3" --format markdown

Each --variable is name=value,standard_uncertainty[,distribution[,dof]], where the distribution is normal, rectangular, triangular, arcsine, or exact and controls Monte Carlo sampling only. Correlations go in as --correlation "a,b=0.9". A JSON --spec file holds the same model for anything long-lived.

The expression is parsed into an abstract syntax tree and reduced by an explicit walk over + - * / ** and a fixed list of functions. It is never compiled or executed.

The report gives the estimate, u_c, sensitivity coefficients, the budget in percent, effective degrees of freedom, k, U, both Monte Carlo coverage intervals, and the verdict on whether the linearized result may be reported.

uncertainty_budget.py

Combines components stated the way certificates and data sheets state them.

python skills/uncertainty-and-units/scripts/uncertainty_budget.py --template > budget.json
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --spec budget.json --format markdown

Each component names a distribution that fixes its divisor — expanded divides by its coverage_factor, rectangular by sqrt(3), triangular by sqrt(6), arcsine by sqrt(2), normal by 1 — with an optional sensitivity, dof, and relative: true. The tool computes u_c, the Welch-Satterthwaite effective degrees of freedom, k from the t-distribution, and U, and warns when a Type A component has no degrees of freedom, when nu_eff is small enough that k = 2 is wrong, when one component dominates, and when a Type B component declared normal is probably an undivided expanded uncertainty.

format_result.py

python skills/uncertainty-and-units/scripts/format_result.py \
  --value 12.34567 --uncertainty 0.02345 --unit mm \
  --coverage-factor 2.26 --coverage-probability 0.95

Returns 12.346 ± 0.023 mm, 12.346(23) mm, the scientific and LaTeX forms, and the sentence that has to accompany the number. Warns when one significant digit is requested for an uncertainty beginning in 1 or 2, and when the uncertainty exceeds the estimate.

convert_units.py

python skills/uncertainty-and-units/scripts/convert_units.py \
  --value 532 --unit nm --to eV --context spectroscopy --uncertainty 0.5

python skills/uncertainty-and-units/scripts/convert_units.py \
  --value 1.0 --unit g --to mol --context chemistry --context-parameter "mw=180.156 g/mol"

Carries the uncertainty through the conversion's local derivative, which matters because context conversions are reciprocal rather than proportional. Names the context in the error message when a conversion needs one, and flags offset and logarithmic units. --list-contexts shows what the registry defines.

audit_units.py

Static review of existing analysis code. Parses, never imports or runs.

python skills/uncertainty-and-units/scripts/audit_units.py \
  --input analysis.py --format markdown --fail-on medium

| Rule | Severity | Detects | | --- | --- | --- | | UNIT001 | medium | a second UnitRegistry in one module — cross-registry ValueError | | UNIT002 | medium | offset temperature units with no delta_ unit anywhere | | UNIT003 | high | .magnitude without a preceding .to(...) or .m_as(...) | | UNIT004 | medium | logarithmic units, whose + multiplies | | UNC001 | high | curve_fit without absolute_sigma | | UNC002 | medium | np.std / np.var without ddof | | UNC003 | medium | math or numpy functions in a module that uses uncertainties | | UNC004 | high | a ufloat rebuilt from .nominal_value and .std_dev | | CONST001 | low | a