universal-physics-tensor 8.0.0 → 10.0.0

package/dist/numerical/binding-value.js

@@ -2,12 +2,17 @@
  * A binding value: a bare number, a number with a unit, or an expression of
  * registered constants and unit literals (`pi/2`, `0.6*c`, `2*1km`).
  *
- * The MathTS parser produces the node this module evaluates, so a unit
- * literal keeps its dimension. A bare `e` is the elementary charge.
- * Euler's number is `exp(x)`. A bare number, or an expression whose result is
- * dimensionless and contains no unit literal, is already in the caller's
- * unit. Anything else is an SI quantity: the caller converts it into the
- * declared unit when the dimensions agree.
+ * The MathTS parser produces the node this module reads. The number is the
+ * MathTS formula parser's, evaluated over the registered constants and the
+ * spliced unit literals; this module walks the same parse tree for the
+ * dimension and the cycle count only, so a unit literal keeps its dimension
+ * and there is one arithmetic. The scalar functions are the one table in
+ * `formula-contract.ts`, read for arity and dimension rule here and for the
+ * numeric body there. A bare `e` is the elementary charge. Euler's number is
+ * `exp(x)`. A bare number, or an expression whose result is dimensionless
+ * and contains no unit literal, is already in the caller's unit. Anything
+ * else is an SI quantity: the caller converts it into the declared unit when
+ * the dimensions agree.
  *
  * A unit literal is recognized only where it is glued to a number (`1km`,
  * `1h`, `1G`). A bare name is a constant (`h`, `G`, `c`), never that unit.
@@ -17,16 +22,40 @@
  * @module numerical/binding-value
  * @internal
  */
-import { K_B_SI, M_SUN_SI } from '../core/constants.js';
-import { FORMULA_NAMED, assertSynonymAgreement, isTemperatureName, synonymGroup, temperatureQuantityRole, } from '../dimensional/formula-names.js';
+import { K_B_SI } from '../core/constants.js';
+import { assertSynonymAgreement, isTemperatureName, synonymGroup, temperatureQuantityRole, } from '../dimensional/formula-names.js';
 import { quantityConventionUnit } from '../dimensional/unit-convention.js';
 import { naturalConstantOverrides } from '../dimensional/natural-units.js';
-import { CONSTANTS as SYMBOLIC } from '../dimensional/symbolic-constants.js';
+import { CONSTANT_REGISTRY, constantRecord } from '../dimensional/symbolic-constants.js';
 import { divide, equals, format, multiply, power } from '../dimensional/algebra.js';
