@iyulab/u-numflow 0.5.0 → 0.6.0

package/README.md

@@ -17,7 +17,7 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 |--------|-------------|
 | `stats` | Descriptive statistics (mean, variance, skewness, kurtosis) with Welford's online algorithm and Neumaier summation |
 | `distributions` | Probability distributions: Uniform, Triangular, PERT, Normal, LogNormal |
-| `special` | Special functions: normal/t/F/chi² CDF, inverse normal CDF, regularized incomplete beta/gamma, erf |
+| `special` | Special functions: normal CDF and tail-precise survival function (and their inverses), t/F/chi² CDF, regularized incomplete beta/gamma, erf |
 | `transforms` | Data transformations: Box-Cox (λ via MLE golden-section search), inverse Box-Cox |
 | `fourier` | Discrete Fourier transform of any length (radix-2 for powers of two, Bluestein otherwise): `fft`, `ifft`, `rfft`, `Complex` |
 | `matrix` | Dense matrix operations: determinant, inverse, Cholesky decomposition, Jacobi eigenvalue decomposition |
@@ -100,7 +100,7 @@ The package resolves per environment via a conditional `exports` map:
 | Bundlers (webpack, Vite, …) | ESM + WebAssembly ESM-integration (`default` condition) |
 | Node.js — `require()`, ESM `import`, CJS TS runners (`tsx`, `ts-node`) | CJS glue loading the wasm from the filesystem (`node` condition) — no loader hooks or flags |
 
-Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `box_cox`, `estimate_lambda`, and
+Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (upper tail `P(Z > x)`, computed directly so tail probabilities keep ~15 significant digits), `box_cox`, `estimate_lambda` (returns `{ lambda, at_bound }` — `at_bound` is `true` when the likelihood was still rising at an end of the search range, so `lambda` is that limit), and
 `rfft(data) -> Float64Array` — the DFT of a real sequence of any length, interleaved as
 `[re0, im0, re1, im1, …]` (bins `k` and `n − k` are conjugates, so `0..=n/2` describes the spectrum).
 

package/node/u_numflow.cjs

@@ -28,15 +28,20 @@ exports.box_cox = box_cox;
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
- * Searches in the range `[lambda_min, lambda_max]` using golden-section search.
+ * Searches in the range `[lambda_min, lambda_max]` using golden-section search
+ * and returns `{ lambda: number, at_bound: boolean }`. `at_bound` is `true`
+ * when the maximum lies on an end of the range — the likelihood was still
+ * rising there, so `lambda` is that range limit (reported exactly), not an
+ * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
  * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or `lambda_min >= lambda_max`.
