@danielsimonjr/mathts-core 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -2445,6 +2445,75 @@ 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;
+
 /**
  * @danielsimonjr/mathts-core - Core types and utilities for MathTS
  * @packageDocumentation
@@ -2452,4 +2521,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, neumaierSum, norm2, number, pairwiseSum, pow, registerNativeTypes, registry, round, subtractScalar };

package/dist/index.js

@@ -1186,6 +1186,69 @@ 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);
+}
+
 // src/index.ts
 var VERSION = "0.1.0";
 export {
@@ -1276,7 +1339,10 @@ export {
   math,
   mathTyped,
   multiplyScalar,
+  neumaierSum,
+  norm2,
   number,
+  pairwiseSum,
   pow,
   registerNativeTypes,
   registry,

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@danielsimonjr/mathts-core",
-  "version": "0.6.0",
-  "description": "Core types, utilities, and configuration for MathTS",
-  "author": "Daniel Simon Jr.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./internal": {
-      "import": "./dist/internal.js",
-      "types": "./dist/internal.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/internal.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts src/internal.ts --format esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "clean": "rm -rf dist",
-    "build:prod": "tsup src/index.ts --format esm --dts --clean --minify --treeshake"
-  },
-  "dependencies": {
-    "typed-function": "github:danielsimonjr/typed-function"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/danielsimonjr/mathts",
-    "directory": "core"
-  },
-  "keywords": [
-    "math",
-    "typescript",
-    "core"
-  ]
-}
+{
+  "name": "@danielsimonjr/mathts-core",
+  "version": "0.7.0",
+  "description": "Core types, utilities, and configuration for MathTS",
+  "author": "Daniel Simon Jr.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./internal": {
+      "import": "./dist/internal.js",
+      "types": "./dist/internal.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/internal.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/internal.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "build:prod": "tsup src/index.ts --format esm --dts --clean --minify --treeshake"
+  },
+  "dependencies": {
+    "typed-function": "github:danielsimonjr/typed-function"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/mathts",
+    "directory": "core"
+  },
+  "keywords": [
+    "math",
+    "typescript",
+    "core"
+  ]
+}