SPB Git

Repository Public MIT

VALIDATION.md 10.0 KB 118 lines markdown

1# ORIXUnits — validation, sources and limitations23State on 2026-11-20: `swift build` and `swift test` pass with zero warnings on macOS 27 (Swift 6.4.2, language mode 6);4the library target also compiles for the iOS Simulator (`xcodebuild … -destination 'generic/platform=iOS Simulator'`).560 tests in 11 suites. The tests have run on macOS only; nothing was executed on an iOS device or simulator.67## How the factors were checked891. **Independent derivation.** `Reference/generate_reference.py` rebuilds every factor with Python10   `fractions.Fraction` from the primary definitions, without reading the Swift sources (only the unit ids are11   shared). It writes `Reference/reference_conversions.tsv` (841 conversions: every one of the 331 units against its12   category reference in both directions, plus 245 curated everyday conversions) and embeds the same table in13   `Tests/ORIXUnitsTests/ReferenceData.swift`.142. **Comparison.** 590 rows have a terminating expectation and must be equal to the last digit; the 251 others are15   compared to 33 significant digits. The `Double` path is compared to 2 ulp. A coverage test fails if the catalog and16   the reference do not list exactly the same unit ids.173. **Guards inside the script.** The derived values are asserted against the 7-digit values printed in NIST SP 81118   Appendix B (psi, slug, hp, Btu/h, ton of refrigeration, ft·lbf, poundal, torr, inHg, lb/ft³, lb/gal, grain, troy19   ounce, acre, barrel, fluid ounces, foot-candle, US survey foot) and against published exact values (lbf, US gallon,20   BTU(IT), conventional mmHg, light-year, parsec to 16 digits).214. **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.2223Limits of this evidence, stated plainly:2425- The Swift catalog and the Python reference were written by the same author in the same session. They are independent26  derivations, not independent authorship. A misconception shared by both (a wrong belief about what a unit *is*) would27  not be caught; a typing or arithmetic error in either one is.28- The NIST SP 811 guard values and most definitions were written from memory of the standard, not re-read from the29  PDF during this work. Two things were fetched and read on 2026-11-20: the CODATA 2022 value of the atomic mass30  constant (physics.nist.gov) and Schedules II and III of the Canada Weights and Measures Act (laws-lois.justice.gc.ca).31- The ISO 4217 names and minor-unit digits were written from memory and were not diffed against the SIX list.32- The ECB parser is tested against a document in the real `eurofxref-daily.xml` structure (namespaces, single-quoted33  attributes) with made-up rates. It was not run against a live download: the package and its tests do no networking.3435## Arithmetic3637- A conversion is an exact fraction of big integers (`ExactArithmetic`), divided once by schoolbook long division:38  the result is exact when it terminates within 38 significant digits, otherwise rounded half-to-even to 38 digits.39  `Conversion.isExactDecimal` tells which.40- Foundation's own `Decimal` division is **not** used: during development it returned `1/149597870700` with 2941  correct digits and kept only about five correct digits on a parsec ↔ femtometre round trip. `Decimal` is only the storage type; its42  `+`/`−` are used for the temperature offsets (exact while the sum fits 38 digits).43- Round trip a → b → a is exactly the starting value when the forward result terminated; otherwise it agrees to44  1e-36 (tested over every ordered pair of exact linear units of every category, six values each).45- `Decimal` exponents span 10⁻¹²⁸…10¹²⁷. Out-of-range results throw `UnitError.notRepresentable`; just inside the46  lower bound, low-order digits are dropped.47- `Double` path: decimal-faithful (shortest round-trip string → `Decimal` → nearest double). Outside 1e-60…1e60, and48  for infinities and NaN, it falls back to binary arithmetic with a few ulps of error.49- Rate conventions are `Double` only (`log1p`/`expm1`), checked against 962 closed-form values computed with Python50  `decimal` at 60 digits, to a relative 2e-13.5152## Units that are not exact5354| Unit | Flag | Value used | Source |55|---|---|---|---|56| parsec | irrational | 648 000/π au | IAU 2015 Resolution B2; π to 38 digits |57| radian, milliradian (against degree) | irrational | 180/π ° | SI Brochure 9th ed.; π to 38 digits |58| rad/s (against Hz) | irrational | 1/(2π) Hz | SI Brochure 9th ed.; π to 38 digits |59| dalton / unified atomic mass unit | approximate | 1.660 539 068 92(52) × 10⁻²⁷ kg | CODATA 2022 (measured, relative uncertainty 3.1 × 10⁻¹⁰) |60| Mach (15 °C, sea level) | approximate | 340.294 m/s | ISO 2533:1975 / ICAO Doc 7488 standard atmosphere; real Mach depends on temperature |61| tropical year | approximate | 365.242 19 d | mean tropical year near J2000; drifts about −0.5 s per century |6263## Exact by definition, but a convention was chosen6465| Family | Choice made | Source |66|---|---|---|67| 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) |68| 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 |69| US survey foot | 1200/3937 m, kept for old data, flagged deprecated | Mendenhall Order (1893); NIST SP 811 B.6 |70| league | 3 statute miles (other leagues exist) | convention |71| arpent (length and area) | 180 French feet of 12.789 in; 32 400 square French feet | Canada Weights and Measures Act, Schedule III |72| nautical mile, knot | 1852 m | International Hydrographic Conference, 1929 |73| astronomical unit, light-year | 149 597 870 700 m; c × 365.25 d | IAU 2012 Resolution B2; IAU (Julian year) |74| 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 |75| Imperial measures | gallon = 4.546 09 L; fl oz = 1/160 gal | UK Weights and Measures Act 1985; Canada W&M Act, Schedule II |76| metric cup, tablespoon, teaspoon | 250 mL, 15 mL, 5 mL (Australia uses a 20 mL tablespoon) | kitchen convention |77| barrel | 42 US gallons (petroleum) | NIST SP 811 B.8 |78| 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 |79| 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 |80| atm, Torr, at, bar | 101 325 Pa; atm/760; kgf/cm²; 10⁵ Pa | 10th CGPM (1954); NIST SP 811 B.8 |81| calorie | `cal`/`kcal` are thermochemical (4.184 J); `cal (IT)` = 4.1868 J is separate | NIST SP 811 B.8 |82| 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 |83| therm (US) | 1.054 804 × 10⁸ J | NIST SP 811 B.8 |84| ton of TNT | 10⁹ cal(th) = 4.184 × 10⁹ J | NIST SP 811 B.8 |85| electronvolt, elementary charge, c | SI 2019 defining constants | SI Brochure 9th ed. |86| 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 |87| 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 |88| data prefixes | kB = 1000 B (SI); KiB = 1024 B | SI Brochure 9th ed.; IEC 80000-13:2008 |89| 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 |90| curie, rad, rem, poise, stokes, Gal, erg, dyne, phot | CGS and legacy units with exact SI values | NIST SP 811 B.8 |91| foot-candle | 1 lm/ft² | NIST SP 811 B.8 |9293## Known limitations9495- **Compatibility is by category, not by dimension.** Energy and torque, frequency and radioactivity, absorbed dose96  and dose equivalent share a `UnitDimension`; the converter refuses to mix them. An expression engine that only97  compares dimensions would accept `J + N·m`.98- **Reference units are not always the coherent SI unit**: degree for angle (so that °, ′, ″, gon and turn stay exact99  among themselves), bit for data, km/L for fuel economy. `UnitDimension` of fuel economy is m⁻².100- **Bare aliases have a regional default** (`gal`, `pt`, `cup`, `mpg` → US; `ton` → short ton; `therm` → US;101  `year` → Gregorian mean year). In a Canadian app this default may be wrong for some users: the UI should show the102  explicit symbol (`gal (US)` / `gal (imp)`).103- **Symbols in the wrong case resolve to nothing** (`KM`, `kwh`, `mPa`). This is deliberate (a wrong SI prefix is a104  factor of 10⁹), but it is strict: the UI should fall back on `search`.105- **Missing on purpose or for lack of time**: compound units built on the fly (the catalog is a fixed list; `kW·h/100 km`106  or `N/mm²` do not exist unless listed), amount of substance and concentration, luminous flux and intensity, magnetic107  units, angular velocity other than rpm and rad/s, US dry measures, troy pound and pennyweight, boiler horsepower,108  the NATO mil, sidereal time, decibels and other logarithmic units.109- **Temperature below absolute zero is not rejected**; the converter is pure arithmetic.110- **Unit and category names are English only.**111- **SF Symbol names** were checked to exist with `NSImage(systemSymbolName:)` on macOS 27 only.112- **Rate conventions**: no day-count conventions (ACT/360, 30/360), no simple-interest or money-market yields, no113  bond-equivalent yield; "daily" is 365 periods, "weekly" is 52.114- **Currency**: 49 common ISO 4217 codes, not the full list (BGN is omitted: Bulgaria adopted the euro on115  2026-01-01). The ECB timestamp is set to 16:00 Frankfurt time on the document's date, the usual publication time;116  the document itself carries only a date. Staleness uses a single threshold and knows nothing about weekends or117  TARGET holidays.118
Files main
Menu

Theme