@danielsimonjr/mathts-core 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -2445,6 +2445,116 @@ declare const math: {
     configure: (config: Partial<MathTSConfig>) => void;
 };
 
+/**
+ * Numerically stable reduction primitives.
+ *
+ * Floating-point addition is not associative, so *how* you accumulate decides how much error you
+ * carry. These are the algorithms the established numerical stack uses, and the reason it is
+ * trusted.
+ *
+ * Measured on this repo's own reductions before these existed — 1e6 copies of `0.1`, exact answer
+ * 100000:
+ *
+ * | accumulation                    | relative error |
+ * | ------------------------------- | -------------- |
+ * | naive `s += x`                  | **1.3e-11**    |
+ * | pairwise (this, = NumPy's algo) | **2.9e-16**    |
+ * | Neumaier compensated (`fsum`)   | **0** (exact)  |
+ *
+ * NumPy 2.3.4 reports 2.9e-16 on the same input — we are now at parity. Before this, we were
+ * ~46,000× worse than NumPy on a bog-standard `sum`, and `mean`, `std`, `var` and every statistic
+ * inherit that error.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Sum with **pairwise (cascade) summation** — the algorithm behind `np.sum`.
+ *
+ * Naive accumulation lets the running total grow large while the addends stay small, so each
+ * addition rounds off a little more of the total: error grows as **O(n)·ε**. Pairwise summation
+ * adds numbers of *comparable magnitude* by recursively halving the range, so error grows as
+ * **O(log n)·ε** — for n = 10⁶ that is the difference between ~1e-11 and ~1e-16.
+ *
+ * It costs the same number of additions as the naive loop. There is no speed/accuracy trade here;
+ * the naive version is simply worse.
+ *
+ * Not exact: for that, use {@link neumaierSum}. Pairwise is the right default because it is free.
+ */
+declare function pairwiseSum(xs: ArrayLike<number>, start?: number, end?: number): number;
+/**
+ * Sum with **Neumaier compensation** — correctly rounded for practical purposes, the equivalent
+ * of Python's `math.fsum`.
+ *
+ * Tracks the low-order bits that each addition throws away and folds them back in at the end. It
+ * recovers information that pairwise summation cannot: `[1e16, 1, -1e16]` sums to **1** here,
+ * while both naive and pairwise (and `np.sum`) give **0**, because the `1` is annihilated the
+ * moment it meets `1e16`.
+ *
+ * ~2-4× slower than {@link pairwiseSum}, so it is opt-in rather than the default. Reach for it
+ * when catastrophic cancellation is possible: near-zero results from large terms, long-running
+ * accumulators, conservation checks.
+ *
+ * (Neumaier's variant, not classic Kahan: Kahan loses the compensation when the *addend* is
+ * larger than the running sum, which is precisely the `1e16` case.)
+ */
+declare function neumaierSum(xs: ArrayLike<number>): number;
+/**
+ * Euclidean (2-)norm that does **not** overflow or underflow — BLAS's `dnrm2` scaling.
+ *
+ * The obvious `sqrt(Σxᵢ²)` squares before it adds, so it dies well inside the representable
+ * range: `‖[1e200, 1e200, 1e200, 1e200]‖` overflows to `Infinity` (the true answer, 2e200, is
+ * perfectly representable), and `‖[1e-200] × 4‖` **flushes to 0** — a silent wrong answer, which
+ * is worse.
+ *
+ * NumPy has this bug too: `np.linalg.norm([1e200]*4)` returns `inf` with an overflow warning.
+ * LAPACK does not, and neither do we.
+ *
+ * The fix is to carry a running scale: keep the largest magnitude seen out of the sum of squares,
+ * so the accumulator only ever holds ratios in [0, 1].
+ */
+declare function norm2(xs: ArrayLike<number>): number;
+/**
+ * Dot product `Σ aᵢ·bᵢ` with **pairwise (cascade) summation** of the products — the accuracy of
+ * {@link pairwiseSum} applied to a dot without materialising the product array.
+ *
+ * A naive `s += a[i]*b[i]` loop carries the same **O(n)·ε** error as a naive sum; measured against
+ * an exact reference on an ill-conditioned dot (large mean × small factor, n = 10⁶) it is ~18×
+ * worse than `np.dot`, which sums pairwise. This closes that gap — and, like {@link pairwiseSum},
+ * costs the same number of flops as the naive loop.
+ *
+ * The two ranges are assumed the same length; callers guard that. Reads only `[start, end)`.
+ */
+declare function pairwiseDot(a: ArrayLike<number>, b: ArrayLike<number>, start?: number, end?: number): number;
+/**
+ * Euclidean distance `‖a − b‖₂` that does **not** overflow or underflow — {@link norm2}'s BLAS
+ * `dnrm2` scaling applied to the elementwise difference.
+ *
+ * `distance` is just a 2-norm, so the obvious `sqrt(Σ(aᵢ−bᵢ)²)` inherits norm's pathology: it
+ * squares before it adds, overflowing to `Infinity` and — the dangerous case — **flushing to a
+ * silent 0** for small differences well inside the representable range. NumPy's `linalg.norm` has
+ * the same bug; scaling on the largest *difference* seen avoids both. The scale tracks the residual
+ * `a − b`, not the inputs, so it stays accurate even when `a` and `b` are individually huge.
+ *
+ * The two ranges are assumed the same length; callers guard that.
+ */
+declare function scaledDistance(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * Cumulative sum with **Neumaier compensation** — each prefix total is written to `out[i]` carrying
+ * the low-order bits a naive running sum throws away.
+ *
+ * A cumulative sum is an inherently sequential prefix scan, so pairwise summation does not apply:
+ * you need every intermediate total, not just the final one. `np.cumsum` therefore accumulates
+ * naively and its tail drifts by **O(n)·ε** (relErr ~1.3e-11 over 10⁶ terms). Carrying a running
+ * compensation costs a few extra flops per element, no extra memory, and makes every prefix exact
+ * for practical purposes — a strict improvement over NumPy where accumulated drift matters (e.g.
+ * integrating a signal).
+ *
+ * Writes `out[i]` for `i` in `[0, xs.length)`; `out` may be a `number[]` or a `Float64Array`.
+ */
+declare function neumaierCumsum(xs: ArrayLike<number>, out: {
+    [index: number]: number;
+}): void;
+
 /**
  * @danielsimonjr/mathts-core - Core types and utilities for MathTS
  * @packageDocumentation
@@ -2452,4 +2562,4 @@ declare const math: {
 
 declare const VERSION = "0.1.0";
 
-export { ALL_UNITS, BASE_UNITS, BEST_PREFIXES, BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, DERIVED_UNITS, DIMENSIONLESS, DUAL_UNARY_RULES, DimensionMismatchError, type Dimensions, Dual, type DualUnaryRule, type DualUnaryRuleName, E, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, LN10, LN2, LOG10E, LOG2E, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericScalar, type NumericType, PHI, PI, Range, type RangeForEachCallback, type RangeFormatOptions, type RangeJSON, type RangeMapCallback, type RoundingMode, SI_PREFIXES, SQRT1_2, SQRT2, type Scalar, TAU, type TypeDef, TypeRegistry, UNIT_ALIASES, type UnitDef, UnitParseError, VERSION, abs, addScalar, createFactory, createMathTSTyped, createRangeClass, createTypedFunction, dim, divideScalar, equal, fix, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isDual, isFraction, isFunction, isMatrix, isNull, isNumber, isNumeric, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, math, mathTyped, multiplyScalar, number, pow, registerNativeTypes, registry, round, subtractScalar };
+export { ALL_UNITS, BASE_UNITS, BEST_PREFIXES, BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, DERIVED_UNITS, DIMENSIONLESS, DUAL_UNARY_RULES, DimensionMismatchError, type Dimensions, Dual, type DualUnaryRule, type DualUnaryRuleName, E, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, LN10, LN2, LOG10E, LOG2E, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericScalar, type NumericType, PHI, PI, Range, type RangeForEachCallback, type RangeFormatOptions, type RangeJSON, type RangeMapCallback, type RoundingMode, SI_PREFIXES, SQRT1_2, SQRT2, type Scalar, TAU, type TypeDef, TypeRegistry, UNIT_ALIASES, type UnitDef, UnitParseError, VERSION, abs, addScalar, createFactory, createMathTSTyped, createRangeClass, createTypedFunction, dim, divideScalar, equal, fix, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isDual, isFraction, isFunction, isMatrix, isNull, isNumber, isNumeric, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, math, mathTyped, multiplyScalar, neumaierCumsum, neumaierSum, norm2, number, pairwiseDot, pairwiseSum, pow, registerNativeTypes, registry, round, scaledDistance, subtractScalar };

package/dist/index.js

@@ -1186,6 +1186,129 @@ var math = {
   configure: (config) => registry.updateConfig(config)
 };
 
+// src/numeric/stable.ts
+var PAIRWISE_BLOCK = 128;
+function pairwiseSum(xs, start = 0, end = xs.length) {
+  const n = end - start;
+  if (n <= PAIRWISE_BLOCK) {
+    let s0 = 0;
+    let s1 = 0;
+    let s2 = 0;
+    let s3 = 0;
+    let s4 = 0;
+    let s5 = 0;
+    let s6 = 0;
+    let s7 = 0;
+    let i = start;
+    const limit = start + (n - n % 8);
+    for (; i < limit; i += 8) {
+      s0 += xs[i];
+      s1 += xs[i + 1];
+      s2 += xs[i + 2];
+      s3 += xs[i + 3];
+      s4 += xs[i + 4];
+      s5 += xs[i + 5];
+      s6 += xs[i + 6];
+      s7 += xs[i + 7];
+    }
+    let tail = 0;
+    for (; i < end; i++) tail += xs[i];
+    return s0 + s1 + (s2 + s3) + (s4 + s5 + (s6 + s7)) + tail;
+  }
+  const half = (n >> 1) - (n >> 1) % 8;
+  return pairwiseSum(xs, start, start + half) + pairwiseSum(xs, start + half, end);
+}
+function neumaierSum(xs) {
+  let sum = 0;
+  let c = 0;
+  for (let i = 0; i < xs.length; i++) {
+    const x = xs[i];
+    const t = sum + x;
+    c += Math.abs(sum) >= Math.abs(x) ? sum - t + x : x - t + sum;
+    sum = t;
+  }
+  return sum + c;
+}
+function norm2(xs) {
+  let scale = 0;
+  let ssq = 1;
+  for (let i = 0; i < xs.length; i++) {
+    const x = xs[i];
+    if (x === 0) continue;
+    if (Number.isNaN(x)) return NaN;
+    const ax = Math.abs(x);
+    if (scale < ax) {
+      const r = scale / ax;
+      ssq = 1 + ssq * r * r;
+      scale = ax;
+    } else {
+      const r = ax / scale;
+      ssq += r * r;
+    }
+  }
+  return scale === 0 ? 0 : scale * Math.sqrt(ssq);
+}
+function pairwiseDot(a, b, start = 0, end = a.length) {
+  const n = end - start;
+  if (n <= PAIRWISE_BLOCK) {
+    let s0 = 0;
+    let s1 = 0;
+    let s2 = 0;
+    let s3 = 0;
+    let s4 = 0;
+    let s5 = 0;
+    let s6 = 0;
+    let s7 = 0;
+    let i = start;
+    const limit = start + (n - n % 8);
+    for (; i < limit; i += 8) {
+      s0 += a[i] * b[i];
+      s1 += a[i + 1] * b[i + 1];
+      s2 += a[i + 2] * b[i + 2];
+      s3 += a[i + 3] * b[i + 3];
+      s4 += a[i + 4] * b[i + 4];
+      s5 += a[i + 5] * b[i + 5];
+      s6 += a[i + 6] * b[i + 6];
+      s7 += a[i + 7] * b[i + 7];
+    }
+    let tail = 0;
+    for (; i < end; i++) tail += a[i] * b[i];
+    return s0 + s1 + (s2 + s3) + (s4 + s5 + (s6 + s7)) + tail;
+  }
+  const half = (n >> 1) - (n >> 1) % 8;
+  return pairwiseDot(a, b, start, start + half) + pairwiseDot(a, b, start + half, end);
+}
+function scaledDistance(a, b) {
+  let scale = 0;
+  let ssq = 1;
+  for (let i = 0; i < a.length; i++) {
+    const d = a[i] - b[i];
+    if (d === 0) continue;
+    if (Number.isNaN(d)) return NaN;
+    const ad = Math.abs(d);
+    if (scale < ad) {
+      const r = scale / ad;
+      ssq = 1 + ssq * r * r;
+      scale = ad;
+    } else {
+      const r = ad / scale;
+      ssq += r * r;
+    }
+  }
+  return scale === 0 ? 0 : scale * Math.sqrt(ssq);
+}
+function neumaierCumsum(xs, out) {
+  let sum = 0;
+  let c = 0;
+  for (let i = 0; i < xs.length; i++) {
+    const x = xs[i];
+    const t = sum + x;
+    c += Math.abs(sum) >= Math.abs(x) ? sum - t + x : x - t + sum;
+    sum = t;
+    out[i] = sum + c;
+  }
+}
+
 // src/index.ts
 var VERSION = "0.1.0";
 export {
@@ -1276,11 +1399,17 @@ export {
   math,
   mathTyped,
   multiplyScalar,
+  neumaierCumsum,
+  neumaierSum,
+  norm2,
   number,
+  pairwiseDot,
+  pairwiseSum,
   pow,
   registerNativeTypes,
   registry,
   round,
+  scaledDistance,
   subtractScalar,
   typed
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Core types, utilities, and configuration for MathTS",
   "author": "Daniel Simon Jr.",
   "license": "MIT",