-import { DIMENSIONLESS, ENERGY, MASS, TEMPERATURE } from '../dimensional/types.js';
-import { affineAbsoluteOffsetK, convertValue, mathTsAgreedQuantity, parseUnit, unitConventionNotes, UnitError, } from '../dimensional/units.js';
-import { callBuiltinFunction, EULER_NUMBER_ERROR, FormulaError } from './formula-contract.js';
-import { parseFormulaPNode } from './formula-dimension.js';
+import { DIMENSIONLESS, ENERGY, TEMPERATURE } from '../dimensional/types.js';
+import { AmbiguousUnitError, convertValue, parseUnit, readQuantityLiteral, readUnit, unitConventionNotes, UnitError, UnitRefusedError, UnknownUnitError, } from '../dimensional/units.js';
+import { arityMessage, EulerNumberError, FormulaError, SCALAR_FUNCTIONS, unknownFunctionMessage } from './formula-contract.js';
+import { constantExponent, parseFormulaPNode, UnsupportedSyntaxError } from './formula-dimension.js';
+import { mathtsFormulaParser } from './formula-mathts.js';
+/** A value on a temperature slot has a dimension that is neither a temperature nor an energy, or a temperature was read onto a dimensionless slot. @internal */
+export class TemperatureBindingError extends UnitError {
+    constructor(message) {
+        super(message);
+        this.name = 'TemperatureBindingError';
+    }
+}
+/** The text is not a number, with or without a unit, or the number is not finite. @internal */
+export class BindingNumberError extends UnitError {
+    constructor(message) {
+        super(message);
+        this.name = 'BindingNumberError';
+    }
+}
+/** An expression names something that is neither a registered constant nor a unit literal. @internal */
+class UnknownNameError extends UnitError {
+    symbol;
+    constructor(symbol) {
+        super(`unknown name '${symbol}'`);
+        this.symbol = symbol;
+        this.name = 'UnknownNameError';
+    }
+}
 /**
  * A temperature binding speaks kelvin. An energy is `k_B T` (the joules
  * divided by `kB`). Any other dimension is refused. A bare number, a
@@ -42,20 +71,21 @@ function alignTemperatureBinding(name, raw, read, kB = K_B_SI, declaredTemperatu
     }
     if (equals(read.dimension, ENERGY)) {
         if (!(kB > 0) || !Number.isFinite(kB)) {
-            throw new UnitError(`cannot read '${raw.trim()}' as a temperature: k_B is not a positive finite number`);
+            throw new TemperatureBindingError(`cannot read '${raw.trim()}' as a temperature: k_B is not a positive finite number`);
         }
         const kelvin = read.value / kB;
+        const temperatureNote = `${name}=${raw.trim()} is read as k_B T, so ${name} is ${kelvin.toExponential(6)} K`;
         return {
             value: kelvin,
             dimensioned: true,
             dimension: TEMPERATURE,
-            notes: [
-                ...read.notes,
-                `${name}=${raw.trim()} is read as k_B T, so ${name} is ${kelvin.toExponential(6)} K`,
-            ],
+            notes: [...read.notes, temperatureNote],
+            cycles: 0,
+            temperatureNote,
         };
     }
-    throw new UnitError(`'${raw.trim()}' is ${format(read.dimension)}, but ${name} is a temperature. An energy on a temperature is k_B T.`);
+    // An energy returned above, so this dimension is neither a temperature nor an energy.
+    throw new TemperatureBindingError(`'${raw.trim()}' is ${format(read.dimension)}, but ${name} is a temperature. Give kelvin, degC, or an energy (read as k_B T).`);
 }
 function sameSpelling(a, b) {
     return a === b || a.replace(/_/g, '-') === b.replace(/_/g, '-');
@@ -68,7 +98,7 @@ function sameSpelling(a, b) {
  */
 function boltzmannBindingScale(pending) {
     const group = synonymGroup('boltzmann-constant') ?? [];
-    const dim = SYMBOLIC.k_B.dim;
+    const dim = constantRecord('k_B').dim;
     const hits = pending.filter((entry) => {
         if (!group.some((member) => sameSpelling(member, entry.name)))
             return false;
@@ -87,47 +117,29 @@ function boltzmannBindingScale(pending) {
     }
     return K_B_SI;
 }
-const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
-const NUMBER_UNIT = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*(.*?)$/;
-const GLUED_NUMBER = /(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/g;
+/** A number glued to a unit; `spliceUnits` builds its own global copy. */
+const GLUED_NUMBER = /(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/;
 function finite(raw, value) {
     if (!Number.isFinite(value))
-        throw new UnitError(`'${raw}' is not a finite number`);
+        throw new BindingNumberError(`'${raw}' is not a finite number`);
     return value;
 }
 function scopeFor(mode) {
     const m = new Map();
-    const put = (name, value, dim) => {
-        m.set(name, { value, dim });
-    };
-    put('pi', Math.PI, DIMENSIONLESS);
-    put('tau', 2 * Math.PI, DIMENSIONLESS);
-    for (const [name, c] of Object.entries(SYMBOLIC))
-        put(name, c.value, c.dim);
-    for (const n of FORMULA_NAMED)
-        put(n.name, n.value, n.dim);
-    const eps = m.get('epsilon_0');
-    if (eps !== undefined)
-        put('eps0', eps.value, eps.dim);
-    const mu = m.get('mu_0');
-    if (mu !== undefined)
-        put('mu0', mu.value, mu.dim);
-    const kb = m.get('k_B');
-    if (kb !== undefined)
-        put('kB', kb.value, kb.dim);
-    put('M_sun', M_SUN_SI, MASS);
+    m.set('pi', { value: Math.PI, dim: DIMENSIONLESS, cycles: 0 });
+    m.set('tau', { value: 2 * Math.PI, dim: DIMENSIONLESS, cycles: 0 });
+    for (const record of CONSTANT_REGISTRY) {
+        for (const spelling of [record.name, ...record.spellings])
+            m.set(spelling, { value: record.value, dim: record.dim, cycles: 0 });
+    }
     if (mode !== 'si') {
         for (const [name, value] of Object.entries(naturalConstantOverrides(mode)))
-            put(name, value, DIMENSIONLESS);
+            m.set(name, { value, dim: DIMENSIONLESS, cycles: 0 });
     }
     return m;
 }
-/** A unit the parser recognized and refused, rather than a prefix that is not a unit. */
-function unitRefusal(e) {
-    if (!(e instanceof UnitError))
-        return null;
-    return /affine|more than one|ambiguous/.test(e.message) ? e : null;
-}
+/** The text has an operator, so it is an expression rather than a lone word. */
+const hasOperator = (text) => /[+\-*/^()]/.test(text);
 /** The longest unit expression at the start of `rest`, or null. */
 function longestUnit(rest) {
     if (rest.length === 0 || !/[A-Za-zµμ°ÅΩ]/.test(rest[0]))
@@ -139,19 +151,20 @@ function longestUnit(rest) {
         if (/[/*^·+\-(\s]$/.test(prefix))
             continue;
         try {
-            parseUnit(prefix);
+            readUnit(prefix);
             // `deg` is a unit, but `degF` is Fahrenheit. Do not keep a prefix whose
             // next character continues the same token.
             const next = rest[n];
-            if (next !== undefined && /[A-Za-z0-9µμ°ÅΩ]/.test(next))
+            if (next !== undefined && /[A-Za-z0-9_µμ°ÅΩ]/.test(next))
                 continue;
             best = prefix;
         }
         catch (e) {
-            const refused = unitRefusal(e);
-            if (refused !== null)
-                throw refused;
-            // A longer prefix may still be a unit (`m` then `m/s`, `M` then `Msun`).
+            // An unknown unit at this length: a longer prefix may still be one
+            // (`m` then `m/s`, `M` then `Msun`). A refused or ambiguous unit, and
+            // anything that is not a unit error, propagates.
+            if (!(e instanceof UnknownUnitError))
+                throw e;
         }
     }
     return best;
@@ -175,13 +188,12 @@ function spliceUnits(src) {
             last = end;
             continue;
         }
-        const parsed = parseUnit(unit);
+        const parsed = readUnit(unit);
         if (parsed.affine !== undefined) {
-            throw new UnitError('an affine temperature cannot be part of an expression; give it alone, or use K');
+            throw new UnitRefusedError('an affine temperature cannot be part of an expression; give it alone, or use K');
         }
-        const agreed = mathTsAgreedQuantity(1, unit, parsed);
         const name = `__u${slots.size}`;
-        slots.set(name, { value: agreed?.value ?? parsed.scale, dim: agreed?.dim ?? parsed.dim });
+        slots.set(name, { value: parsed.scale, dim: parsed.dim, cycles: parsed.cycles });
         for (const note of unitConventionNotes(unit)) {
             if (!notes.includes(note))
                 notes.push(note);
@@ -193,147 +205,141 @@ function spliceUnits(src) {
     out += src.slice(last);
     return { expr: out, slots, notes };
 }
-function evalAst(node, scope, slots) {
+/**
+ * An exponent is a dimensionless numeric constant (`2`, `-1`, `1/2`); its
+ * value raises the base's dimension. The number of the whole expression is
+ * MathTS's, so this is the one place a value is folded here, and it is the
+ * same folding the formula dimension checker uses.
+ */
+function exponentValue(node, scope, slots) {
+    const exp = dimensionWalk(node, scope, slots);
+    const value = constantExponent(node);
+    if (!equals(exp.dim, DIMENSIONLESS) || value === undefined) {
+        throw new UnitError('an exponent must be a dimensionless number');
+    }
+    return value;
+}
+/**
+ * The dimension and cycle count of a parse tree, by the dimensional rules of
+ * each node and the one function table. No number is computed here except an
+ * exponent's; unknown names, unlike sums and dimensioned transcendental
+ * arguments are refused.
+ */
+function dimensionWalk(node, scope, slots) {
     switch (node.kind) {
         case 'num':
-            return { value: node.value, dim: DIMENSIONLESS };
+            return { dim: DIMENSIONLESS, cycles: 0 };
         case 'sym': {
             if (node.name === 'euler')
-                throw new FormulaError(EULER_NUMBER_ERROR);
-            const slot = slots.get(node.name);
-            if (slot !== undefined)
-                return slot;
-            const known = scope.get(node.name);
-            if (known !== undefined)
-                return known;
-            throw new UnitError(`unknown name '${node.name}'`);
-        }
-        case 'neg': {
-            const a = evalAst(node.arg, scope, slots);
-            return { value: -a.value, dim: a.dim };
+                throw new EulerNumberError();
+            const known = slots.get(node.name) ?? scope.get(node.name);
+            if (known === undefined)
+                throw new UnknownNameError(node.name);
+            return { dim: known.dim, cycles: known.cycles };
         }
+        case 'neg':
+            return dimensionWalk(node.arg, scope, slots);
         case 'op':
-            return evalOp(node.op, node.args.map((a) => evalAst(a, scope, slots)));
+            return dimensionOfOp(node.op, node.args.map((a) => dimensionWalk(a, scope, slots)));
         case 'pow': {
-            const base = evalAst(node.base, scope, slots);
-            const exp = evalAst(node.exp, scope, slots);
-            if (!equals(exp.dim, DIMENSIONLESS))
-                throw new UnitError('an exponent must be dimensionless');
-            return { value: Math.pow(base.value, exp.value), dim: power(base.dim, exp.value) };
+            const base = dimensionWalk(node.base, scope, slots);
+            const n = exponentValue(node.exp, scope, slots);
+            return { dim: power(base.dim, n), cycles: base.cycles * n };
         }
         case 'call':
-            if (node.fn === 'euler')
-                throw new FormulaError(EULER_NUMBER_ERROR);
-            return evalCall(node.fn, node.args.map((a) => evalAst(a, scope, slots)));
+            return dimensionOfCall(node.fn, node.args, scope, slots);
     }
 }
-function evalOp(op, args) {
-    if (args.length === 0)
+function dimensionOfOp(op, args) {
+    const first = args[0];
+    if (first === undefined)
         throw new UnitError(`cannot ${op}`);
     if (op === '+' || op === '-') {
-        const first = args[0];
-        if (args.length === 1) {
-            return op === '-' ? { value: -first.value, dim: first.dim } : first;
-        }
-        let value = first.value;
+        let cycles = first.cycles;
         for (const next of args.slice(1)) {
             if (!equals(first.dim, next.dim)) {
                 throw new UnitError(`cannot ${op === '+' ? 'add' : 'subtract'} ${format(first.dim)} and ${format(next.dim)}`);
             }
-            value = op === '+' ? value + next.value : value - next.value;
-        }
-        return { value, dim: first.dim };
-    }
-    if (op === '*') {
-        let value = 1;
-        let dim = DIMENSIONLESS;
-        for (const a of args) {
-            value *= a.value;
-            dim = multiply(dim, a.dim);
+            // A sum of a cycle rate and a plain rate has no single cycle count.
+            if (next.cycles !== cycles)
+                cycles = Number.NaN;
         }
-        return { value, dim };
+        return { dim: first.dim, cycles };
     }
-    let value = args[0].value;
-    let dim = args[0].dim;
-    for (const next of args.slice(1)) {
-        value /= next.value;
-        dim = divide(dim, next.dim);
+    let dim = op === '*' ? DIMENSIONLESS : first.dim;
+    let cycles = op === '*' ? 0 : first.cycles;
+    for (const a of op === '*' ? args : args.slice(1)) {
+        dim = op === '*' ? multiply(dim, a.dim) : divide(dim, a.dim);
+        cycles = op === '*' ? cycles + a.cycles : cycles - a.cycles;
     }
-    return { value, dim };
+    return { dim, cycles };
 }
-function evalCall(fn, args) {
-    if (fn === 'sqrt' || fn === 'cbrt') {
-        if (args.length !== 1)
-            throw new UnitError(`${fn} expected 1 argument`);
-        const n = fn === 'sqrt' ? 0.5 : 1 / 3;
-        const value = fn === 'sqrt' ? Math.sqrt(args[0].value) : Math.cbrt(args[0].value);
-        return { value, dim: power(args[0].dim, n) };
-    }
-    if (fn === 'abs') {
-        if (args.length !== 1)
-            throw new UnitError('abs expected 1 argument');
-        return { value: Math.abs(args[0].value), dim: args[0].dim };
-    }
-    if (fn === 'pow') {
-        if (args.length !== 2)
-            throw new UnitError('pow expects 2 arguments');
-        if (!equals(args[1].dim, DIMENSIONLESS))
-            throw new UnitError('an exponent must be dimensionless');
-        return { value: Math.pow(args[0].value, args[1].value), dim: power(args[0].dim, args[1].value) };
-    }
-    if (fn === 'atan2') {
-        if (args.length !== 2)
-            throw new UnitError('atan2 expects 2 arguments');
-        if (!equals(args[0].dim, args[1].dim))
-            throw new UnitError('atan2 arguments must have the same dimension');
-        return { value: Math.atan2(args[0].value, args[1].value), dim: DIMENSIONLESS };
-    }
-    for (const a of args) {
-        if (!equals(a.dim, DIMENSIONLESS))
-            throw new UnitError(`${fn} expects a dimensionless argument`);
+/** A call, by the one table's arity and dimension rule. */
+function dimensionOfCall(fn, args, scope, slots) {
+    if (fn === 'euler')
+        throw new EulerNumberError();
+    const spec = SCALAR_FUNCTIONS[fn];
+    if (spec === undefined)
+        throw new UnitError(unknownFunctionMessage(fn));
+    if (args.length !== spec.arity)
+        throw new UnitError(arityMessage(fn, spec.arity));
+    const rule = spec.dimension;
+    const first = dimensionWalk(args[0], scope, slots);
+    switch (rule.kind) {
+        case 'root':
+            return { dim: power(first.dim, rule.power), cycles: first.cycles * rule.power };
+        case 'same':
+            return first;
+        case 'transcendental':
+            if (!equals(first.dim, DIMENSIONLESS))
+                throw new UnitError(`${fn} expects a dimensionless argument`);
+            return { dim: DIMENSIONLESS, cycles: 0 };
+        case 'power': {
+            const n = exponentValue(args[1], scope, slots);
+            return { dim: power(first.dim, n), cycles: first.cycles * n };
+        }
+        case 'ratio': {
+            const second = dimensionWalk(args[1], scope, slots);
+            if (!equals(first.dim, second.dim))
+                throw new UnitError(`${fn} arguments must have the same dimension`);
+            return { dim: DIMENSIONLESS, cycles: 0 };
+        }
     }
+}
+/**
+ * The number of a spliced expression: the MathTS formula parser over the
+ * registered constants and the unit slots. The dimension walk has already
+ * refused unknown names, so a failure here is a non-finite result.
+ */
+function numberOf(raw, expr, scope, slots) {
+    const values = {};
+    for (const [name, qty] of scope)
+        values[name] = qty.value;
+    for (const [name, qty] of slots)
+        values[name] = qty.value;
     try {
-        return { value: callBuiltinFunction(fn, args.map((a) => a.value)), dim: DIMENSIONLESS };
+        return mathtsFormulaParser.parse(expr).evaluate(values);
     }
     catch (e) {
         if (e instanceof FormulaError)
-            throw new UnitError(e.message);
+            throw new BindingNumberError(`'${raw}' is not a finite number`);
         throw e;
     }
 }
-function plainUnit(raw, reading) {
-    const m = NUMBER_UNIT.exec(raw);
-    // A leading `*` is multiplication (`2*h`, `0.6*c`). `parseUnit` would drop
-    // it and read the name as a unit (`h` the hour). A leading `/` is a unit
-    // (`1/s`) when the remainder parses, and an expression otherwise.
-    if (m === null || m[2] === undefined || m[2] === '' || m[2].startsWith('*') || m[2].startsWith('·'))
-        return null;
-    let unit;
-    try {
-        unit = parseUnit(m[2]);
-    }
-    catch (e) {
-        const refused = unitRefusal(e);
-        if (refused !== null)
-            throw refused;
+/** The literal path: a number with an optional unit, read exactly by the one unit reader. */
+function literalBinding(raw, reading) {
+    const literal = readQuantityLiteral(raw, reading);
+    if (literal === null)
         return null;
-    }
-    const v = finite(raw, Number(m[1]));
-    const offset = unit.affine !== undefined && reading === 'absolute' ? affineAbsoluteOffsetK(unit.affine) : 0;
-    const agreed = offset === 0 ? mathTsAgreedQuantity(v, m[2], unit) : undefined;
     return {
-        value: agreed?.value ?? v * unit.scale + offset,
-        dimensioned: true,
-        dimension: agreed?.dim ?? unit.dim,
-        notes: unitConventionNotes(m[2]),
+        value: finite(raw, literal.value),
+        dimensioned: literal.unit !== '',
+        dimension: literal.dim,
+        notes: unitConventionNotes(literal.unit),
+        cycles: literal.cycles,
+        ...(literal.affine === undefined ? {} : { affine: literal.affine }),
     };
 }
-function looksLikeNumberUnit(raw) {
-    const matched = NUMBER_UNIT.exec(raw.trim());
-    if (matched === null || matched[2] === undefined || matched[2] === '')
-        return false;
-    return !matched[2].startsWith('*') && !matched[2].startsWith('·');
-}
 /**
  * A number-plus-unit whose dimension matches `target`, including an ambiguous
  * token that has one reading of that dimension. A unique dimension mismatch
@@ -341,22 +347,25 @@ function looksLikeNumberUnit(raw) {
  * An ambiguous expression that matches nothing throws.
  */
 function declaredUnitReading(raw, target, reading) {
-    if (!looksLikeNumberUnit(raw))
-        return undefined;
     try {
         const converted = convertValue(raw, target, reading);
         if (converted.given === '')
             return undefined;
-        const to = parseUnit(target);
         return {
             value: converted.value,
             dimensioned: true,
-            dimension: to.dim,
+            dimension: parseUnit(target).dim,
             notes: unitConventionNotes(converted.given),
+            cycles: converted.cycles ?? 0,
+            ...(converted.affine === undefined ? {} : { affine: converted.affine }),
         };
     }
     catch (error) {
-        if (error instanceof UnitError && /ambiguous/.test(error.message))
+        if (error instanceof AmbiguousUnitError)
+            throw error;
+        // A unit the reader could not match to the target is the "not this
+        // reading" outcome; anything that is not a unit error propagates.
+        if (!(error instanceof UnitError))
             throw error;
         return undefined;
     }
@@ -388,8 +397,11 @@ export function readNamedBinding(name, raw, opts) {
         try {
             pending.push({ name: sibling.name, read: readBinding(sibling.raw, { mode, reading }) });
         }
-        catch {
-            // A sibling that does not parse is that sibling's own error.
+        catch (error) {
+            // A sibling that does not read as a value is that sibling's own error,
+            // reported where it is read. A programming error propagates.
+            if (!(error instanceof UnitError))
+                throw error;
         }
     }
     const declaredDim = declared !== undefined && declared !== '' ? parseUnit(declared).dim : undefined;
@@ -400,7 +412,7 @@ export function readNamedBinding(name, raw, opts) {
     const energyBecameTemperature = aligned.dimensioned && equals(aligned.dimension, TEMPERATURE) && !equals(read.dimension, TEMPERATURE);
     if (energyBecameTemperature) {
         if (target === '') {
-            throw new UnitError(`'${raw.trim()}' is a temperature, but this input is dimensionless`);
+            throw new TemperatureBindingError(`'${raw.trim()}' is a temperature, but this input is dimensionless`);
         }
         const to = parseUnit(target);
         if (to.affine !== undefined)
@@ -408,12 +420,7 @@ export function readNamedBinding(name, raw, opts) {
         if (!equals(aligned.dimension, to.dim)) {
             throw new UnitError(`'${raw.trim()}' is ${format(aligned.dimension)}, but this input is ${format(to.dim)} (${target})`);
         }
-        return {
-            value: aligned.value / to.scale,
-            dimensioned: true,
-            dimension: to.dim,
-            notes: aligned.notes,
-        };
+        return { ...aligned, value: aligned.value / to.scale, dimensioned: true, dimension: to.dim };
     }
     const converted = bindingInUnit(raw, target, reading, mode);
     return {
@@ -421,6 +428,8 @@ export function readNamedBinding(name, raw, opts) {
         dimensioned: converted.given !== '',
         dimension: target === '' ? DIMENSIONLESS : parseUnit(target).dim,
         notes: unitConventionNotes(converted.given),
+        cycles: converted.cycles ?? 0,
+        ...(converted.affine === undefined ? {} : { affine: converted.affine }),
     };
 }
 /**
@@ -433,48 +442,47 @@ export function readBinding(raw, opts) {
     const mode = opts?.mode ?? 'si';
     const reading = opts?.reading ?? 'absolute';
     if (trimmed === '')
-        throw new UnitError(`'${raw}' is not a finite number`);
-    if (NUMBER.test(trimmed)) {
-        return { value: finite(trimmed, Number(trimmed)), dimensioned: false, dimension: DIMENSIONLESS, notes: [] };
-    }
-    const plain = plainUnit(trimmed, reading);
-    if (plain !== null)
-        return plain;
+        throw new BindingNumberError(`'${raw}' is not a finite number`);
+    const literal = literalBinding(trimmed, reading);
+    if (literal !== null)
+        return literal;
     const spliced = spliceUnits(trimmed);
+    const notANumber = () => new BindingNumberError(`'${trimmed}' is not a number with an optional unit`);
     let ast;
     try {
         ast = parseFormulaPNode(spliced.expr);
     }
     catch (e) {
+        // Syntax the normalized form has no shape for (`1.2.3`, `a.b`) is not a value.
+        if (e instanceof UnsupportedSyntaxError)
+            throw notANumber();
+        // `euler` names the refused constant; keep that sentence.
+        if (e instanceof EulerNumberError)
+            throw new UnitError(e.message);
         if (e instanceof FormulaError) {
-            // `euler` names the refused constant. Keep that sentence; a bare unknown
-            // word is not an expression, and a token with an operator (`2*`) is.
-            if (e.message.includes('exp(x)'))
-                throw new UnitError(e.message);
-            if (!/[+\-*/^()]/.test(trimmed))
-                throw new UnitError(`'${trimmed}' is not a number with an optional unit`);
+            // A bare unknown word is not an expression; a token with an operator (`2*`) is.
+            if (!hasOperator(trimmed))
+                throw notANumber();
             throw new UnitError(e.message);
         }
         throw e;
     }
-    let qty;
+    const scope = scopeFor(mode);
+    let shape;
     try {
-        qty = evalAst(ast, scopeFor(mode), spliced.slots);
+        shape = dimensionWalk(ast, scope, spliced.slots);
     }
     catch (e) {
-        if (e instanceof UnitError &&
-            /unknown name '/.test(e.message) &&
-            spliced.slots.size === 0 &&
-            !/[+\-*/^()]/.test(trimmed)) {
-            throw new UnitError(`'${trimmed}' is not a number with an optional unit`);
-        }
+        if (e instanceof UnknownNameError && spliced.slots.size === 0 && !hasOperator(trimmed))
+            throw notANumber();
         throw e;
     }
     return {
-        value: finite(trimmed, qty.value),
-        dimensioned: spliced.slots.size > 0 || !equals(qty.dim, DIMENSIONLESS),
-        dimension: qty.dim,
+        value: finite(trimmed, numberOf(trimmed, spliced.expr, scope, spliced.slots)),
+        dimensioned: spliced.slots.size > 0 || !equals(shape.dim, DIMENSIONLESS),
+        dimension: shape.dim,
         notes: spliced.notes,
+        cycles: shape.cycles,
     };
 }
 /**
@@ -483,9 +491,10 @@ export function readBinding(raw, opts) {
  * @internal
  */
 export function bindingInUnit(raw, target, reading = 'absolute', mode = 'si') {
-    if (NUMBER.test(raw.trim()) || looksLikeNumberUnit(raw)) {
+    // A literal the one unit reader accepts converts exactly, unit to unit; anything else
+    // (an expression such as `1Hz + 1/(1s)`) is read as an expression and converted from SI.
+    if (readQuantityLiteral(raw, reading) !== null)
         return convertValue(raw, target, reading);
-    }
     const b = readBinding(raw, { reading, mode });
     if (!b.dimensioned)
         return { value: b.value, given: '' };
@@ -495,7 +504,7 @@ export function bindingInUnit(raw, target, reading = 'absolute', mode = 'si') {
     if (!equals(b.dimension, to.dim)) {
         throw new UnitError(`'${raw.trim()}' is ${format(b.dimension)}, but this input is ${format(to.dim)} (${target || 'dimensionless'})`);
     }
-    return { value: b.value / to.scale, given: raw.trim() };
+    return { value: b.value / to.scale, given: raw.trim(), ...(b.cycles === 0 ? {} : { cycles: b.cycles }) };
 }
 /**
  * A parameter whose unit is the SI base of `expected`. A bare number is