SPB Git

Repository Public MIT

VALIDATION.md 10.0 KB

# 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

  1. Independent derivation. Reference/generate_reference.py rebuilds every factor with Python fractions.Fraction from the primary definitions, without reading the Swift sources (only the unit ids are shared). It writes Reference/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 in Tests/ORIXUnitsTests/ReferenceData.swift.
  2. 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 Double path is compared to 2 ulp. A coverage test fails if the catalog and the reference do not list exactly the same unit ids.
  3. 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).
  4. 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.xml structure (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.isExactDecimal tells which.
  • Foundation's own Decimal division is not used: during development it returned 1/149597870700 with 29 correct digits and kept only about five correct digits on a parsec ↔ femtometre round trip. Decimal is 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).
  • Decimal exponents span 10⁻¹²⁸…10¹²⁷. Out-of-range results throw UnitError.notRepresentable; just inside the lower bound, low-order digits are dropped.
  • Double path: 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 Double only (log1p/expm1), checked against 962 closed-form values computed with Python decimal at 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 accept J + 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. UnitDimension of 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 on search.
  • Missing on purpose or for lack of time: compound units built on the fly (the catalog is a fixed list; kW·h/100 km or N/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.
Files main
Menu

Theme