科研 Skill
物理量纲与不确定度传播
uncertainty-and-units
Tracks physical units and propagates measurement uncertainty with pint/uncertainties: GUM budgets, Monte Carlo propagation, dimensionless-group checks. Use to sanity-check a result or unit.
SKILL.md
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 = 2is 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.constantsin 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
- Attach units at input and strip them only at output. Convert at function
boundaries with
ureg.wrapsorm_as("unit"), never mid-calculation. - 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.
- Give every input four things: an estimate, a standard uncertainty, the distribution the uncertainty came from, and its degrees of freedom.
- Convert Type B statements with the right divisor. A certificate's expanded
uncertainty divides by its stated
k; rectangular limits divide bysqrt(3). - Identify correlations before combining. Inputs calibrated against the same standard, measured on the same instrument, or drawn from the same fit are correlated.
- Compute sensitivity coefficients, and read the budget from
c_i * u(x_i)rather than from the raw uncertainties. - 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.
- Choose
kfrom the effective degrees of freedom, not by habit. - Round the uncertainty first, then the value to the same decimal place.
- State what the
±is — standard or expanded, withk, the coverage probability, and the method. - 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 literal within 0.1% of a CODATA constant |
Exit status is 1 when a finding meets --fail-on (default high), which makes it usable
as a pre-commit or CI check.
The rules are heuristics, so a false positive is suppressed with a directive comment — trailing to cover its own line, or alone on a line to cover the next one:
value = quantity.magnitude # audit-units: ignore UNIT003 -- already converted upstream
# audit-units: ignore UNC003 -- the argument here is a plain float array
scaled = np.log10(counts)
# audit-units: ignore-file CONST001 covers a whole module, and naming no rule
suppresses all of them. Suppressions are counted in the report rather than hidden, so a
file that silences everything still says so.
check_plausibility.py
Dimensional consistency is not physical possibility. A cell 2 m across and a Reynolds number of 4e7 in a capillary both pass every unit check. This tool tests a set of quantities against dimensionless groups, characteristic scales, and curated magnitude bands, and verifies each formula's dimensionality before reporting a number.
python skills/uncertainty-and-units/scripts/check_plausibility.py \
--quantity "density=1060 kg/m**3" --quantity "velocity=0.5 mm/s" \
--quantity "length=8 um" --quantity "viscosity=3.5 mPa*s" \
--group reynolds --format markdown
# Re = 0.001211 -- laminar (circular pipe, length = diameter)
python skills/uncertainty-and-units/scripts/check_plausibility.py \
--quantity "diameter=2 m" --band "eukaryotic_cell_diameter=diameter"
# implausible: 4.3 decades outside the 5-100 um range
--group evaluates one of 14 dimensionless groups and names the regime it places the
system in; --scale computes a characteristic scale such as a diffusion time, Debye
length, or Stokes settling velocity; --band compares a supplied quantity against an
observed range. --list prints the whole catalogue with the inputs each formula needs.
Physical constants (k_B, N_A, R_gas, g_earth, and the rest) are available to every
formula without being supplied, and are read from scipy.constants at run time rather
than written as literals, so they track the CODATA release SciPy ships.
The dimensionality check is the point. Passing a kinematic viscosity where the formula needs a dynamic one — both called "viscosity", both tabulated for water, differing by a factor of ρ — is refused before any number is computed:
error: viscosity must have dimensionality [mass] / ([length] * [time]),
but m²/s is [length] ** 2 / [time]
Exit status is 1 when the verdict meets --fail-on (default implausible; a value
within one decade of a band is questionable). The thresholds are conventions with soft
edges and assume the geometry their correlation was fitted for — see
references/plausibility-scales.md for the characteristic length to use in each case.
Choosing a propagation method
| Situation | Method |
|---|---|
| Linear or near-linear model, normal-ish inputs, large dof | GUM framework alone |
| Any nonlinearity across ±2u of an input | run both, apply the clause 8 test |
| Relative uncertainty above ~20% on any input | Monte Carlo |
| Dominant rectangular or otherwise non-normal component | Monte Carlo |
| Output bounded below (variance, concentration, squared quantity) | Monte Carlo |
| Asymmetric output distribution | Monte Carlo, shortest coverage interval |
| Correlated inputs | either, but supply the covariance matrix, not the standard uncertainties alone |
A model dominated by rectangular contributions fails the clause 8 test even when it is
perfectly linear: the framework's k = 1.96 over-covers a nearly trapezoidal output.
The estimate and u_c are still right; only the interval is too wide.
Constants
Never type a constant from memory. The 2019 SI redefinition fixed c, h, e, k,
and N_A exactly, so their relative standard uncertainty is zero; everything else is a
measured value that moves between CODATA releases.
import scipy.constants as constants
constants.value("electron mass") # 9.1093837139e-31
constants.unit("electron mass") # kg
constants.precision("electron mass") # 3.07e-10, relative standard uncertainty
constants.precision("Planck constant") # 0.0, exact by definition
precision returns a relative standard uncertainty; multiply by the value for the
absolute one.
Reference files
references/gum-methodology.md— Type A and Type B evaluation, distribution divisors, the law of propagation, Welch-Satterthwaite, when the framework fails, the Monte Carlo procedure, and the clause 8 validation test.references/pint-recipes.md— registries, offset and logarithmic units, contexts, boundary enforcement withwrapsandcheck, NumPy interoperability, custom units, formatting.references/uncertainties-recipes.md— variable identity and correlation,correlated_values,umathandunumpy, format specs, fit covariance matrices, and the package's limits.references/domain-conversions.md— the energy ladder, spectroscopy, concentration, pressure, radiation and magnetism, mass spectrometry, logarithmic quantities, and the pairs that share dimensions without sharing meaning.references/reporting-rules.md— rounding, notations, the sentence that must accompany a result, SD versus SEM versus CI in figures, non-detects, and conformity decision rules.references/plausibility-scales.md— choosing the characteristic length, the dimensionless groups and the modelling assumption each one gates, characteristic scales, the observed magnitude bands and their sources, and the caveats on every threshold.
Dated sources
Checked 2026-07-26:
- JCGM 100:2008, Evaluation of measurement data — Guide to the expression of uncertainty in measurement
- JCGM 101:2008, Supplement 1 — Propagation of distributions using a Monte Carlo method
- NIST Technical Note 1297
- CODATA internationally recommended values
- Pint on PyPI — 0.25.3, released 2026-03-19.
- Pint documentation, including non-multiplicative units and contexts.
- uncertainties on PyPI — 3.2.3, released 2025-04-21.
- uncertainties documentation
- scipy.constants reference
Related skills
astropy: Core Python library for astronomy and astrophysics workflows that need Astropy APIs, including units/quantities, coordinates, FITS I/O, tab…
示例提示词
帮我用pint和uncertainties包做这组测量数据的GUM不确定度评定。
所属插件
安装该插件会一并获得同领域的 22 个 Skill / MCP。
同插件的其他科研 Skill
- 天文星表检索Queries astronomical archives (Gaia, SDSS, VizieR, MAST, NED, SIMBAD) via astroquery/TAP/ADQL and cross-matches results. Use when sourcing or combining survey data by position.
- 天文光谱分析Reduces 1D astronomical spectra with specutils: continuum normalization, line fitting, redshift/radial-velocity measurement, equivalent widths. Use for spectral classification or velocity work.
- 天文观测数据分析Runs applied astronomy pipelines with astropy/astroquery: catalog cross-matching, Gaia/SIMBAD queries, aperture photometry, CMB power spectra. Use for end-to-end data-analysis workflows.
- Astropy天文数据处理Covers core Astropy APIs for units, coordinates, FITS I/O, tables, time systems, WCS, and cosmology. Use as the API reference, before reaching for applied workflows.
- 谷歌量子计算框架Builds noise-aware quantum circuits for Google Quantum AI hardware and runs characterization experiments. Use for Google-hardware targeting; use qiskit for IBM or pennylane for differentiable ML.
- 有限元法求解偏微分方程Solves PDEs with finite elements using FEniCS/dolfinx: weak forms, gmsh meshing, Poisson/elasticity problems, boundary conditions, ParaView export. Use for continuum-physics simulation.
- 计算流体力学模拟Runs pseudospectral CFD simulations in Python: Navier-Stokes, shallow water, stratified flows with FFT-based solvers. Use for turbulence, vortex dynamics, or geophysical flow simulation.
- LAMMPS经典分子动力学Runs classical molecular dynamics with LAMMPS: force field selection, NVT/NPT ensembles, RDF/MSD post-processing, OVITO visualization. Use for atomistic materials or molecular simulation.
- 三维科学可视化Creates 3D scientific visualizations with Mayavi: vector fields, isosurfaces, volume rendering, animated 3D plots. Use for visualizing volumetric or vector-field physics data.
- 蒙特卡洛物理模拟Simulates physical systems with Monte Carlo methods: statistical integration, MCMC sampling, the Ising model, error estimation. Use for stochastic physics simulation.
- 地震学数据处理Analyzes seismological data with ObsPy: FDSN waveform download, response removal, phase picking, moment tensor inversion. Use for earthquake and seismic-waveform analysis.
- 粒子图像测速分析Extracts velocity fields from PIV image pairs with OpenPIV: cross-correlation, vector validation, vorticity/strain-rate statistics. Use for experimental fluid-flow measurement.
- 量子机器学习框架Trains quantum circuits with autodiff across IBM/Google/Rigetti/IonQ devices: VQE, QAOA, hybrid models with PyTorch/JAX. Use for gradient-based variational quantum algorithms.
- 恒星测光分析Performs PSF and aperture photometry with photutils: source detection, PSF fitting, background estimation, multi-epoch light curves. Use for precision stellar photometry beyond one aperture sum.
- 物理信息神经网络Builds physics-informed neural networks, neural ODEs, and data-driven force fields with PyTorch, DeepXDE, torchdiffeq. Use for ML-based physics simulation and surrogate modeling.
- IBM量子计算框架Runs IBM Quantum workflows end to end: Runtime primitives, transpilation, hardware backend selection, error mitigation. Use when targeting IBM Quantum hardware or Runtime.
- Qiskit量子线路实验Implements Qiskit algorithms: circuit construction, VQE/QAOA workflows, noise-model simulation, statevector-vs-shot comparisons. Use for algorithm design and local simulation.
- 开放量子系统模拟Simulates open quantum systems with QuTiP: master equations, Lindblad dynamics, decoherence, cavity QED. Use for open-system physics, not circuit-based quantum computing.
- SciPy数值计算工具Solves ODEs/PDEs, runs FFT analysis, optimization, and sparse linear algebra with SciPy for physics problems. Use as the general-purpose numerical-computing toolkit.
- SymPy符号计算Performs symbolic computation for physics with SymPy: algebra, calculus, Lagrangian mechanics, quantum operators, code generation. Use for exact derivations, not numerical solving.
- 多维标注数组NetCDF分析Analyzes labeled multi-dimensional arrays with xarray: NetCDF/HDF5 I/O, lazy Dask loading, rechunking, Zarr stores, CF conventions. Use for gridded scientific data handling.
常见问题
物理量纲与不确定度传播能做什么?
Tracks physical units and propagates measurement uncertainty with pint/uncertainties: GUM budgets, Monte Carlo propagation, dimensionless-group checks. Use to sanity-check a result or unit。
如何安装物理量纲与不确定度传播?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「物理量纲与不确定度传播」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
物理量纲与不确定度传播需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
物理量纲与不确定度传播经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。