Unit Convert

Shipping

unit_convert

Re-express a quantity in another unit, or simplify/reduce its compound unit to canonical SI form

Signature

Inputs

valueScalar|Signalrequired— The quantity to convert. Its source unit is resolved leniently (custom units auto-register).

Outputs

resultScalar|Signal— Same shape as the input, its value (and ±σ) rescaled and re-expressed in the resolved output unit.

Parameters

Key	Type	Default	Notes
`mode`	enum	target	one of: target, coherent, base
`target_unit`	unit		Unit to express the quantity in (mV, km/h, kg/m^3, Wh, °F …), used only in Convert to unit mode. The value AND its uncertainty rescale; temperatures convert affinely. Empty = pass-through. Errors on incompatible dimensions or unknown symbols (resolved strictly, so a typo is a loud error rather than a freshly minted dimension).

Description

Unit Convert expresses a quantity in a different unit while preserving the physical measurement — the number changes, its meaning does not. It is the semantic partner of set_unit, which changes the meaning while keeping the number.

Three output-unit modes share one conversion engine:

Convert to unit (target) — the classic path: re-express in a user-typed target_unit (mV, km/h, Wh, °F).
Simplify (coherent SI) (coherent) — reduce the quantity's dimension to its named coherent SI unit ( $m \cdot km / h \cdot k g / s \to J$ , $V \cdot A \to W$ , $k g \cdot m / s^{2} \to N$ , $d B V \to V$ ). The target is looked up from the source dimension, so the physical quantity is preserved — only its written form is canonicalised.
Reduce to base SI (base) — decompose the dimension into irreducible base SI units ( $J \to k g \cdot m^{2} / s^{2}$ , $W \to k g \cdot m^{2} / s^{3}$ ). Numerically identical to coherent (every base unit has scale 1); only the written symbol differs.

For ordinary units the conversion is the full affine map $v a l u e^{'} = f a c t or \cdot v a l u e + o ff se t$ with $f a c t or = sc a l e_{src} / sc a l e_{t g t}$ , so $^{\circ} C \to^{\circ} F$ shifts correctly while $V \to mV$ is a pure rescale. Per-sample variance converts by $f a c t o r^{2}$ only — an offset shifts the value but never affects the spread, so $σ$ scales purely by the slope.

When the source or target is logarithmic (dB ↔ linear, e.g. dBV, dBm) the map is nonlinear: each value passes through the base scale and each variance propagates first-order by the local slope², which is value-dependent. On this path the σ-correlation lineage is dropped (the node re-enters as a fresh source), mirroring the FFT/IIR drop policy.

Empty target in target mode is an explicit identity pass-through — a freshly dropped node never errors and never silently invents a canonical form. Incompatible dimensions error with both dimensional formulas in the message.

Mathematics

(affine) v a l u e^{'} = f a c t or \cdot v a l u e + o ff se t, f a c t or = \frac{sc a l e _{src}}{sc a l e _{t g t}}

σ^{'2} = f a c t o r^{2} σ^{2} (the offset never affects the spread)

(logarithmic) v a l u e^{'} = t g t . from_base (src . to_base (v a l u e))

σ^{'2} = (src . d_to_base (v a l u e) \cdot t g t . d_from_base)^{2} σ^{2}

Examples

Volts to millivolts (value and σ rescale)

target mode, target_unit = mV. An input of $5 V \pm 0.1 V$ becomes $5000 mV \pm 100 mV$ ( $σ^{2} : 0.01 \to 10000$ ). The factor is $1000$ , offset $0$ .

Celsius to Fahrenheit is affine

target_unit = °F. $25\,^{\circ}C \pm 0.5$ maps to $77\,^{\circ}F$ . The value shifts by the $+ 32$ offset, but $σ$ scales by the slope $9/5$ only: $0.5 \to 0.9$ , so $σ^{2} = 0.81$ .

Simplify a compound unit to named SI

coherent mode. A quantity of $5 (m \cdot km / h \cdot k g / s)$ is dimensionally an energy, so it simplifies to Joules: $5 \cdot \frac{1000}{3600} \approx 1.389 J$ . Likewise $2 V \cdot A \to 2 W$ .

Reduce Watts to base SI

base mode on $1 W$ yields kg*m^2/s^3 with the same value. The generated symbol re-parses through the unit engine back to the power dimension, so a downstream node can resolve it.

dBV to Volts (logarithmic)

target_unit = V. $20 d B V = 10 V$ . A σ of $1 d B$ propagates by the local slope $\frac{10 l n 10}{20} \approx 1.151 V / d B$ , so $σ \approx 1.151 V$ at this operating point.

Applications

Presenting acquired data in engineering units (V→mV, m→km, Pa→bar) with uncertainty carried along automatically.
Collapsing a chain of arithmetic that leaves a messy compound unit (m·km/h·kg/s) into a clean named result (J) for display or export.
Reducing named units to irreducible base SI to verify dimensional consistency of a derived quantity.
Converting logarithmic sensor readings (dBV, dBm) to linear V/W before downstream math that expects linear units.

Neat

One conversion engine serves all three modes: `coherent` and `base` only differ in how the target is *derived* — the coherent mode looks up the dimension's named SI unit, base mode spells the same scale-1 value out in irreducible symbols.

The base-SI symbol is emitted in conventional textbook order (mass·length·time·…), split into numerator and denominator, and is guaranteed to re-parse to the same dimension so it round-trips through the unit parser.

Variance converts by factor² independent of the affine offset — a deliberate consequence of the units subsystem's affine model (ADR-002): a temperature shift moves the mean but not the spread.

Known issues

Logarithmic conversions (dB ↔ linear) are nonlinear, so they drop the σ-correlation lineage and re-enter as a fresh source — downstream correlation with the pre-conversion signal is lost.

In `target` mode an unknown or misspelled target unit is a strict, loud error (it will not auto-register a new dimension); the simplify modes ignore any stale `target_unit`.

Converting across incompatible dimensions (e.g. V→kg, or dBV→W) errors with both dimensional formulas rather than producing a value.