+ * has fewer than 2 elements, or the range is not finite with
+ * `lambda_min < lambda_max`.
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
- * @returns {number}
+ * @returns {any}
  */
 function estimate_lambda(data, lambda_min, lambda_max) {
     const ptr0 = passArrayF64ToWasm0(data, wasm.__wbindgen_malloc);
@@ -45,7 +50,7 @@ function estimate_lambda(data, lambda_min, lambda_max) {
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
-    return ret[0];
+    return takeFromExternrefTable0(ret[0]);
 }
 exports.estimate_lambda = estimate_lambda;
 
@@ -69,7 +74,8 @@ exports.mean = mean;
  *
  * To evaluate a general normal N(μ, σ), pass `(x - μ) / σ`.
  *
- * Uses Abramowitz & Stegun formula 26.2.17 (max abs error < 7.5 × 10⁻⁸).
+ * Computed as `erfc(−x/√2)/2` with a direct `erfc`, so the lower tail keeps
+ * relative precision. For the upper tail use [`normal_sf`].
  * @param {number} x
  * @returns {number}
  */
@@ -79,6 +85,21 @@ function normal_cdf(x) {
 }
 exports.normal_cdf = normal_cdf;
 
+/**
+ * Standard normal survival function P(Z > x) = 1 − Φ(x) for Z ~ N(0, 1).
+ *
+ * Computed directly (not as `1 − normal_cdf(x)`), so upper-tail
+ * probabilities such as PPM defect rates keep their significant digits:
+ * `normal_sf(6)` is `9.865876450376948e-10` to about 15 digits.
+ * @param {number} x
+ * @returns {number}
+ */
+function normal_sf(x) {
+    const ret = wasm.normal_sf(x);
+    return ret;
+}
+exports.normal_sf = normal_sf;
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -130,7 +151,29 @@ exports.variance = variance;
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbindgen_generic_0000000000000001: function(arg0, arg1) {
+        __wbg_String_8564e559799eccda: function(arg0, arg1) {
+            const ret = String(arg1);
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_new_bebc3f4757acf305: function() {
+            const ret = new Object();
+            return ret;
+        },
+        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
+            arg0[arg1] = arg2;
+        },
+        __wbindgen_generic_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_generic_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
@@ -156,6 +199,14 @@ function getArrayF64FromWasm0(ptr, len) {
     return getFloat64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
 }
 
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
 let cachedFloat64ArrayMemory0 = null;
 function getFloat64ArrayMemory0() {
     if (cachedFloat64ArrayMemory0 === null || cachedFloat64ArrayMemory0.byteLength === 0) {
@@ -183,6 +234,43 @@ function passArrayF64ToWasm0(arg, malloc) {
     return ptr;
 }
 
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
 function takeFromExternrefTable0(idx) {
     const value = wasm.__wbindgen_externrefs.get(idx);
     wasm.__externref_table_dealloc(idx);
@@ -195,6 +283,19 @@ function decodeText(ptr, len) {
     return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
 }
 
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
 let WASM_VECTOR_LEN = 0;
 
 const wasmPath = `${__dirname}/u_numflow_bg.wasm`;

package/node/u_numflow.d.cts

@@ -15,13 +15,18 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
- * Searches in the range `[lambda_min, lambda_max]` using golden-section search.
+ * Searches in the range `[lambda_min, lambda_max]` using golden-section search
+ * and returns `{ lambda: number, at_bound: boolean }`. `at_bound` is `true`
+ * when the maximum lies on an end of the range — the likelihood was still
+ * rising there, so `lambda` is that range limit (reported exactly), not an
+ * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
  * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or `lambda_min >= lambda_max`.
+ * has fewer than 2 elements, or the range is not finite with
+ * `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): number;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): any;
 
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
@@ -35,10 +40,20 @@ export function mean(data: Float64Array): number;
  *
  * To evaluate a general normal N(μ, σ), pass `(x - μ) / σ`.
  *
- * Uses Abramowitz & Stegun formula 26.2.17 (max abs error < 7.5 × 10⁻⁸).
+ * Computed as `erfc(−x/√2)/2` with a direct `erfc`, so the lower tail keeps
+ * relative precision. For the upper tail use [`normal_sf`].
  */
 export function normal_cdf(x: number): number;
 
+/**
+ * Standard normal survival function P(Z > x) = 1 − Φ(x) for Z ~ N(0, 1).
+ *
+ * Computed directly (not as `1 − normal_cdf(x)`), so upper-tail
+ * probabilities such as PPM defect rates keep their significant digits:
+ * `normal_sf(6)` is `9.865876450376948e-10` to about 15 digits.
+ */
+export function normal_sf(x: number): number;
+
 /**
  * Forward DFT of a real sequence of any length.
  *

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Foundational mathematical primitives: statistics, probability distributions, random sampling, and collections.",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_numflow.d.ts

@@ -15,13 +15,18 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
- * Searches in the range `[lambda_min, lambda_max]` using golden-section search.
+ * Searches in the range `[lambda_min, lambda_max]` using golden-section search
+ * and returns `{ lambda: number, at_bound: boolean }`. `at_bound` is `true`
+ * when the maximum lies on an end of the range — the likelihood was still
+ * rising there, so `lambda` is that range limit (reported exactly), not an
+ * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
  * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or `lambda_min >= lambda_max`.
+ * has fewer than 2 elements, or the range is not finite with
+ * `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): number;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): any;
 
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
@@ -35,10 +40,20 @@ export function mean(data: Float64Array): number;
  *
  * To evaluate a general normal N(μ, σ), pass `(x - μ) / σ`.
  *
- * Uses Abramowitz & Stegun formula 26.2.17 (max abs error < 7.5 × 10⁻⁸).
+ * Computed as `erfc(−x/√2)/2` with a direct `erfc`, so the lower tail keeps
+ * relative precision. For the upper tail use [`normal_sf`].
  */
 export function normal_cdf(x: number): number;
 
+/**
+ * Standard normal survival function P(Z > x) = 1 − Φ(x) for Z ~ N(0, 1).
+ *
+ * Computed directly (not as `1 − normal_cdf(x)`), so upper-tail
+ * probabilities such as PPM defect rates keep their significant digits:
+ * `normal_sf(6)` is `9.865876450376948e-10` to about 15 digits.
+ */
+export function normal_sf(x: number): number;
+
 /**
  * Forward DFT of a real sequence of any length.
  *

package/u_numflow.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./u_numflow_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    box_cox, estimate_lambda, mean, normal_cdf, rfft, std_dev, variance
+    box_cox, estimate_lambda, mean, normal_cdf, normal_sf, rfft, std_dev, variance
 } from "./u_numflow_bg.js";

package/u_numflow_bg.js

@@ -25,15 +25,20 @@ export function box_cox(data, lambda) {
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
- * Searches in the range `[lambda_min, lambda_max]` using golden-section search.
+ * Searches in the range `[lambda_min, lambda_max]` using golden-section search
+ * and returns `{ lambda: number, at_bound: boolean }`. `at_bound` is `true`
+ * when the maximum lies on an end of the range — the likelihood was still
+ * rising there, so `lambda` is that range limit (reported exactly), not an
+ * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
  * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or `lambda_min >= lambda_max`.
+ * has fewer than 2 elements, or the range is not finite with
+ * `lambda_min < lambda_max`.
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
- * @returns {number}
+ * @returns {any}
  */
 export function estimate_lambda(data, lambda_min, lambda_max) {
     const ptr0 = passArrayF64ToWasm0(data, wasm.__wbindgen_malloc);
@@ -42,7 +47,7 @@ export function estimate_lambda(data, lambda_min, lambda_max) {
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
-    return ret[0];
+    return takeFromExternrefTable0(ret[0]);
 }
 
 /**
@@ -64,7 +69,8 @@ export function mean(data) {
  *
  * To evaluate a general normal N(μ, σ), pass `(x - μ) / σ`.
  *
- * Uses Abramowitz & Stegun formula 26.2.17 (max abs error < 7.5 × 10⁻⁸).
+ * Computed as `erfc(−x/√2)/2` with a direct `erfc`, so the lower tail keeps
+ * relative precision. For the upper tail use [`normal_sf`].
  * @param {number} x
  * @returns {number}
  */
@@ -73,6 +79,20 @@ export function normal_cdf(x) {
     return ret;
 }
 
+/**
+ * Standard normal survival function P(Z > x) = 1 − Φ(x) for Z ~ N(0, 1).
+ *
+ * Computed directly (not as `1 − normal_cdf(x)`), so upper-tail
+ * probabilities such as PPM defect rates keep their significant digits:
+ * `normal_sf(6)` is `9.865876450376948e-10` to about 15 digits.
+ * @param {number} x
+ * @returns {number}
+ */
+export function normal_sf(x) {
+    const ret = wasm.normal_sf(x);
+    return ret;
+}
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -118,7 +138,29 @@ export function variance(data) {
     const ret = wasm.variance(ptr0, len0);
     return ret;
 }
-export function __wbindgen_generic_0000000000000001(arg0, arg1) {
+export function __wbg_String_8564e559799eccda(arg0, arg1) {
+    const ret = String(arg1);
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg___wbindgen_throw_5d9e815e6fdf150f(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+}
+export function __wbg_new_bebc3f4757acf305() {
+    const ret = new Object();
+    return ret;
+}
+export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
+    arg0[arg1] = arg2;
+}
+export function __wbindgen_generic_0000000000000001(arg0) {
+    // Cast intrinsic for `F64 -> Externref`.
+    const ret = arg0;
+    return ret;
+}
+export function __wbindgen_generic_0000000000000002(arg0, arg1) {
     // Cast intrinsic for `Ref(String) -> Externref`.
     const ret = getStringFromWasm0(arg0, arg1);
     return ret;
@@ -137,6 +179,14 @@ function getArrayF64FromWasm0(ptr, len) {
     return getFloat64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
 }
 
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
 let cachedFloat64ArrayMemory0 = null;
 function getFloat64ArrayMemory0() {
     if (cachedFloat64ArrayMemory0 === null || cachedFloat64ArrayMemory0.byteLength === 0) {
@@ -164,6 +214,43 @@ function passArrayF64ToWasm0(arg, malloc) {
     return ptr;
 }
 
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
 function takeFromExternrefTable0(idx) {
     const value = wasm.__wbindgen_externrefs.get(idx);
     wasm.__externref_table_dealloc(idx);
@@ -184,6 +271,19 @@ function decodeText(ptr, len) {
     return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
 }
 
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
 let WASM_VECTOR_LEN = 0;