universal-physics-tensor 8.0.0 → 10.0.0

package/dist/dimensional/units.js

@@ -21,27 +21,32 @@
  * wins on a bare token, so `ms` stays a millisecond, `mm` a millimetre,
  * `mK` a millikelvin, and `Ts` a terasecond. Inside a larger expression the
  * prefixed reading competes with a heterogeneous product (`mK` is millikelvin
- * or metre·kelvin; `ms` is millisecond or metre·second). A homogeneous power
- * does not compete (`mm` is a millimetre, not metre·metre). `parseUnit` names
+ * or metre·kelvin; `ms` is millisecond or metre·second). A split that puts
+ * a prefix letter's own unit twice in a row is never a reading, because a
+ * power is written `m2` or `m^2`: `mm` is a millimetre, not metre·metre,
+ * and `mmin` is metre·minute or millimetre·inch, not metre·metre·inch.
+ * A unit that is not a prefix letter still juxtaposes with itself (`NN` is
+ * N·N). `parseUnit` names
  * every remaining reading and refuses. `convertValue` keeps the one reading
  * whose dimension is the declared unit. A token that is not one factor is a
  * product when exactly one split exists: `m2K` is `m^2·K`, `Vs` is `V·s`,
  * and `cm^2/Vs` is `cm^2/(V·s)`. Zero splits are an unknown unit. Two or more
  * splits name each reading and are refused (`mAs` is milliampere·second or
  * metre·ampere·second). An unknown token that ends in a digit stays unknown
- * when it is not that product.
- * `AU` is the same exact metre count as `au`. `Msun` is `M_SUN_SI` kilograms; `Msun_iau` is
- * `GM_SUN_SI / G_SI`. `myr` is a milliyear because `m` is the SI prefix.
- * `eV` takes an SI prefix, so `GeV` is 10⁹ eV in joules. `nat` is the
- * coherent information unit (scale 1); `bit` is ln 2 nat. Neither takes a
- * prefix.
+ * when it is not that product. A numerator that is the single token `1` is
+ * the dimensionless unit, so `1/s` is a reciprocal second and `1/m^3` a
+ * number density; `1` is not a symbol anywhere else.
+ * The table is data: `data/units.json`, loaded and validated by
+ * `unit-data.ts`. Every row, prefix, refused spelling, prefix letter, affine
+ * scale and spelling note is a row there, with the reason as its `comment`;
+ * this module holds the grammar. `myr` is a milliyear because `m` is the SI
+ * prefix, and `eV` takes one, so `GeV` is 10⁹ eV in joules.
  *
  * @module dimensional/units
  */
-import { toSiDimensionVector } from '@danielsimonjr/mathts-core';
-import { unit } from '@danielsimonjr/mathts-functions';
 import { equals, format, multiply, power } from './algebra.js';
