ORIXUnits — validation, sources and limitations
State on 2026-11-20: swift build and swift test pass with zero warnings on macOS 27 (Swift 6.4.2, language mode 6);
the library target also compiles for the iOS Simulator (xcodebuild … -destination 'generic/platform=iOS Simulator').
60 tests in 11 suites. The tests have run on macOS only; nothing was executed on an iOS device or simulator.
How the factors were checked
- Independent derivation.
Reference/generate_reference.pyrebuilds every factor with Pythonfractions.Fractionfrom the primary definitions, without reading the Swift sources (only the unit ids are shared). It writesReference/reference_conversions.tsv(841 conversions: every one of the 331 units against its category reference in both directions, plus 245 curated everyday conversions) and embeds the same table inTests/ORIXUnitsTests/ReferenceData.swift. - Comparison. 590 rows have a terminating expectation and must be equal to the last digit; the 251 others are
compared to 33 significant digits. The
Doublepath is compared to 2 ulp. A coverage test fails if the catalog and the reference do not list exactly the same unit ids. - Guards inside the script. The derived values are asserted against the 7-digit values printed in NIST SP 811 Appendix B (psi, slug, hp, Btu/h, ton of refrigeration, ft·lbf, poundal, torr, inHg, lb/ft³, lb/gal, grain, troy ounce, acre, barrel, fluid ounces, foot-candle, US survey foot) and against published exact values (lbf, US gallon, BTU(IT), conventional mmHg, light-year, parsec to 16 digits).
- Mutation check (done once, by hand). Changing 1 atm to 101 326 Pa made 31 expectations fail; truncating π to 32 digits was caught by one test.
Limits of this evidence, stated plainly:
- The Swift catalog and the Python reference were written by the same author in the same session. They are independent derivations, not independent authorship. A misconception shared by both (a wrong belief about what a unit is) would not be caught; a typing or arithmetic error in either one is.
- The NIST SP 811 guard values and most definitions were written from memory of the standard, not re-read from the PDF during this work. Two things were fetched and read on 2026-11-20: the CODATA 2022 value of the atomic mass constant (physics.nist.gov) and Schedules II and III of the Canada Weights and Measures Act (laws-lois.justice.gc.ca).
- The ISO 4217 names and minor-unit digits were written from memory and were not diffed against the SIX list.
- The ECB parser is tested against a document in the real
eurofxref-daily.xmlstructure (namespaces, single-quoted attributes) with made-up rates. It was not run against a live download: the package and its tests do no networking.
Arithmetic
- A conversion is an exact fraction of big integers (
ExactArithmetic), divided once by schoolbook long division: the result is exact when it terminates within 38 significant digits, otherwise rounded half-to-even to 38 digits.Conversion.isExactDecimaltells which. - Foundation's own
Decimaldivision is not used: during development it returned1/149597870700with 29 correct digits and kept only about five correct digits on a parsec ↔ femtometre round trip.Decimalis only the storage type; its+/−are used for the temperature offsets (exact while the sum fits 38 digits). - Round trip a → b → a is exactly the starting value when the forward result terminated; otherwise it agrees to 1e-36 (tested over every ordered pair of exact linear units of every category, six values each).
Decimalexponents span 10⁻¹²⁸…10¹²⁷. Out-of-range results throwUnitError.notRepresentable; just inside the lower bound, low-order digits are dropped.Doublepath: decimal-faithful (shortest round-trip string →Decimal→ nearest double). Outside 1e-60…1e60, and for infinities and NaN, it falls back to binary arithmetic with a few ulps of error.- Rate conventions are
Doubleonly (log1p/expm1), checked against 962 closed-form values computed with Pythondecimalat 60 digits, to a relative 2e-13.
Units that are not exact
| Unit | Flag | Value used | Source |
|---|---|---|---|
| parsec | irrational | 648 000/π au | IAU 2015 Resolution B2; π to 38 digits |
| radian, milliradian (against degree) | irrational | 180/π ° | SI Brochure 9th ed.; π to 38 digits |
| rad/s (against Hz) | irrational | 1/(2π) Hz | SI Brochure 9th ed.; π to 38 digits |
| dalton / unified atomic mass unit | approximate | 1.660 539 068 92(52) × 10⁻²⁷ kg | CODATA 2022 (measured, relative uncertainty 3.1 × 10⁻¹⁰) |
| Mach (15 °C, sea level) | approximate | 340.294 m/s | ISO 2533:1975 / ICAO Doc 7488 standard atmosphere; real Mach depends on temperature |
| tropical year | approximate | 365.242 19 d | mean tropical year near J2000; drifts about −0.5 s per century |
Exact by definition, but a convention was chosen
| Family | Choice made | Source |
|---|---|---|
| inch, foot, yard, mile, pound and everything derived (areas, volumes, lbf, psi, hp, slug, poundal…) | 1 yd = 0.9144 m, 1 lb = 0.453 592 37 kg, g₀ = 9.806 65 m/s² | 1959 international agreement; NIST SP 811 B.6; 3rd CGPM (1901) |
| rod, chain, link, furlong, fathom, acre | international foot (before 2023, US land surveys used the survey foot: 2 ppm larger) | NIST/NGS retirement of the US survey foot, 2022-12-31 |
| US survey foot | 1200/3937 m, kept for old data, flagged deprecated | Mendenhall Order (1893); NIST SP 811 B.6 |
| league | 3 statute miles (other leagues exist) | convention |
| arpent (length and area) | 180 French feet of 12.789 in; 32 400 square French feet | Canada Weights and Measures Act, Schedule III |
| nautical mile, knot | 1852 m | International Hydrographic Conference, 1929 |
| astronomical unit, light-year | 149 597 870 700 m; c × 365.25 d | IAU 2012 Resolution B2; IAU (Julian year) |
| US liquid measures | gallon = 231 in³; cup = 1/16 gal (not the 240 mL labelling cup); tbsp = 1/2 fl oz; tsp = 1/6 fl oz | NIST SP 811 B.8; NIST Handbook 44 App. C |
| Imperial measures | gallon = 4.546 09 L; fl oz = 1/160 gal | UK Weights and Measures Act 1985; Canada W&M Act, Schedule II |
| metric cup, tablespoon, teaspoon | 250 mL, 15 mL, 5 mL (Australia uses a 20 mL tablespoon) | kitchen convention |
| barrel | 42 US gallons (petroleum) | NIST SP 811 B.8 |
| carat, grain, troy ounce, stone, tons | 200 mg; lb/7000; 480 gr; 14 lb; 2000 lb and 2240 lb | 4th CGPM (1907); NIST SP 811 B.8 |
| mmHg, inHg, cmH₂O, inH₂O | "conventional" columns (13 595.1 kg/m³ mercury, 1000 kg/m³ water, g₀); mmHg ≠ Torr by 1.4 × 10⁻⁷ | NIST SP 811 B.8 |
| atm, Torr, at, bar | 101 325 Pa; atm/760; kgf/cm²; 10⁵ Pa | 10th CGPM (1954); NIST SP 811 B.8 |
| calorie | cal/kcal are thermochemical (4.184 J); cal (IT) = 4.1868 J is separate |
NIST SP 811 B.8 |
| BTU, BTU/h, ton of refrigeration, therm (EC) | International Table BTU, 1055.055 852 62 J; 12 000 BTU/h | NIST SP 811 B.8 |
| therm (US) | 1.054 804 × 10⁸ J | NIST SP 811 B.8 |
| ton of TNT | 10⁹ cal(th) = 4.184 × 10⁹ J | NIST SP 811 B.8 |
| electronvolt, elementary charge, c | SI 2019 defining constants | SI Brochure 9th ed. |
| horsepower | mechanical 550 ft·lbf/s; metric 75 kgf·m/s; electric 746 W (boiler and water horsepower are absent) | NIST SP 811 B.8 |
| Julian year, Gregorian year, month, decade, century | 365.25 d; 365.2425 d; Gregorian/12; 10 and 100 Gregorian years | IAU; Gregorian calendar; labelled convention |
| data prefixes | kB = 1000 B (SI); KiB = 1024 B | SI Brochure 9th ed.; IEC 80000-13:2008 |
| point, pica, pixel | 1/72 in (DTP point); 1/6 in; 1/96 in (CSS reference pixel, not a device pixel) | PostScript; W3C CSS Values and Units |
| curie, rad, rem, poise, stokes, Gal, erg, dyne, phot | CGS and legacy units with exact SI values | NIST SP 811 B.8 |
| foot-candle | 1 lm/ft² | NIST SP 811 B.8 |
Known limitations
- Compatibility is by category, not by dimension. Energy and torque, frequency and radioactivity, absorbed dose
and dose equivalent share a
UnitDimension; the converter refuses to mix them. An expression engine that only compares dimensions would acceptJ + N·m. - Reference units are not always the coherent SI unit: degree for angle (so that °, ′, ″, gon and turn stay exact
among themselves), bit for data, km/L for fuel economy.
UnitDimensionof fuel economy is m⁻². - Bare aliases have a regional default (
gal,pt,cup,mpg→ US;ton→ short ton;therm→ US;year→ Gregorian mean year). In a Canadian app this default may be wrong for some users: the UI should show the explicit symbol (gal (US)/gal (imp)). - Symbols in the wrong case resolve to nothing (
KM,kwh,mPa). This is deliberate (a wrong SI prefix is a factor of 10⁹), but it is strict: the UI should fall back onsearch. - Missing on purpose or for lack of time: compound units built on the fly (the catalog is a fixed list;
kW·h/100 kmorN/mm²do not exist unless listed), amount of substance and concentration, luminous flux and intensity, magnetic units, angular velocity other than rpm and rad/s, US dry measures, troy pound and pennyweight, boiler horsepower, the NATO mil, sidereal time, decibels and other logarithmic units. - Temperature below absolute zero is not rejected; the converter is pure arithmetic.
- Unit and category names are English only.
- SF Symbol names were checked to exist with
NSImage(systemSymbolName:)on macOS 27 only. - Rate conventions: no day-count conventions (ACT/360, 30/360), no simple-interest or money-market yields, no bond-equivalent yield; "daily" is 365 periods, "weekly" is 52.
- Currency: 49 common ISO 4217 codes, not the full list (BGN is omitted: Bulgaria adopted the euro on 2026-01-01). The ECB timestamp is set to 16:00 Frankfurt time on the document's date, the usual publication time; the document itself carries only a date. Staleness uses a single threshold and knows nothing about weekends or TARGET holidays.