Uncertainty Propagator

Turn an explicit measurement model and an input covariance description into a traceable uncertainty result. Keep measured values, uncertainty assumptions, model assumptions, and numerical conclusions separate.

Required inputs

Collect these before calculating:

1. Model: each output as an equation, such as g = 4*pi**2*L/T**2.
2. Input values: central value and unit for every symbol.
3. Uncertainty definition: standard uncertainty, expanded uncertainty plus coverage factor, confidence interval plus distribution, or raw repeats.
4. Dependence: covariance/correlation information, or an explicit reason inputs may be treated as independent.
5. Desired output: absolute uncertainty, relative uncertainty, covariance between outputs, or a measurement-priority recommendation.

If an uncertainty, distribution, or dependence is unknown, label it unknown; do not silently replace it with zero or independence. Ask only for missing information that can materially change the result.

Boundary

Use this skill for propagation through a stated model and for local sensitivity ranking.

• Use model-fit-auditor when model parameters must first be estimated from data and that fit has to be judged.
• Use dataset-systematic-error-hunter when drift, hysteresis, calibration bias, or omitted physics must be diagnosed from raw data.
• Use physics-mechanism-decomposer when the physical model itself is still disputed.
• Do not convert tolerance limits or instrument resolution to standard uncertainty without naming the assumed distribution.
• Do not imply that propagation captures unknown bias or model inadequacy.

Workflow

1. Normalize uncertainty inputs

Convert every supplied uncertainty to a standard uncertainty u(x_i). Record each conversion and its assumption:

• standard uncertainty: use directly;
• expanded uncertainty U: use u = U/k only when k is supplied or justified;
• rectangular half-width a: u = a/sqrt(3);
• triangular half-width a: u = a/sqrt(6);
• repeated observations: report the distinction between sample spread and uncertainty of the mean.

Keep units attached in the human-readable analysis. The helper script expects a coherent numerical unit system and does not perform unit conversion.

2. Build and validate covariance

For inputs x, construct covariance matrix Σ_x:

Σ_ij = ρ_ij u(x_i) u(x_j).

Check symmetry, diagonal non-negativity, correlation bounds, and positive semidefiniteness. Never include a covariance term twice in hand calculations. If independence is assumed, state why that is defensible (for example, separate instruments or independent calibration chains).

3. Compute first-order propagation

For output vector y = f(x), compute the Jacobian at the central values:

J_ki = ∂f_k/∂x_i

and propagate:

Σ_y = J Σ_x Jᵀ.

For one output, report signed sensitivity coefficients c_i = ∂f/∂x_i, diagonal variance contributions c_i²u_i², and the total correlation contribution. Do not present diagonal shares as a complete additive budget when correlations are important.

4. Check whether linearization is credible

Run Monte Carlo when the model is nonlinear, relative input uncertainties are not small, distributions are bounded/asymmetric, the result is near a singularity, or cancellation makes the linear result fragile.

Compare at least:

• output mean versus the model evaluated at input means;
• Monte Carlo standard deviation versus linearized standard uncertainty;
• quantiles/skewness versus a symmetric interval;
• rejected/invalid draws and their physical cause.

A discrepancy is evidence to investigate, not something to average away. Increase draws to test stability before attributing a mismatch to nonlinearity.

5. Diagnose conditioning and rank measurements

Use both local sensitivity and actual uncertainty contribution:

• sensitivity coefficient: how strongly the model responds per unit change;
• variance contribution: sensitivity combined with present measurement uncertainty;
• elasticity (x_i/y)(∂y/∂x_i): signed, as the script reports it (for g = 4π²L/T² the elasticity of T is −2); compare magnitudes |e_i| when ranking differently scaled inputs; defined only when values are nonzero;
• Jacobian condition number: warns that inverse interpretation or multi-output separation may be unstable; it is not by itself an uncertainty.

Recommend improving a measurement only when reducing its uncertainty would materially reduce the output uncertainty. For correlated inputs, discuss the covariance source before ranking individual measurements.

6. Report with an audit trail

Return sections in this order:

1. Result — estimate, standard uncertainty, unit, and interval convention.
2. Model and assumptions — equations, distributions, conversions, correlations, and omitted effects.
3. Sensitivity budget — signed coefficients, elasticities, diagonal contributions, and correlation contribution.
4. Method check — linear propagation versus Monte Carlo and any conditioning warning.
5. Next measurement — highest-value measurement improvement, expected benefit, and why.
6. Limitations — unknown bias, model inadequacy, unsupported distribution assumptions, or extrapolation.

Use appropriate significant figures: normally one or two significant digits in uncertainty, with the estimate rounded to the same decimal place. Preserve extra digits in intermediate calculations.

Helper script

scripts/propagate_uncertainty.py accepts a JSON specification and emits a JSON report. It uses SymPy for symbolic derivatives and NumPy for covariance algebra and Monte Carlo sampling.

python3 scripts/propagate_uncertainty.py example.json --samples 100000 --seed 20260904

Input shape:

{
  "variables": {
    "L": {"value": 0.994, "std_uncertainty": 0.002},
    "T": {"value": 2.006, "std_uncertainty": 0.004}
  },
  "correlations": [{"a": "L", "b": "T", "rho": 0.25}],
  "outputs": {"g": "4*pi**2*L/T**2"}
}

All numerical values must already use coherent units. Review references/method.md for interpretation and failure criteria. If dependencies or valid numerical inputs are unavailable, provide the symbolic method and mark numerical verification as blocked rather than inventing a result.

Names in outputs are plain symbols: every one must be declared under variables. The only built-in constant is pi; write exp(1) for Euler's number, so an undeclared E (energy, field, Young's modulus) is an error, not 2.718. Callable functions: sqrt, cbrt, exp, log, ln, sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, asinh, acosh, atanh, abs, erf, erfc. Python reserved words cannot be names; call a wavelength lam, not lambda. Each variable may carry an optional unit string as a label; it is not converted. Unknown fields (for example correlation for correlations) are errors. Exit code 0 means a report was produced, 2 an input error reported as {"error": ...}; --selftest runs the script's regression cases.

Quality gate

Before finalizing, verify:

• every symbol has a value, unit in the report, and uncertainty status;
• uncertainty conversions and distribution assumptions are visible;
• correlations are included or independence is justified;
• covariance is valid and dimensions of J, Σ_x, and Σ_y agree;
• nonlinear or fragile models receive a Monte Carlo comparison;
• sensitivity is not confused with uncertainty contribution;
• the recommendation names a measurable change and expected effect;
• unknown systematic and model errors remain explicit limitations.

References

• references/method.md — propagation formulas, Monte Carlo diagnostics, sensitivity and elasticity definitions
• ../_shared/physics-evidence-contract.md — §4 academic-integrity boundary shared by all physics skills (no invented uncertainties or correlations)

变更记录 / Changelog

版本	日期	变更	类型
0.1.1	2026-09-26	脚本里表达式的名字一律按普通符号处理，未声明的 E、I、S、gamma 等不再静默取 SymPy 含义，只保留 pi 与白名单函数；变量名用 lambda 等保留字时给出改名提示；未知字段（如 correlation）改为报错；加 --selftest；弹性系数统一为带符号（与脚本输出、method.md 一致），排序按绝对值；Boundary 三处泛称改为点名 model-fit-auditor、dataset-systematic-error-hunter、physics-mechanism-decomposer；补 _shared 证据契约 §4 引用；示例命令改用 python3（macOS 自带的只有 python3）	patch
0.1.0	2026-09-05	初始版本	minor