-import { C_SI, E_SI, G_SI, GM_SUN_SI, M_SUN_SI } from '../core/constants.js';
+import { addScales, decimalScale, divideScales, multiplyScales, powerScale, ratioScale, scaleToNumber, solidusSides, UNIT_SCALE, } from './exact-scale.js';
+import { UNIT_DATA } from './unit-data.js';
 /** Thrown for any input that does not parse as a value with a known unit. @public */
 export class UnitError extends Error {
     constructor(message) {
@@ -49,126 +54,93 @@ export class UnitError extends Error {
         this.name = 'UnitError';
     }
 }
+/** A symbol no table row and no prefix spells. @public */
+export class UnknownUnitError extends UnitError {
+    symbol;
+    constructor(symbol) {
+        super(`unknown unit '${symbol}'`);
+        this.symbol = symbol;
+        this.name = 'UnknownUnitError';
+    }
+}
+/**
+ * A unit the reader recognizes and refuses: a logarithmic or ratio unit, an
+ * ambiguous name such as `ton`, or an affine temperature inside a compound.
+ * @public
+ */
+export class UnitRefusedError extends UnitError {
+    constructor(message) {
+        super(message);
+        this.name = 'UnitRefusedError';
+    }
+}
+/** A unit expression with more than one dimensionally distinct reading. @public */
+export class AmbiguousUnitError extends UnitError {
+    text;
+    readings;
+    constructor(text, readings) {
+        super(`'${text}' is ambiguous: ${readings.join(' or ')}`);
+        this.text = text;
+        this.readings = readings;
+        this.name = 'AmbiguousUnitError';
+    }
+}
 const D = (p) => ({ L: 0, M: 0, T: 0, I: 0, Theta: 0, N: 0, J: 0, ...p });
-const JOULE = D({ L: 2, M: 1, T: -2 });
 const DIMENSIONLESS = D({});
-/** symbol → [scale to SI base, dimension, takes an SI prefix]. */
-const UNITS = new Map([
-    ['m', [1, D({ L: 1 }), true]],
-    ['g', [1e-3, D({ M: 1 }), true]],
-    ['s', [1, D({ T: 1 }), true]],
-    ['K', [1, D({ Theta: 1 }), true]],
-    ['A', [1, D({ I: 1 }), true]],
-    ['mol', [1, D({ N: 1 }), true]],
-    ['Hz', [1, D({ T: -1 }), true]],
-    ['N', [1, D({ L: 1, M: 1, T: -2 }), true]],
-    ['Pa', [1, D({ L: -1, M: 1, T: -2 }), true]],
-    ['J', [1, JOULE, true]],
-    ['W', [1, D({ L: 2, M: 1, T: -3 }), true]],
-    ['C', [1, D({ T: 1, I: 1 }), true]],
-    ['V', [1, D({ L: 2, M: 1, T: -3, I: -1 }), true]],
-    ['ohm', [1, D({ L: 2, M: 1, T: -3, I: -2 }), true]],
-    ['Ω', [1, D({ L: 2, M: 1, T: -3, I: -2 }), true]],
-    ['S', [1, D({ L: -2, M: -1, T: 3, I: 2 }), true]],
-    ['F', [1, D({ L: -2, M: -1, T: 4, I: 2 }), true]],
-    ['eV', [E_SI, JOULE, true]],
-    // Information. A nat is the coherent dimensionless unit; a bit is ln 2 nat.
-    // Exact, so neither takes a prefix (`kbit` is not a kilobit).
-    ['nat', [1, DIMENSIONLESS, false]],
-    ['bit', [Math.LN2, DIMENSIONLESS, false]],
-    ['rad', [1, DIMENSIONLESS, true]],
-    ['deg', [Math.PI / 180, DIMENSIONLESS, false]],
-    ['min', [60, D({ T: 1 }), false]],
-    ['h', [3600, D({ T: 1 }), false]],
-    ['d', [86400, D({ T: 1 }), false]],
-    // The Julian year, the year the orbital evaluators take.
-    ['yr', [365.25 * 86400, D({ T: 1 }), true]],
-    ['au', [149597870700, D({ L: 1 }), false]],
-    ['AU', [149597870700, D({ L: 1 }), false]],
-    // The solar mass the evaluators use, not the IAU nominal value.
-    ['Msun', [M_SUN_SI, D({ M: 1 }), false]],
-    // GM☉/G, so G × Msun_iau is the IAU solar mass parameter.
-    ['Msun_iau', [GM_SUN_SI / G_SI, D({ M: 1 }), false]],
-    // Tesla. An exact `T` still wins over the tera prefix, so `Ts` is a
-    // terasecond. The prefix flag is what lets `nT` and `uT` parse.
-    ['T', [1, D({ M: 1, T: -2, I: -1 }), true]],
-    // Gauss = 10⁻⁴ T. Exact, so `GPa` stays gigapascal (prefix G + Pa) and bare `G` is gauss.
-    // The spelled name is the same unit. It does not take a prefix (`kgauss` is not a kilogauss).
-    ['G', [1e-4, D({ M: 1, T: -2, I: -1 }), false]],
-    ['gauss', [1e-4, D({ M: 1, T: -2, I: -1 }), false]],
-    ['Gauss', [1e-4, D({ M: 1, T: -2, I: -1 }), false]],
-    ['bar', [1e5, D({ L: -1, M: 1, T: -2 }), true]],
-    ['atm', [101325, D({ L: -1, M: 1, T: -2 }), false]],
-    ['angstrom', [1e-10, D({ L: 1 }), false]],
-    ['Angstrom', [1e-10, D({ L: 1 }), false]],
-    ['Å', [1e-10, D({ L: 1 }), false]],
-    // IAU-style parsec; the prefix applies, so `Mpc` is a megaparsec.
-    ['pc', [3.0856775814913673e16, D({ L: 1 }), true]],
-    ['ly', [C_SI * 365.25 * 86400, D({ L: 1 }), false]],
-    // CGPM 1964: 1 L = 1 dm³ = 10⁻³ m³ exactly. Prefixable, so mL is a millilitre.
-    // `l` is the same litre. Bare `mL` stays the prefix; `mol/mL` competes with metre·litre.
-    ['L', [1e-3, D({ L: 3 }), true]],
-    ['l', [1e-3, D({ L: 3 }), true]],
-    // Thermochemical calorie: 1 cal_th = 4.184 J exactly (NIST). Not cal_IT = 4.1868 J.
-    // Prefixable, so kcal is 4184 J.
-    ['cal', [4.184, JOULE, true]],
-    // International Steam Table BTU: cal_IT × (lb/g) / (°F per 1.8 °C).
-    // 4.1868 × 453.59237 / 1.8 J exactly. Not the thermochemical calorie.
-    ['BTU', [(4.1868 * 453.59237) / 1.8, JOULE, false]],
-    // psi = lbf/in². lbf = 0.45359237 kg × 9.80665 m/s² (1959 pound × standard gravity).
-    // inch = 0.0254 m exactly.
-    ['psi', [(0.45359237 * 9.80665) / (0.0254 * 0.0254), D({ L: -1, M: 1, T: -2 }), false]],
-    // torr = 1/760 of a standard atmosphere = 101325/760 Pa exactly. Prefixable (mtorr).
-    ['torr', [101325 / 760, D({ L: -1, M: 1, T: -2 }), true]],
-    // Conventional millimetre of mercury, 133.322387415 Pa exactly (NIST SP 811).
-    // Not the torr, and not `mm` × `Hg`.
-    ['mmHg', [133.322387415, D({ L: -1, M: 1, T: -2 }), false]],
-    // Poise = 0.1 Pa·s exactly. Prefixable, so cP = 10⁻³ Pa·s. Exact `P` wins over peta.
-    ['P', [0.1, D({ L: -1, M: 1, T: -1 }), true]],
-    // Rankine is proportional: K = °R × 5/9. Not affine.
-    ['degR', [5 / 9, D({ Theta: 1 }), false]],
-    ['°R', [5 / 9, D({ Theta: 1 }), false]],
-    // Revolutions per minute = 1/60 Hz. Prefixable, so krpm is a kilorevolution per minute.
-    ['rpm', [1 / 60, D({ T: -1 }), true]],
-    // Mechanical horsepower = 550 ft·lbf/s. ft = 0.3048 m.
-    ['hp', [550 * 0.3048 * 0.45359237 * 9.80665, D({ L: 2, M: 1, T: -3 }), false]],
-]);
-const CELSIUS_OFFSET_K = 273.15;
-const FAHRENHEIT_SCALE = 5 / 9;
-/** Lone spellings. A compound that contains one is refused. */
-const AFFINE = [
-    { id: 'celsius', scale: 1, offset: CELSIUS_OFFSET_K, symbols: ['degC', '°C'] },
-    {
-        id: 'fahrenheit',
-        scale: FAHRENHEIT_SCALE,
-        offset: CELSIUS_OFFSET_K - 32 * FAHRENHEIT_SCALE,
-        symbols: ['degF', '°F'],
-    },
-];
+/** symbol → exact scale to SI base, dimension, prefixability, cycle count. Rows are `data/units.json`. */
+const UNITS = UNIT_DATA.units;
+/** Units that are a ratio or a log scale, and the reason each is not a plain factor. */
+const REFUSED_UNITS = UNIT_DATA.refused;
+/**
+ * Letters that are both an SI prefix and a unit of their own. Such a token
+ * reads as the prefix reading and not as the unit times the rest: `Gyr` is a
+ * gigayear. The file's `prefixLetterUnits.comment` says why `m` is not one.
+ */
+const PREFIX_LETTER_UNITS = UNIT_DATA.prefixLetterUnits;
+/** Kelvin at 0 °C, exactly. */
+const CELSIUS_OFFSET_K = UNIT_DATA.iceKelvin;
+/**
+ * Lone spellings. A compound that contains one is refused. The schema's `id`
+ * enum is {@link AffineTemperature}, held equal by a test: the public type
+ * promises callers these ids, so a new affine scale is an API change.
+ */
+const AFFINE = UNIT_DATA.affine;
+/** Kelvin at a reading of zero, exactly: 273.15 − icePoint × scale. */
+function affineOffset(row) {
+    return addScales(CELSIUS_OFFSET_K, multiplyScales(ratioScale(-1, 1), row.icePoint, row.scale));
+}
+const fractionText = (s) => (s.den === 1n ? String(s.num) : `${s.num}/${s.den}`);
+/**
+ * How a reading on an affine scale becomes kelvin, from the row's scale and
+ * ice point: `absolute: (degF − 32) × 5/9 + 273.15`, `a difference: × 5/9, no offset`.
+ * @internal
+ */
+export function affineReadingNote(affine, reading) {
+    const row = AFFINE.find((candidate) => candidate.id === affine);
+    const unitScale = row.scale.num === row.scale.den;
+    if (reading === 'difference')
+        return unitScale ? 'a difference: no offset' : `a difference: × ${fractionText(row.scale)}, no offset`;
+    const kelvin = String(scaleToNumber(CELSIUS_OFFSET_K));
+    if (unitScale && row.icePoint.num === 0n)
+        return `absolute: + ${kelvin}`;
+    const shifted = row.icePoint.num === 0n ? row.symbols[0] : `(${row.symbols[0]} − ${fractionText(row.icePoint)})`;
+    return `absolute: ${unitScale ? shifted : `${shifted} × ${fractionText(row.scale)}`} + ${kelvin}`;
+}
 function affineRow(text) {
-    return AFFINE.find((row) => row.symbols.includes(text));
-}
-const PREFIXES = new Map([
-    ['Y', 1e24], ['Z', 1e21], ['E', 1e18], ['P', 1e15], ['T', 1e12], ['G', 1e9], ['M', 1e6], ['k', 1e3],
-    ['h', 1e2], ['da', 1e1], ['d', 1e-1], ['c', 1e-2], ['m', 1e-3], ['u', 1e-6], ['µ', 1e-6], ['μ', 1e-6],
-    ['n', 1e-9], ['p', 1e-12], ['f', 1e-15], ['a', 1e-18], ['z', 1e-21], ['y', 1e-24],
-]);
-function parseSymbol(sym) {
-    const parsed = trySymbol(sym);
-    if (parsed !== null)
-        return parsed;
-    throw new UnitError(`unknown unit '${sym}'`);
+    return AFFINE.find((candidate) => candidate.symbols.includes(text));
 }
+const PREFIXES = UNIT_DATA.prefixes;
 function trySymbol(sym) {
     const exact = UNITS.get(sym);
     if (exact !== undefined)
-        return [exact[0], exact[1]];
+        return { scale: exact.scale, dim: exact.dim, cycles: exact.cycles === true ? 1 : 0 };
     for (const [p, f] of PREFIXES) {
         if (!sym.startsWith(p) || sym.length === p.length)
             continue;
         const base = UNITS.get(sym.slice(p.length));
-        if (base !== undefined && base[2])
-            return [f * base[0], base[1]];
+        if (base !== undefined && base.prefixable) {
+            return { scale: multiplyScales(f, base.scale), dim: base.dim, cycles: base.cycles === true ? 1 : 0 };
+        }
     }
     return null;
 }
@@ -182,7 +154,7 @@ function tryOneFactor(token) {
         exp = Number(caret[2]);
     }
     else {
-        const uni = /^(.*?)([¹²³])$/.exec(token);
+        const uni = /^(.*?)(⁻?[¹²³])$/.exec(token);
         const superExp = uni === null ? undefined : SUPERSCRIPT[uni[2]];
         if (uni !== null && superExp !== undefined && uni[1].length > 0) {
             base = uni[1];
@@ -199,7 +171,7 @@ function tryOneFactor(token) {
     const parsed = trySymbol(base);
     if (parsed === null || !Number.isFinite(exp))
         return null;
-    return { base, exp, scale: parsed[0], dim: parsed[1] };
+    return { base, exp, scale: parsed.scale, dim: parsed.dim, cycles: parsed.cycles };
 }
 function formatReading(factors) {
     return factors.map((factor) => (factor.exp === 1 ? factor.base : `${factor.base}^${factor.exp}`)).join('·');
@@ -212,24 +184,25 @@ function attachedUnit(symbol) {
         if (!symbol.startsWith(prefix) || symbol.length === prefix.length)
             continue;
         const base = symbol.slice(prefix.length);
-        const row = UNITS.get(base);
-        if (row !== undefined && row[2])
+        const unitRow = UNITS.get(base);
+        if (unitRow !== undefined && unitRow.prefixable)
             return base;
     }
     return null;
 }
 /**
- * A product of the same unprefixed unit the prefix attaches to (`mm` = m·m,
- * `mm2` = m·m²). Powers are written `m2` / `m^2`, so this reading does not
- * compete with the prefix.
+ * `X·X` where `XX` is X's own prefix spelling (`m·m` beside `mm`, `d·d`
+ * beside `dd`): not a split, because a power is written `X2` or `X^2`. A
+ * run of a unit that is not also a prefix letter (`N·N`) stays a product.
  */
-function homogeneousPower(single, product) {
-    const unit = attachedUnit(single.base);
-    if (unit === null)
-        return false;
-    return product.every((factor) => factor.base === unit && attachedUnit(factor.base) === null);
+function prefixRun(last, next) {
+    return last.base === next.base && attachedUnit(last.base + next.base) === last.base;
 }
-/** Every way to split `token` into one or more factors. A one-factor token is included. */
+/**
+ * Every way to split `token` into one or more factors. A one-factor token is
+ * included. A split that puts a prefix letter's own unit twice in a row
+ * (`m·m`, `m·m²`, `m·m·in`) is not a way, inside any split.
+ */
 function segmentations(token) {
     const ways = Array.from({ length: token.length + 1 }, () => []);
     ways[0].push([]);
@@ -240,8 +213,11 @@ function segmentations(token) {
             const factor = tryOneFactor(token.slice(i, j));
             if (factor === null)
                 continue;
-            for (const prev of ways[i])
+            for (const prev of ways[i]) {
+                if (prev.length > 0 && prefixRun(prev[prev.length - 1], factor))
+                    continue;
                 ways[j].push([...prev, factor]);
+            }
         }
     }
     const unique = new Map();
@@ -252,25 +228,35 @@ function segmentations(token) {
 /**
  * Ways to read one token. A bare expression keeps a one-factor reading and
  * does not also split it. Inside a compound, a prefixed factor also competes
- * with each heterogeneous product. A homogeneous power does not.
+ * with each heterogeneous product; `segmentations` has already dropped the
+ * homogeneous runs.
  */
-function tokenWays(token, compete) {
+function tokenWays(token, compete, side) {
+    const refused = REFUSED_UNITS.get(token);
+    if (refused !== undefined)
+        throw new UnitRefusedError(refused);
     const single = tryOneFactor(token);
     if (single !== null && !compete)
         return [[single]];
-    const products = segmentations(token).filter((way) => way.length > 1);
-    const extra = single === null ? products : products.filter((way) => !homogeneousPower(single, way));
+    // A prefixed numerator token is the prefix reading: `mN/m` is millinewton per metre.
+    // A denominator keeps the product readings (`W/mK`), and a target dimension chooses.
+    if (single !== null && side === 'numerator')
+        return [[single]];
+    const prefixWins = single !== null && PREFIX_LETTER_UNITS.has(token[0]) && attachedUnit(single.base) !== null;
+    const products = segmentations(token)
+        .filter((way) => way.length > 1)
+        .filter(() => !prefixWins);
     const ways = [];
     if (single !== null)
         ways.push([single]);
-    for (const way of extra)
+    for (const way of products)
         ways.push(way);
     const unique = new Map();
     for (const way of ways)
         unique.set(formatReading(way), way);
     const list = [...unique.values()];
     if (list.length === 0)
-        throw new UnitError(`unknown unit '${token}'`);
+        throw new UnknownUnitError(token);
     return list;
 }
 function cartesian(lists) {
@@ -285,55 +271,82 @@ function cartesian(lists) {
     return acc;
 }
 function sideTokens(text) {
-    return text.split(/[*·\s]+/).filter((part) => part.length > 0);
+    return text.split(/[*·\s]+|(?<=[A-Za-zµμΩ])\.(?=[A-Za-zµμΩ])/).filter((part) => part.length > 0);
 }
 function formatSide(tokens) {
     return tokens.map((factors) => formatReading(factors)).join('·');
 }
 function formatExpression(num, den) {
-    const numerator = formatSide(num);
+    // An empty numerator over a denominator is the dimensionless 1: `1/s`.
+    const numerator = num.length === 0 ? '1' : formatSide(num);
     if (den.length === 0)
         return numerator;
     const denominator = formatSide(den);
     return denominator.includes('·') ? `${numerator}/(${denominator})` : `${numerator}/${denominator}`;
 }
 function accumulate(tokens, sign) {
-    let scale = 1;
+    let scale = UNIT_SCALE;
     let dim = DIMENSIONLESS;
+    let cycles = 0;
     for (const factors of tokens) {
         for (const factor of factors) {
             const n = sign * factor.exp;
-            scale *= factor.scale ** n;
+            scale = multiplyScales(scale, powerScale(factor.scale, n));
             dim = multiply(dim, power(factor.dim, n));
+            cycles += factor.cycles * n;
         }
     }
-    return { scale, dim };
+    return { scale, dim, cycles };
+}
+function reading(exact, dim, label, cycles, affine) {
+    return {
+        scale: scaleToNumber(exact),
+        exact,
+        dim,
+        label,
+        cycles,
+        ...(affine === undefined ? {} : { affine }),
+    };
 }
-/** Every dimensionally distinct spelling of one unit expression. */
+/**
+ * Every dimensionally distinct reading of one unit expression.
+ *
+ * The unit grammar is not the formula grammar, and the difference is
+ * deliberate: a unit symbol is not an identifier (a prefix, a glued product
+ * or a glued power lives inside one token: `mN`, `m2K`, `Vs`, `K²`, `°C`,
+ * `%`), and everything after the first `/` is the denominator, the
+ * single-solidus convention of ISO 80000-1 (`W/m*K` is W·m⁻¹·K⁻¹), where the
+ * formula grammar would read `(W/m)·K`.
+ * @internal
+ */
 function unitReadings(text) {
     const t = text.trim();
     if (t === '' || t === '1')
-        return [{ scale: 1, dim: DIMENSIONLESS, label: '1' }];
+        return [reading(UNIT_SCALE, DIMENSIONLESS, '1', 0)];
     const affine = affineRow(t);
-    if (affine !== undefined) {
-        return [{ scale: affine.scale, dim: D({ Theta: 1 }), affine: affine.id, label: t }];
-    }
-    if (AFFINE.some((row) => row.symbols.some((symbol) => t.includes(symbol))) ||
+    if (affine !== undefined)
+        return [reading(affine.scale, D({ Theta: 1 }), t, 0, affine.id)];
+    if (AFFINE.some((candidate) => candidate.symbols.some((symbol) => t.includes(symbol))) ||
         /deg\s+[CFcf]|°\s*[CFcf]/.test(t)) {
-        throw new UnitError('an affine temperature cannot be part of a compound unit; give K');
+        throw new UnitRefusedError('an affine temperature cannot be part of a compound unit; give K');
     }
-    const parts = t.split('/');
-    if (parts.length > 2)
-        throw new UnitError(`'${t}' has more than one '/'; put the whole denominator after one '/'`);
+    // An operator with nothing on one side (`m/`, `m//s`, `m*`, `*m`, `m/*s`) is not a unit
+    // text; it was read as if the empty factor were 1 (Tom's second round). A leading `/`
+    // (`/s`) stays the dimensionless numerator.
+    if (/[*·/]\s*$|^\s*[*·]|[*·/]\s*[*·/]/.test(t))
+        throw new UnknownUnitError(t);
+    // A chain is one denominator: `km/s/Mpc` is km/(s·Mpc), the way the Hubble constant is written.
+    const sides = solidusSides(t);
     const compete = /[*·/\s]/.test(t);
-    const numerator = sideTokens(parts[0]);
-    const denominatorText = parts.length === 1 ? '' : parts[1].replace(/^\((.*)\)$/, '$1');
-    const denominator = denominatorText === '' ? [] : sideTokens(denominatorText);
+    const numeratorTokens = sideTokens(sides.numerator);
+    // A numerator that is the single token `1` is the dimensionless unit: `1/s`, `1/m^3`.
+    const numerator = numeratorTokens.length === 1 && numeratorTokens[0] === '1' ? [] : numeratorTokens;
+    const denominator = sides.denominator === '' ? [] : sideTokens(sides.denominator);
     // `/s` is a dimensionless numerator over seconds. A bare `/` is not a unit.
     if (numerator.length === 0 && denominator.length === 0)
-        throw new UnitError(`unknown unit '${t}'`);
-    const numWays = numerator.map((token) => tokenWays(token, compete));
-    const denWays = denominator.map((token) => tokenWays(token, compete));
+        throw new UnknownUnitError(t);
+    const numWays = numerator.map((token) => tokenWays(token, compete, 'numerator'));
+    const denWays = denominator.map((token) => tokenWays(token, compete, 'denominator'));
     const numCombos = numerator.length === 0 ? [[]] : cartesian(numWays);
     const denCombos = denominator.length === 0 ? [[]] : cartesian(denWays);
     const unique = new Map();
@@ -342,180 +355,162 @@ function unitReadings(text) {
             const n = accumulate(num, 1);
             const d = accumulate(den, -1);
             const label = formatExpression(num, den);
-            unique.set(label, { scale: n.scale * d.scale, dim: multiply(n.dim, d.dim), label });
+            unique.set(label, reading(multiplyScales(n.scale, d.scale), multiply(n.dim, d.dim), label, n.cycles + d.cycles));
         }
     }
     return [...unique.values()];
 }
-function ambiguousMessage(text, readings) {
-    return `'${text}' is ambiguous: ${readings.map((reading) => reading.label).join(' or ')}`;
-}
-const SUPERSCRIPT = { '¹': 1, '²': 2, '³': 3 };
+const SUPERSCRIPT = { '¹': 1, '²': 2, '³': 3, '⁻¹': -1, '⁻²': -2, '⁻³': -3 };
 /**
- * Spellings that convert correctly and still mean something else to a reader.
- * `myr` is a milliyear, `Msun` is `M_SUN_SI`, bare `G` is the gauss, bare `T`
- * is the tesla, and bare `A` is the ampere rather than the angstrom.
+ * Spellings that convert correctly and still mean something else to a reader:
+ * the `spellingNotes` of `data/units.json` for each symbol in `given`, in file
+ * order. `myr` is a milliyear, bare `G` is the gauss, bare `A` the ampere.
  * @internal
  */
 export function unitConventionNotes(given) {
-    const notes = [];
-    const symbols = given.split(/[*·/\s^0-9()+-]+/).filter((s) => s.length > 0);
-    if (symbols.includes('myr')) {
-        notes.push('myr is a milliyear (the SI prefix m on yr = 0.001 yr), not a million years; a million years is Myr');
-    }
-    if (symbols.includes('Msun')) {
-        notes.push(`Msun is ${M_SUN_SI} kg (M_SUN_SI), not GM☉/G; G×Msun is about 3.0e-4 high versus the IAU GM☉. Use the unit Msun_iau, or the eval name GM_sun, for GM_SUN_SI`);
-    }
-    if (symbols.includes('G'))
-        notes.push('bare G is the gauss (1e-4 T); GPa is still a gigapascal');
-    if (symbols.includes('T'))
-        notes.push('bare T is the tesla; Ts is a terasecond');
-    if (symbols.includes('A'))
-        notes.push('bare A is the ampere, not the angstrom; write angstrom or Å for 10^-10 m');
-    if (symbols.includes('P'))
-        notes.push('bare P is the poise (0.1 Pa·s); PV is still a petavolt');
-    return notes;
+    const symbols = new Set(given.split(/[*·/\s^0-9()+-]+/).filter((s) => s.length > 0));
+    return [...UNIT_DATA.spellingNotes].filter(([spelling]) => symbols.has(spelling)).map(([, note]) => note);
 }
-/** Parse a unit expression; the empty string is dimensionless. @public */
-export function parseUnit(text) {
+/** The one reading of a unit expression; more than one is refused. @internal */
+export function readUnit(text) {
     const t = text.trim();
     const readings = unitReadings(t);
     if (readings.length !== 1)
-        throw new UnitError(ambiguousMessage(t, readings));
-    const reading = readings[0];
-    return {
-        scale: reading.scale,
-        dim: reading.dim,
-        ...(reading.affine !== undefined ? { affine: reading.affine } : {}),
-    };
+        throw new AmbiguousUnitError(t, readings.map((r) => r.label));
+    return readings[0];
 }
-/** Kelvin added when this affine unit is an absolute point. @internal */
-export function affineAbsoluteOffsetK(id) {
-    const row = AFFINE.find((candidate) => candidate.id === id);
-    if (row === undefined)
-        throw new UnitError(`unknown affine temperature '${id}'`);
-    return row.offset;
+/** Parse a unit expression; the empty string is dimensionless. @public */
+export function parseUnit(text) {
+    const r = readUnit(text);
+    return { scale: r.scale, dim: r.dim, ...(r.affine !== undefined ? { affine: r.affine } : {}) };
 }
-/** Kelvin from an affine or proportional reading. A difference drops the offset. */
-function kelvinFrom(value, unit, reading) {
+/** The SI magnitude of `magnitude` in `unit`, exactly. An absolute affine reading adds its offset. */
+function siMagnitude(magnitude, unit, temperature) {
+    const scaled = multiplyScales(magnitude, unit.exact);
     const row = unit.affine === undefined ? undefined : AFFINE.find((candidate) => candidate.id === unit.affine);
-    const offset = row !== undefined && reading === 'absolute' ? row.offset : 0;
-    return value * unit.scale + offset;
+    return row !== undefined && temperature === 'absolute' ? addScales(scaled, affineOffset(row)) : scaled;
+}
+const FRACTION = /^\s*([+-]?(?:\d+\.?\d*|\.\d+))\s*\/\s*((?:\d+\.?\d*|\.\d+))\s*$/;
+const NUMBER_THEN_REST = /^\s*([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*(.*?)\s*$/;
+/**
+ * `raw` split into an exact decimal magnitude and the unit text after it, or
+ * null when `raw` is not a number followed by an optional unit. A plain
+ * fraction (`1/3`) is a number. Text that begins with an operator (`*h`,
+ * `·c`) is an expression, not a unit.
+ * @internal
+ */
+function splitQuantityLiteral(raw) {
+    const fraction = FRACTION.exec(raw);
+    if (fraction !== null) {
+        const den = decimalScale(fraction[2]);
+        if (den.num !== 0n)
+            return { magnitude: divideScales(decimalScale(fraction[1]), den), unit: '' };
+    }
+    const m = NUMBER_THEN_REST.exec(raw);
+    if (m === null)
+        return null;
+    const unit = m[2];
+    if (unit.startsWith('*') || unit.startsWith('·'))
+        return null;
+    const magnitude = decimalScale(m[1]);
+    return magnitude === null ? null : { magnitude, unit };
+}
+function finiteLiteral(raw, value) {
+    if (!Number.isFinite(value))
+        throw new UnitError(`'${raw}' is not a finite number`);
+    return value;
+}
+/**
+ * Read `raw` as one number with an optional unit, in SI. Null when `raw` is
+ * not that form or names a unit no row spells, so the caller can read it as
+ * an expression. A refused unit and an ambiguous one throw. The value may be
+ * non-finite (`1e999`); the caller owns that refusal and its error class.
+ * @internal
+ */
+export function readQuantityLiteral(raw, temperature = 'absolute') {
+    const literal = splitQuantityLiteral(raw);
+    if (literal === null)
+        return null;
+    if (literal.unit === '') {
+        return { value: scaleToNumber(literal.magnitude), dim: DIMENSIONLESS, unit: '', cycles: 0 };
+    }
+    let unit;
+    try {
+        unit = readUnit(literal.unit);
+    }
+    catch (error) {
+        if (error instanceof UnknownUnitError)
+            return null;
+        throw error;
+    }
+    return {
+        value: scaleToNumber(siMagnitude(literal.magnitude, unit, temperature)),
+        dim: unit.dim,
+        unit: literal.unit,
+        cycles: unit.cycles,
+        ...(unit.affine === undefined ? {} : { affine: unit.affine }),
+    };
 }
 /**
  * Convert `raw` (`<number>[unit]`) into `target` (a unit expression). A bare
  * number is taken to be in `target` already. The dimensions must agree.
  *
+ * The magnitude, the unit scales and the target scale are multiplied as
+ * exact rationals and rounded once, so `1 g/cm^3` in `kg/m^3` is 1000.
+ *
  * @returns the value in `target`, and the unit the user gave (`''` for none).
  * @public
  */
-export function convertValue(raw, target, reading = 'absolute') {
-    const m = /^\s*([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*(.*?)\s*$/.exec(raw);
-    if (m === null)
+export function convertValue(raw, target, temperature = 'absolute') {
+    const literal = splitQuantityLiteral(raw);
+    if (literal === null)
         throw new UnitError(`'${raw}' is not a number with an optional unit`);
-    const v = Number(m[1]);
-    const given = m[2];
-    if (!Number.isFinite(v))
-        throw new UnitError(`'${raw}' is not a finite number`);
-    if (given === '')
-        return { value: v, given };
+    if (literal.unit === '')
+        return { value: finiteLiteral(raw, scaleToNumber(literal.magnitude)), given: '' };
+    const given = literal.unit;
     const readings = unitReadings(given);
-    const to = parseUnit(target);
+    const to = readUnit(target);
     if (to.affine !== undefined)
         throw new UnitError(`a declared unit cannot be affine ('${target}')`);
     const matched = readings.filter((candidate) => equals(candidate.dim, to.dim));
     if (matched.length !== 1) {
         if (readings.length > 1)
-            throw new UnitError(ambiguousMessage(given, readings));
+            throw new AmbiguousUnitError(given, readings.map((r) => r.label));
         const from = readings[0];
         if (from === undefined)
-            throw new UnitError(`unknown unit '${given}'`);
+            throw new UnknownUnitError(given);
         throw new UnitError(`'${given}' is ${format(from.dim)}, but this input is ${format(to.dim)} (${target || 'dimensionless'})`);
     }
     const from = matched[0];
-    const local = kelvinFrom(v, from, reading) / to.scale;
-    // MathTS `unit` + `toSI` is the conversion when it reads the same quantity.
-    // A temperature difference must not take the absolute offset `toSI` adds.
-    // `bit` is ln 2 nat here; MathTS reads `bit` as 1. Symbols MathTS does not
-    // have (a solar mass, a Julian year, the gauss) stay on the table above.
-    const via = mathTsRatio(v, given, target);
-    if (via !== undefined && sameQuantity(via, local))
-        return { value: via, given };
-    return { value: local, given };
-}
-/** Spellings MathTS's unit parser accepts for the same UPT symbol. */
-function mathTsSpelling(text) {
-    return text
-        .replaceAll('µ', 'u')
-        .replaceAll('μ', 'u')
-        .replaceAll('Ω', 'ohm')
-        .replaceAll('Å', 'angstrom')
-        .replaceAll('°C', 'degC');
-}
-/** The 7-base record for a MathTS length-10 exponent vector. Angle, bit, and solid angle are dropped. */
-function dimensionFromUnitVector(vector) {
-    const v = toSiDimensionVector(vector, { ignoreExtra: true });
-    return { L: v[0], M: v[1], T: v[2], I: v[3], Theta: v[4], N: v[5], J: v[6] };
-}
-function mathTsReading(value, unitText) {
-    // `unit` is a typed-function; its declared return is `unknown`.
-    const created = unit(value, mathTsSpelling(unitText));
-    const n = Number(created.toSI().value);
-    if (!Number.isFinite(n))
-        throw new Error('non-finite SI magnitude');
-    return { si: n, dim: dimensionFromUnitVector(created.dimensions) };
-}
-function mathTsRatio(value, given, target) {
-    try {
-        const from = mathTsReading(value, given);
-        const to = mathTsReading(1, target);
-        if (to.si === 0)
-            return undefined;
-        // A scale match is not enough when the 7-base dimensions differ.
-        if (!equals(from.dim, parseUnit(given).dim))
-            return undefined;
-        if (!equals(to.dim, parseUnit(target).dim))
-            return undefined;
-        return from.si / to.si;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * MathTS's SI value for `magnitude` of `unitText`, when that value and the
- * 7-base dimension agree with `local`. Affine °C stays on the local offset.
- * A symbol MathTS lacks, or a scale it disagrees with (`bit` is 1 there and
- * ln 2 here; a solar mass, a Julian year, and the gauss are absent), returns
- * undefined so the caller keeps the local table.
- *
- * @internal
- */
-export function mathTsAgreedQuantity(magnitude, unitText, local) {
-    if (local.affine !== undefined)
-        return undefined;
-    try {
-        const read = mathTsReading(magnitude, unitText);
-        if (!sameQuantity(read.si, magnitude * local.scale))
-            return undefined;
-        if (!equals(read.dim, local.dim))
-            return undefined;
-        return { value: read.si, dim: read.dim };
-    }
-    catch {
-        return undefined;
-    }
-}
-function sameQuantity(got, expected) {
-    const scale = Math.max(Math.abs(got), Math.abs(expected));
-    return Math.abs(got - expected) <= 1e-9 * scale;
+    const value = scaleToNumber(divideScales(siMagnitude(literal.magnitude, from, temperature), to.exact));
+    return {
+        value: finiteLiteral(raw, value),
+        given,
+        ...(from.cycles === 0 ? {} : { cycles: from.cycles }),
+        ...(from.affine === undefined ? {} : { affine: from.affine }),
+    };
 }
 /** The dimension of a declared unit expression. @internal */
 export function unitDimension(unit) {
     return parseUnit(unit).dim;
 }
-/** The tables conversion reads, for the CLI record's fingerprint (`src/cli/record-tables.ts`). @internal */
+/** The symbols the unit table spells, with their exact scales, for the agreement test against MathTS. @internal */
+export function unitRows() {
+    return UNITS;
+}
+/**
+ * The tables conversion reads, for the CLI record's fingerprint (`src/cli/record-tables.ts`):
+ * each row's scale, dimension, prefixability and `cycles` flag (which multiplies an angular
+ * input by 2π), the prefixes, the Celsius offset, and the SHA-256 of `data/units.json`, so a
+ * refused spelling, a prefix letter, an affine row or a note that changes changes the fingerprint too.
+ * @internal
+ */
 export function unitTables() {
-    return { units: UNITS, prefixes: PREFIXES, celsiusOffsetK: CELSIUS_OFFSET_K };
+    return {
+        units: new Map([...UNITS].map(([symbol, r]) => [symbol, [scaleToNumber(r.scale), r.dim, r.prefixable, r.cycles === true]])),
+        prefixes: new Map([...PREFIXES].map(([prefix, f]) => [prefix, scaleToNumber(f)])),
+        celsiusOffsetK: scaleToNumber(CELSIUS_OFFSET_K),
+        sourceSha256: UNIT_DATA.sha256,
+    };
 }
 //# sourceMappingURL=units.js.map