@woosh/meep-engine 3.1.0 → 3.2.0

package/src/core/science/units/unit_matrix_to_string.js

@@ -1,403 +1,403 @@
-import { UnitDimension, UNIT_DIMENSION_COUNT } from "./UnitDimension.js";
-import { UNIT_DIMENSION_MAPPING } from "./UNIT_DIMENSION_MAPPING.js";
-
-/**
- * Order in which dimensions are visited when assembling a base-unit string. Chosen to match the
- * conventional way SI compound units are written (mass appears before length in "kg·m/s^2",
- * "kg·m^2/s^2", etc.).
- *
- * @type {number[]}
- */
-const RENDER_ORDER = [
-    UnitDimension.Mass,
-    UnitDimension.Length,
-    UnitDimension.Time,
-    UnitDimension.ElectricCurrent,
-    UnitDimension.Temperature,
-    UnitDimension.AmountOfSubstance,
-    UnitDimension.LuminousIntensity
-];
-
-/**
- * Format an exponent as either an empty suffix (for ^1) or a `^n` suffix.
- * @param {number} exponent
- * @returns {string}
- */
-function format_exponent_suffix(exponent) {
-    if (exponent === 1) {
-        return '';
-    }
-
-    return `^${exponent}`;
-}
-
-/**
- * Append a `symbol[^k]` term to either the numerator or denominator buffer.
- *
- * @param {string} numerator
- * @param {string} denominator
- * @param {string} symbol
- * @param {number} power Non-zero power.
- * @returns {[string, string]} New (numerator, denominator) pair.
- */
-function append_term(numerator, denominator, symbol, power) {
-    if (power > 0) {
-        const term = symbol + format_exponent_suffix(power);
-        return [numerator === '' ? term : numerator + '·' + term, denominator];
-    }
-
-    const term = symbol + format_exponent_suffix(-power);
-    return [numerator, denominator === '' ? term : denominator + '·' + term];
-}
-
-/**
- * Count how many components of an exponent vector are non-zero — used as the "term cardinality"
- * objective during decomposition.
- *
- * @param {Float64Array} exponents
- * @returns {number}
- */
-function count_nonzero(exponents) {
-    let count = 0;
-
-    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
-        if (exponents[i] !== 0) {
-            count++;
-        }
-    }
-
-    return count;
-}
-
-/**
- * Count how many components of `(remaining - k * unit)` are non-zero. Hot path during
- * decomposition; written without allocating a temporary vector.
- *
- * @param {Float64Array} remaining
- * @param {Float64Array} unit
- * @param {number} k
- * @returns {number}
- */
-function count_nonzero_after_subtract(remaining, unit, k) {
-    let count = 0;
-
-    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
-        if (remaining[i] - k * unit[i] !== 0) {
-            count++;
-        }
-    }
-
-    return count;
-}
-
-/**
- * Subtract `k * unit` from `remaining` in place.
- *
- * @param {Float64Array} remaining
- * @param {Float64Array} unit
- * @param {number} k
- */
-function subtract_scaled(remaining, unit, k) {
-    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
-        remaining[i] -= k * unit[i];
-    }
-}
-
-/**
- * Maximum |k| considered when looking for the integer power of a named unit that best reduces
- * the remaining matrix. Chosen large enough to handle squares / cubes of common units while
- * keeping the inner loop bounded.
- *
- * @type {number}
- */
-const MAX_POWER_SEARCH = 4;
-
-/**
- * Whether the given exponent vector has 2 or more non-zero components — i.e. whether the
- * named unit it belongs to expresses a genuine compound dimension (Newton, Volt, ...) rather
- * than just a renaming of a single base dimension.
- *
- * @param {Float64Array} exponents
- * @returns {boolean}
- */
-function is_compound(exponents) {
-    let count = 0;
-
-    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
-        if (exponents[i] !== 0) {
-            count++;
-
-            if (count >= 2) {
-                return true;
-            }
-        }
-    }
-
-    return false;
-}
-
-/**
- * Compute `k` such that every component of `matrix` equals `k * named_unit`. Returns `null`
- * when no such scalar exists, or when `named_unit` is itself dimensionless.
- *
- * @param {Float64Array} matrix
- * @param {Float64Array} named_unit
- * @returns {number|null}
- */
-function compute_scalar_power(matrix, named_unit) {
-    let k = null;
-
-    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
-        const ni = named_unit[i];
-        const mi = matrix[i];
-
-        if (ni === 0) {
-            if (mi !== 0) {
-                return null;
-            }
-            continue;
-        }
-
-        const candidate = mi / ni;
-
-        if (k === null) {
-            k = candidate;
-        } else if (k !== candidate) {
-            return null;
-        }
-    }
-
-    return k;
-}
-
-/**
- * Look for a registry entry that is a non-zero **integer** scalar multiple of `matrix` — i.e.
- * an exact match (including positive/negative integer powers like `V`, `V^2`, `1/V`). Fractional
- * scalars are rejected; that prevents nonsensical renders like `Gy^0.5` for a speed matrix.
- *
- * Returns the registry index and matching power, or `index === -1` when no integer scalar
- * match exists.
- *
- * @param {Float64Array} matrix
- * @param {NamedUnit[]} named_units
- * @returns {{ index: number, power: number }}
- */
-function find_scalar_match(matrix, named_units) {
-    for (let i = 0; i < named_units.length; i++) {
-        const power = compute_scalar_power(matrix, named_units[i].unit.exponents);
-
-        if (power !== null && power !== 0 && Number.isInteger(power)) {
-            return { index: i, power };
-        }
-    }
-
-    return { index: -1, power: 0 };
-}
-
-/**
- * Pick the (named-unit-index, power) pair that minimises the non-zero count of
- * `remaining - power * named_unit.unit`, considering only **compound** registry entries
- * (those with at least two non-zero exponents).
- *
- * Single-dimension entries (e.g. METER, SECOND) are skipped: they would just substitute their
- * symbol for the corresponding base symbol while reordering terms by registry order rather
- * than the canonical RENDER_ORDER. The base-residual pass handles those cleanly.
- *
- * Ties are broken by registry order (first match wins).
- *
- * @param {Float64Array} remaining
- * @param {NamedUnit[]} named_units
- * @param {number} baseline Current non-zero count of `remaining`.
- * @returns {{ index: number, power: number, nonzero: number }}
- */
-function find_best_compound_unit(remaining, named_units, baseline) {
-    let best_index = -1;
-    let best_power = 0;
-    let best_nonzero = baseline;
-
-    for (let i = 0; i < named_units.length; i++) {
-        const unit_exp = named_units[i].unit.exponents;
-
-        if (!is_compound(unit_exp)) {
-            continue;
-        }
-
-        for (let k = -MAX_POWER_SEARCH; k <= MAX_POWER_SEARCH; k++) {
-            if (k === 0) {
-                continue;
-            }
-
-            const after = count_nonzero_after_subtract(remaining, unit_exp, k);
-
-            if (after < best_nonzero) {
-                best_nonzero = after;
-                best_index = i;
-                best_power = k;
-            }
-        }
-    }
-
-    return { index: best_index, power: best_power, nonzero: best_nonzero };
-}
-
-/**
- * Greedily decompose `unit_matrix` against the **compound** entries of the registry, appending
- * recognised named-unit terms into the numerator/denominator buffers. The leftover residual
- * exponents are returned for later rendering as base-dimension terms.
- *
- * Each iteration picks the (named unit, integer power) pair that strictly reduces the term
- * count: `total terms = #picked + nonzero(residual)`. The algorithm stops once no further
- * pick yields a strict improvement.
- *
- * Note: this function does NOT handle the exact-match case (`matrix == k * named_unit`) — that
- * is detected separately upstream and short-circuits to a single-term render so callers can
- * benefit from named single-dim units like Hz.
- *
- * @param {UnitMatrix} unit_matrix
- * @param {NamedUnit[]} named_units
- * @returns {{ numerator: string, denominator: string, residual: Float64Array }}
- */
-function decompose_compound(unit_matrix, named_units) {
-    const residual = new Float64Array(UNIT_DIMENSION_COUNT);
-    residual.set(unit_matrix.exponents);
-
-    let numerator = '';
-    let denominator = '';
-
-    while (true) {
-        const baseline = count_nonzero(residual);
-
-        if (baseline === 0) {
-            break;
-        }
-
-        const best = find_best_compound_unit(residual, named_units, baseline);
-
-        // Strict improvement: total terms decrease only when the new non-zero count is at
-        // least 2 below the baseline (a 1-step reduction is offset by adding a named term,
-        // for net zero change). This avoids cosmetic substitutions like `m/s -> Hz·m`.
-        if (best.index === -1 || best.nonzero > baseline - 2) {
-            break;
-        }
-
-        const named = named_units[best.index];
-        subtract_scaled(residual, named.unit.exponents, best.power);
-
-        const result = append_term(numerator, denominator, named.symbol, best.power);
-        numerator = result[0];
-        denominator = result[1];
-    }
-
-    return { numerator, denominator, residual };
-}
-
-/**
- * Append every non-zero residual base-dimension exponent to the numerator/denominator buffers,
- * using `dimension_units[i].symbol` for each dimension `i`.
- *
- * @param {string} numerator
- * @param {string} denominator
- * @param {Float64Array} residual
- * @param {NamedUnit[]} dimension_units One entry per base dimension, in {@link UnitDimension} order.
- * @returns {[string, string]}
- */
-function append_base_residual(numerator, denominator, residual, dimension_units) {
-    let n = numerator;
-    let d = denominator;
-
-    for (let i = 0; i < RENDER_ORDER.length; i++) {
-        const dim = RENDER_ORDER[i];
-        const e = residual[dim];
-
-        if (e === 0) {
-            continue;
-        }
-
-        const result = append_term(n, d, dimension_units[dim].symbol, e);
-        n = result[0];
-        d = result[1];
-    }
-
-    return [n, d];
-}
-
-/**
- * Convert a {@link UnitMatrix} into a human-readable string such as `m/s`, `kg·m/s^2` or `Hz`.
- *
- * Output rules:
- *  - dimensions with positive exponent appear in the numerator, joined by `·`
- *  - dimensions with negative exponent appear in the denominator, joined by `·`
- *  - exponents of magnitude 1 are written without a suffix; otherwise `^n` is appended
- *  - dimensionless matrices return an empty string
- *  - if every term lives in the denominator, the numerator is rendered as `1`
- *
- * Optional named-unit registry (`named_units` argument):
- *  - if the matrix is a non-zero scalar multiple of any registry entry, that entry is used
- *    directly: `Hz` for `1/s`, `V` for the volt matrix, `V^2` for its square, `1/V` for its
- *    inverse.
- *  - otherwise the matrix is greedily decomposed against compound registry entries (named
- *    units with at least two non-zero exponents). The algorithm tries to use the fewest terms
- *    possible — `V/m^2` is rendered as `V/m^2` (two terms) rather than `kg/(s^3·A)` (four
- *    terms). Single-dimension entries (`METER`, `SECOND`, ...) are skipped here so the
- *    leftover base residual renders in canonical `Mass·Length·Time·...` order.
- *  - registry order acts as a tiebreaker — the first match wins among options with the same
- *    term-count reduction.
- *
- * @param {UnitMatrix} unit_matrix
- * @param {NamedUnit[]} [named_units] Optional registry of compound-unit symbols.
- * @param {NamedUnit[]} [dimension_units=UNIT_DIMENSION_MAPPING] One {@link NamedUnit} per base dimension, indexed by {@link UnitDimension}. Only the `.symbol` field is read.
- * @returns {string}
- */
-export function unit_matrix_to_string(
-    unit_matrix,
-    named_units = undefined,
-    dimension_units = UNIT_DIMENSION_MAPPING
-) {
-    if (unit_matrix.is_dimensionless()) {
-        return '';
-    }
-
-    let numerator = '';
-    let denominator = '';
-    let residual;
-
-    if (named_units !== undefined && named_units.length > 0) {
-        // Phase 1: exact scalar match short-circuits to a single named term.
-        const scalar = find_scalar_match(unit_matrix.exponents, named_units);
-
-        if (scalar.index !== -1) {
-            const named = named_units[scalar.index];
-            const result = append_term('', '', named.symbol, scalar.power);
-
-            if (result[1] === '') {
-                return result[0];
-            }
-
-            return '1/' + result[1];
-        }
-
-        // Phase 2: greedy decomposition against compound entries; leftover residual renders
-        // via the base-residual pass below.
-        const decomposed = decompose_compound(unit_matrix, named_units);
-
-        numerator = decomposed.numerator;
-        denominator = decomposed.denominator;
-        residual = decomposed.residual;
-    } else {
-        residual = unit_matrix.exponents;
-    }
-
-    const result = append_base_residual(numerator, denominator, residual, dimension_units);
-    numerator = result[0];
-    denominator = result[1];
-
-    if (denominator === '') {
-        return numerator;
-    }
-
-    if (numerator === '') {
-        return '1/' + denominator;
-    }
-
-    return numerator + '/' + denominator;
-}
+import { UnitDimension, UNIT_DIMENSION_COUNT } from "./UnitDimension.js";
+import { UNIT_DIMENSION_MAPPING } from "./UNIT_DIMENSION_MAPPING.js";
+
+/**
+ * Order in which dimensions are visited when assembling a base-unit string. Chosen to match the
+ * conventional way SI compound units are written (mass appears before length in "kg·m/s^2",
+ * "kg·m^2/s^2", etc.).
+ *
+ * @type {number[]}
+ */
+const RENDER_ORDER = [
+    UnitDimension.Mass,
+    UnitDimension.Length,
+    UnitDimension.Time,
+    UnitDimension.ElectricCurrent,
+    UnitDimension.Temperature,
+    UnitDimension.AmountOfSubstance,
+    UnitDimension.LuminousIntensity
+];
+
+/**
+ * Format an exponent as either an empty suffix (for ^1) or a `^n` suffix.
+ * @param {number} exponent
+ * @returns {string}
+ */
+function format_exponent_suffix(exponent) {
+    if (exponent === 1) {
+        return '';
+    }
+
+    return `^${exponent}`;
+}
+
+/**
+ * Append a `symbol[^k]` term to either the numerator or denominator buffer.
+ *
+ * @param {string} numerator
+ * @param {string} denominator
+ * @param {string} symbol
+ * @param {number} power Non-zero power.
+ * @returns {[string, string]} New (numerator, denominator) pair.
+ */
+function append_term(numerator, denominator, symbol, power) {
+    if (power > 0) {
+        const term = symbol + format_exponent_suffix(power);
+        return [numerator === '' ? term : numerator + '·' + term, denominator];
+    }
+
+    const term = symbol + format_exponent_suffix(-power);
+    return [numerator, denominator === '' ? term : denominator + '·' + term];
+}
+
+/**
+ * Count how many components of an exponent vector are non-zero — used as the "term cardinality"
+ * objective during decomposition.
+ *
+ * @param {Float64Array} exponents
+ * @returns {number}
+ */
+function count_nonzero(exponents) {
+    let count = 0;
+
+    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
+        if (exponents[i] !== 0) {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Count how many components of `(remaining - k * unit)` are non-zero. Hot path during
+ * decomposition; written without allocating a temporary vector.
+ *
+ * @param {Float64Array} remaining
+ * @param {Float64Array} unit
+ * @param {number} k
+ * @returns {number}
+ */
+function count_nonzero_after_subtract(remaining, unit, k) {
+    let count = 0;
+
+    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
+        if (remaining[i] - k * unit[i] !== 0) {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Subtract `k * unit` from `remaining` in place.
+ *
+ * @param {Float64Array} remaining
+ * @param {Float64Array} unit
+ * @param {number} k
+ */
+function subtract_scaled(remaining, unit, k) {
+    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
+        remaining[i] -= k * unit[i];
+    }
+}
+
+/**
+ * Maximum |k| considered when looking for the integer power of a named unit that best reduces
+ * the remaining matrix. Chosen large enough to handle squares / cubes of common units while
+ * keeping the inner loop bounded.
+ *
+ * @type {number}
+ */
+const MAX_POWER_SEARCH = 4;
+
+/**
+ * Whether the given exponent vector has 2 or more non-zero components — i.e. whether the
+ * named unit it belongs to expresses a genuine compound dimension (Newton, Volt, ...) rather
+ * than just a renaming of a single base dimension.
+ *
+ * @param {Float64Array} exponents
+ * @returns {boolean}
+ */
+function is_compound(exponents) {
+    let count = 0;
+
+    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
+        if (exponents[i] !== 0) {
+            count++;
+
+            if (count >= 2) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Compute `k` such that every component of `matrix` equals `k * named_unit`. Returns `null`
+ * when no such scalar exists, or when `named_unit` is itself dimensionless.
+ *
+ * @param {Float64Array} matrix
+ * @param {Float64Array} named_unit
+ * @returns {number|null}
+ */
+function compute_scalar_power(matrix, named_unit) {
+    let k = null;
+
+    for (let i = 0; i < UNIT_DIMENSION_COUNT; i++) {
+        const ni = named_unit[i];
+        const mi = matrix[i];
+
+        if (ni === 0) {
+            if (mi !== 0) {
+                return null;
+            }
+            continue;
+        }
+
+        const candidate = mi / ni;
+
+        if (k === null) {
+            k = candidate;
+        } else if (k !== candidate) {
+            return null;
+        }
+    }
+
+    return k;
+}
+
+/**
+ * Look for a registry entry that is a non-zero **integer** scalar multiple of `matrix` — i.e.
+ * an exact match (including positive/negative integer powers like `V`, `V^2`, `1/V`). Fractional
+ * scalars are rejected; that prevents nonsensical renders like `Gy^0.5` for a speed matrix.
+ *
+ * Returns the registry index and matching power, or `index === -1` when no integer scalar
+ * match exists.
+ *
+ * @param {Float64Array} matrix
+ * @param {NamedUnit[]} named_units
+ * @returns {{ index: number, power: number }}
+ */
+function find_scalar_match(matrix, named_units) {
+    for (let i = 0; i < named_units.length; i++) {
+        const power = compute_scalar_power(matrix, named_units[i].unit.exponents);
+
+        if (power !== null && power !== 0 && Number.isInteger(power)) {
+            return { index: i, power };
+        }
+    }
+
+    return { index: -1, power: 0 };
+}
+
+/**
+ * Pick the (named-unit-index, power) pair that minimises the non-zero count of
+ * `remaining - power * named_unit.unit`, considering only **compound** registry entries
+ * (those with at least two non-zero exponents).
+ *
+ * Single-dimension entries (e.g. METER, SECOND) are skipped: they would just substitute their
+ * symbol for the corresponding base symbol while reordering terms by registry order rather
+ * than the canonical RENDER_ORDER. The base-residual pass handles those cleanly.
+ *
+ * Ties are broken by registry order (first match wins).
+ *
+ * @param {Float64Array} remaining
+ * @param {NamedUnit[]} named_units
+ * @param {number} baseline Current non-zero count of `remaining`.
+ * @returns {{ index: number, power: number, nonzero: number }}
+ */
+function find_best_compound_unit(remaining, named_units, baseline) {
+    let best_index = -1;
+    let best_power = 0;
+    let best_nonzero = baseline;
+
+    for (let i = 0; i < named_units.length; i++) {
+        const unit_exp = named_units[i].unit.exponents;
+
+        if (!is_compound(unit_exp)) {
+            continue;
+        }
+
+        for (let k = -MAX_POWER_SEARCH; k <= MAX_POWER_SEARCH; k++) {
+            if (k === 0) {
+                continue;
+            }
+
+            const after = count_nonzero_after_subtract(remaining, unit_exp, k);
+
+            if (after < best_nonzero) {
+                best_nonzero = after;
+                best_index = i;
+                best_power = k;
+            }
+        }
+    }
+
+    return { index: best_index, power: best_power, nonzero: best_nonzero };
+}
+
+/**
+ * Greedily decompose `unit_matrix` against the **compound** entries of the registry, appending
+ * recognised named-unit terms into the numerator/denominator buffers. The leftover residual
+ * exponents are returned for later rendering as base-dimension terms.
+ *
+ * Each iteration picks the (named unit, integer power) pair that strictly reduces the term
+ * count: `total terms = #picked + nonzero(residual)`. The algorithm stops once no further
+ * pick yields a strict improvement.
+ *
+ * Note: this function does NOT handle the exact-match case (`matrix == k * named_unit`) — that
+ * is detected separately upstream and short-circuits to a single-term render so callers can
+ * benefit from named single-dim units like Hz.
+ *
+ * @param {UnitMatrix} unit_matrix
+ * @param {NamedUnit[]} named_units
+ * @returns {{ numerator: string, denominator: string, residual: Float64Array }}
+ */
+function decompose_compound(unit_matrix, named_units) {
+    const residual = new Float64Array(UNIT_DIMENSION_COUNT);
+    residual.set(unit_matrix.exponents);
+
+    let numerator = '';
+    let denominator = '';
+
+    while (true) {
+        const baseline = count_nonzero(residual);
+
+        if (baseline === 0) {
+            break;
+        }
+
+        const best = find_best_compound_unit(residual, named_units, baseline);
+
+        // Strict improvement: total terms decrease only when the new non-zero count is at
+        // least 2 below the baseline (a 1-step reduction is offset by adding a named term,
+        // for net zero change). This avoids cosmetic substitutions like `m/s -> Hz·m`.
+        if (best.index === -1 || best.nonzero > baseline - 2) {
+            break;
+        }
+
+        const named = named_units[best.index];
+        subtract_scaled(residual, named.unit.exponents, best.power);
+
+        const result = append_term(numerator, denominator, named.symbol, best.power);
+        numerator = result[0];
+        denominator = result[1];
+    }
+
+    return { numerator, denominator, residual };
+}
+
+/**
+ * Append every non-zero residual base-dimension exponent to the numerator/denominator buffers,
+ * using `dimension_units[i].symbol` for each dimension `i`.
+ *
+ * @param {string} numerator
+ * @param {string} denominator
+ * @param {Float64Array} residual
+ * @param {NamedUnit[]} dimension_units One entry per base dimension, in {@link UnitDimension} order.
+ * @returns {[string, string]}
+ */
+function append_base_residual(numerator, denominator, residual, dimension_units) {
+    let n = numerator;
+    let d = denominator;
+
+    for (let i = 0; i < RENDER_ORDER.length; i++) {
+        const dim = RENDER_ORDER[i];
+        const e = residual[dim];
+
+        if (e === 0) {
+            continue;
+        }
+
+        const result = append_term(n, d, dimension_units[dim].symbol, e);
+        n = result[0];
+        d = result[1];
+    }
+
+    return [n, d];
+}
+
+/**
+ * Convert a {@link UnitMatrix} into a human-readable string such as `m/s`, `kg·m/s^2` or `Hz`.
+ *
+ * Output rules:
+ *  - dimensions with positive exponent appear in the numerator, joined by `·`
+ *  - dimensions with negative exponent appear in the denominator, joined by `·`
+ *  - exponents of magnitude 1 are written without a suffix; otherwise `^n` is appended
+ *  - dimensionless matrices return an empty string
+ *  - if every term lives in the denominator, the numerator is rendered as `1`
+ *
+ * Optional named-unit registry (`named_units` argument):
+ *  - if the matrix is a non-zero scalar multiple of any registry entry, that entry is used
+ *    directly: `Hz` for `1/s`, `V` for the volt matrix, `V^2` for its square, `1/V` for its
+ *    inverse.
+ *  - otherwise the matrix is greedily decomposed against compound registry entries (named
+ *    units with at least two non-zero exponents). The algorithm tries to use the fewest terms
+ *    possible — `V/m^2` is rendered as `V/m^2` (two terms) rather than `kg/(s^3·A)` (four
+ *    terms). Single-dimension entries (`METER`, `SECOND`, ...) are skipped here so the
+ *    leftover base residual renders in canonical `Mass·Length·Time·...` order.
+ *  - registry order acts as a tiebreaker — the first match wins among options with the same
+ *    term-count reduction.
+ *
+ * @param {UnitMatrix} unit_matrix
+ * @param {NamedUnit[]} [named_units] Optional registry of compound-unit symbols.
+ * @param {NamedUnit[]} [dimension_units=UNIT_DIMENSION_MAPPING] One {@link NamedUnit} per base dimension, indexed by {@link UnitDimension}. Only the `.symbol` field is read.
+ * @returns {string}
+ */
+export function unit_matrix_to_string(
+    unit_matrix,
+    named_units = undefined,
+    dimension_units = UNIT_DIMENSION_MAPPING
+) {
+    if (unit_matrix.is_dimensionless()) {
+        return '';
+    }
+
+    let numerator = '';
+    let denominator = '';
+    let residual;
+
+    if (named_units !== undefined && named_units.length > 0) {
+        // Phase 1: exact scalar match short-circuits to a single named term.
+        const scalar = find_scalar_match(unit_matrix.exponents, named_units);
+
+        if (scalar.index !== -1) {
+            const named = named_units[scalar.index];
+            const result = append_term('', '', named.symbol, scalar.power);
+
+            if (result[1] === '') {
+                return result[0];
+            }
+
+            return '1/' + result[1];
+        }
+
+        // Phase 2: greedy decomposition against compound entries; leftover residual renders
+        // via the base-residual pass below.
+        const decomposed = decompose_compound(unit_matrix, named_units);
+
+        numerator = decomposed.numerator;
+        denominator = decomposed.denominator;
+        residual = decomposed.residual;
+    } else {
+        residual = unit_matrix.exponents;
+    }
+
+    const result = append_base_residual(numerator, denominator, residual, dimension_units);
+    numerator = result[0];
+    denominator = result[1];
+
+    if (denominator === '') {
+        return numerator;
+    }
+
+    if (numerator === '') {
+        return '1/' + denominator;
+    }
+
+    return numerator + '/' + denominator;
+}