numbl 0.1.7 → 0.2.0

package/dist-lib/numbl-core/ops/bessel.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure-TS implementation of Bessel tensor ops.
+ * Mirrors native/ops/bessel.c — fallback when the native addon is unavailable.
+ *
+ * Delegates the per-element math to src/numbl-core/helpers/bessel.ts so both
+ * the scalar interpreter path and the tensor path share the same algorithm.
+ */
+/**
+ * out[i] = bessel<OP>(nu, z[i]).  scale mirrors the behavior of numbl_bessel_real.
+ */
+export declare function tsBesselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+/**
+ * Hankel function for real z:
+ *   kKind=1 → out[i] = J_nu(z[i]) + i * Y_nu(z[i])
+ *   kKind=2 → out[i] = J_nu(z[i]) - i * Y_nu(z[i])
+ * scaled=1 multiplies by exp(-i*z) (k=1) or exp(+i*z) (k=2).
+ */
+export declare function tsBesselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;

package/dist-lib/numbl-core/ops/comparison.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure-TS implementation of comparison ops.
+ * Mirrors native/ops/comparison.c.
+ *
+ * Output is 0.0 / 1.0 stored in a Float64Array (numbl's logical-tensor
+ * convention — caller wraps the result with _isLogical = true).
+ */
+export declare function tsRealComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+export declare function tsComplexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+export declare function tsComplexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-lib/numbl-core/ops/complexBinaryElemwise.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pure-TS implementation of complex binary element-wise ops, split storage.
+ * Mirrors native/ops/complex_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ * aIm/bIm/arrIm may be null → treat as zero.
+ * outIm is always required (caller allocates even if result might be real).
+ */
+export declare function tsComplexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;

package/dist-lib/numbl-core/ops/complexUnaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of complex unary element-wise ops, split storage.
+ * Mirrors native/ops/complex_unary_elemwise.c.
+ *
+ * ABS is intentionally unsupported (use tsComplexAbs — real-valued output).
+ */
+export declare function tsComplexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;

package/dist-lib/numbl-core/ops/dispatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tensor-ops dispatcher: chooses native bridge or pure-TS fallback.
+ *
+ * All entry points have identical signatures across native and TS impls.
+ * Caller owns input AND output memory; functions never allocate output.
+ *
+ * Selection happens once on first use per category and is cached
+ * (the bridge identity is captured at module load via getLapackBridge()).
+ */
+export declare const tensorOps: {
+    realBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    realUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    realComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    complexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    realFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    besselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    besselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+};

package/dist-lib/numbl-core/ops/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tensor-ops layer: pointer-based, op-code dispatched, native + TS parity.
+ *
+ * Every op has identical signatures across native (C) and TS implementations.
+ * Caller owns input AND output memory; ops never allocate output.
+ */
+export { tensorOps } from "./dispatch.js";
+export { OpRealBin, OpComplexBin, OpUnary, OpCmp, OpReduce, OpBessel, } from "./opCodes.js";

package/dist-lib/numbl-core/ops/opCodes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Op-code enums for the tensor-ops layer.
+ *
+ * SINGLE SOURCE OF TRUTH on the TS side. Mirrors native/ops/numbl_ops.h.
+ * Drift detection: src/__tests__/op-codes-sync.test.ts compares this file's
+ * values against numbl_dump_op_codes() at CI time.
+ */
+/** Real binary element-wise ops. */
+export declare const OpRealBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Complex binary element-wise ops. */
+export declare const OpComplexBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Flat reduction ops. */
+export declare const OpReduce: {
+    readonly SUM: 0;
+    readonly PROD: 1;
+    readonly MAX: 2;
+    readonly MIN: 3;
+    readonly ANY: 4;
+    readonly ALL: 5;
+    readonly MEAN: 6;
+};
+/** Comparison ops (logical output). */
+export declare const OpCmp: {
+    readonly EQ: 0;
+    readonly NE: 1;
+    readonly LT: 2;
+    readonly LE: 3;
+    readonly GT: 4;
+    readonly GE: 5;
+};
+/** Bessel function ops (real input). H-variants are in numbl_bessel_h (complex output). */
+export declare const OpBessel: {
+    readonly J: 0;
+    readonly Y: 1;
+    readonly I: 2;
+    readonly K: 3;
+};
+/** Unary element-wise ops (shared numbering for real + complex). */
+export declare const OpUnary: {
+    readonly EXP: 0;
+    readonly LOG: 1;
+    readonly LOG2: 2;
+    readonly LOG10: 3;
+    readonly SQRT: 4;
+    readonly ABS: 5;
+    readonly FLOOR: 6;
+    readonly CEIL: 7;
+    readonly ROUND: 8;
+    readonly TRUNC: 9;
+    readonly SIN: 10;
+    readonly COS: 11;
+    readonly TAN: 12;
+    readonly ASIN: 13;
+    readonly ACOS: 14;
+    readonly ATAN: 15;
+    readonly SINH: 16;
+    readonly COSH: 17;
+    readonly TANH: 18;
+    readonly SIGN: 19;
+};

package/dist-lib/numbl-core/ops/realBinaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of real binary element-wise ops.
+ * Mirrors native/ops/real_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ */
+export declare function tsRealBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-lib/numbl-core/ops/realUnaryElemwise.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Pure-TS implementation of real unary element-wise ops.
+ * Mirrors native/ops/real_unary_elemwise.c.
+ */
+export declare function tsRealUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;

package/dist-lib/numbl-core/ops/reduce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pure-TS flat reductions.  Mirrors native/ops/reduce.c.
+ * Caller-allocated input and output (1-element).
+ */
+export declare function tsRealFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+export declare function tsComplexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;

package/dist-lib/numbl-core/parser/types.d.ts

@@ -310,6 +310,12 @@ export type Stmt = {
     superClass: string | null;
     members: ClassMember[];
     span: Span;
+} | {
+    /** Magic comment directive, e.g. `%!numbl:assert_jit` or `%!numbl:assert_jit c`. */
+    type: "Directive";
+    directive: string;
+    args: string[];
+    span: Span;
 };
 export interface AbstractSyntaxTree {
     body: Stmt[];

package/dist-lib/numbl-core/runtime/alloc.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Allocate an UNINITIALIZED typed array — skips the zero-fill that
+ * `new Float64Array(n)` / `new FloatXArray(n)` perform by default.
+ *
+ * On Node, `Buffer.allocUnsafe` returns un-zeroed memory; wrapping it
+ * in a TypedArray view costs ~10× less than the zero-fill for a 16 MB
+ * buffer (~45 µs vs ~470 µs at N=2M doubles).
+ *
+ * SAFETY CONTRACT (very important):
+ *   The caller MUST write every element before reading it.  Any element
+ *   that is read before being written will contain arbitrary stale bytes
+ *   from recently-freed memory.  If you cannot guarantee full coverage,
+ *   use `new Float64Array(n)` / `new FloatXArray(n)` instead.
+ *
+ * In non-Node environments (browser, Deno without node-compat, …) where
+ * `Buffer` is unavailable, we fall back to the zero-filling constructor
+ * — still correct, just slower.
+ */
+import { FloatXArray } from "./types.js";
+type FloatXInstance = InstanceType<typeof FloatXArray>;
+export declare function uninitFloat64(n: number): Float64Array<ArrayBuffer>;
+export declare function uninitFloatX(n: number): FloatXInstance;
+export {};

package/dist-lib/numbl-core/runtime/runtime.d.ts

@@ -147,6 +147,7 @@ export declare class Runtime {
     /** Scalar power that returns complex for negative base with fractional exponent */
     pow(a: number, b: number): number | RuntimeComplexNumber;
     share(v: unknown): RuntimeValue;
+    get displayResults(): boolean;
     displayResult(v: unknown): void;
     displayAssign(name: string, v: unknown): void;
     getConstant(name: string): RuntimeValue;

package/dist-lib/numbl-core/version.d.ts

@@ -1,2 +1,2 @@
 /** Numbl version, used for JIT disk cache invalidation. */
-export declare const NUMBL_VERSION = "0.1.7";
+export declare const NUMBL_VERSION = "0.2.0";

package/native/jit_runtime/jit_runtime.c

@@ -0,0 +1,261 @@
+/**
+ * numbl_jit_runtime — see jit_runtime.h for the shape and invariants.
+ */
+
+#include "jit_runtime.h"
+#include "numbl_ops.h"
+
+#include <math.h>
+#include <string.h>
+#include <time.h>
+
+int numbl_jit_rt_version(void) {
+  return NUMBL_JIT_RT_VERSION;
+}
+
+double numbl_idx1r(const double* data, size_t len, double i, double* err_flag) {
+  /* Truncation-to-zero via int64 cast mirrors JS-JIT's `(i - 1) | 0`.
+   * Unsigned compare catches both negative idx and idx >= len in one
+   * branch. */
+  int64_t idx = (int64_t)(i - 1.0);
+  if ((uint64_t)idx >= (uint64_t)len) {
+    *err_flag = 1.0;
+    return 0.0;
+  }
+  return data[idx];
+}
+
+void numbl_set1r_h(double* data, size_t len, double i, double v,
+                   double* err_flag) {
+  int64_t idx = (int64_t)(i - 1.0);
+  if ((uint64_t)idx >= (uint64_t)len) {
+    /* 2.0 = "growth needed → soft-bail to interpreter", distinct from
+     * 1.0 which the JS wrapper translates into a hard bounds error. */
+    *err_flag = 2.0;
+    return;
+  }
+  data[idx] = v;
+}
+
+double numbl_idx2r(const double* data, size_t len, size_t d0,
+                   double i, double j, double* err_flag) {
+  int64_t r = (int64_t)(i - 1.0);
+  int64_t c = (int64_t)(j - 1.0);
+  /* d0 == 0 would mean an empty tensor — any index is OOB. */
+  if (d0 == 0 || (uint64_t)r >= (uint64_t)d0) {
+    *err_flag = 1.0;
+    return 0.0;
+  }
+  size_t cols = len / d0;
+  if ((uint64_t)c >= (uint64_t)cols) {
+    *err_flag = 1.0;
+    return 0.0;
+  }
+  return data[(size_t)c * d0 + (size_t)r];
+}
+
+double numbl_idx3r(const double* data, size_t len, size_t d0, size_t d1,
+                   double i, double j, double k, double* err_flag) {
+  int64_t k0 = (int64_t)(i - 1.0);
+  int64_t k1 = (int64_t)(j - 1.0);
+  int64_t k2 = (int64_t)(k - 1.0);
+  if (d0 == 0 || d1 == 0 ||
+      (uint64_t)k0 >= (uint64_t)d0 ||
+      (uint64_t)k1 >= (uint64_t)d1) {
+    *err_flag = 1.0;
+    return 0.0;
+  }
+  size_t plane = d0 * d1;
+  size_t d2 = len / plane;
+  if ((uint64_t)k2 >= (uint64_t)d2) {
+    *err_flag = 1.0;
+    return 0.0;
+  }
+  return data[(size_t)k2 * plane + (size_t)k1 * d0 + (size_t)k0];
+}
+
+void numbl_set2r_h(double* data, size_t len, size_t d0,
+                   double i, double j, double v, double* err_flag) {
+  int64_t r = (int64_t)(i - 1.0);
+  int64_t c = (int64_t)(j - 1.0);
+  if (d0 == 0) {
+    *err_flag = 2.0;
+    return;
+  }
+  size_t cols = len / d0;
+  if ((uint64_t)r >= (uint64_t)d0 || (uint64_t)c >= (uint64_t)cols) {
+    *err_flag = 2.0;
+    return;
+  }
+  data[(size_t)c * d0 + (size_t)r] = v;
+}
+
+void numbl_set3r_h(double* data, size_t len, size_t d0, size_t d1,
+                   double i, double j, double k, double v,
+                   double* err_flag) {
+  int64_t k0 = (int64_t)(i - 1.0);
+  int64_t k1 = (int64_t)(j - 1.0);
+  int64_t k2 = (int64_t)(k - 1.0);
+  if (d0 == 0 || d1 == 0) {
+    *err_flag = 2.0;
+    return;
+  }
+  size_t plane = d0 * d1;
+  size_t d2 = len / plane;
+  if ((uint64_t)k0 >= (uint64_t)d0 ||
+      (uint64_t)k1 >= (uint64_t)d1 ||
+      (uint64_t)k2 >= (uint64_t)d2) {
+    *err_flag = 2.0;
+    return;
+  }
+  data[(size_t)k2 * plane + (size_t)k1 * d0 + (size_t)k0] = v;
+}
+
+void numbl_setRange1r_h(double* dstData, size_t dstLen,
+                        double dstStart, double dstEnd,
+                        const double* srcData, size_t srcLen,
+                        double srcStart, double srcEnd,
+                        double* err_flag) {
+  int64_t dS = (int64_t)(dstStart - 1.0);
+  int64_t dE = (int64_t)(dstEnd - 1.0);
+  int64_t sS = (int64_t)(srcStart - 1.0);
+  int64_t sE = (int64_t)(srcEnd - 1.0);
+  int64_t dN = dE - dS + 1;
+  int64_t sN = sE - sS + 1;
+  if (dN != sN) {
+    /* 3.0 — length-mismatch error; JS wrapper translates to MATLAB's
+     * "Unable to perform assignment..." message. */
+    *err_flag = 3.0;
+    return;
+  }
+  if (dN <= 0) return;
+  if ((uint64_t)dS >= (uint64_t)dstLen ||
+      (uint64_t)dE >= (uint64_t)dstLen ||
+      (uint64_t)sS >= (uint64_t)srcLen ||
+      (uint64_t)sE >= (uint64_t)srcLen) {
+    *err_flag = 1.0;
+    return;
+  }
+  /* memmove handles overlap when src and dst alias. */
+  memmove(dstData + (size_t)dS, srcData + (size_t)sS,
+          (size_t)dN * sizeof(double));
+}
+
+void numbl_setCol2r_h(double* dstData, size_t dstRows, size_t dstLen,
+                      double col,
+                      const double* srcData, size_t srcLen,
+                      double* err_flag) {
+  if (srcLen != dstRows) {
+    *err_flag = 3.0;
+    return;
+  }
+  int64_t j = (int64_t)(col - 1.0);
+  if (j < 0) {
+    *err_flag = 1.0;
+    return;
+  }
+  if (dstRows == 0) {
+    /* Empty dst with a nonempty src: growth territory — soft-bail. */
+    *err_flag = 2.0;
+    return;
+  }
+  size_t dstCols = dstLen / dstRows;
+  if ((uint64_t)j >= (uint64_t)dstCols) {
+    /* Growth on write — the interpreter handles growing dst; JS-JIT
+     * mirrors this with JitBailToInterpreter. */
+    *err_flag = 2.0;
+    return;
+  }
+  memcpy(dstData + (size_t)j * dstRows, srcData,
+         dstRows * sizeof(double));
+}
+
+void numbl_copyRange1r(const double* srcData, size_t srcLen,
+                       double start, double end,
+                       double* dstData,
+                       double* err_flag) {
+  int64_t s = (int64_t)(start - 1.0);
+  int64_t e = (int64_t)(end - 1.0);
+  int64_t n = e - s + 1;
+  if (n <= 0) return;
+  if ((uint64_t)s >= (uint64_t)srcLen ||
+      (uint64_t)e >= (uint64_t)srcLen) {
+    *err_flag = 1.0;
+    return;
+  }
+  memcpy(dstData, srcData + (size_t)s, (size_t)n * sizeof(double));
+}
+
+double numbl_mod(double a, double b) {
+  if (b == 0.0) return a;
+  double r = fmod(a, b);
+  if (r != 0.0 && ((r < 0.0) != (b < 0.0))) r += b;
+  return r;
+}
+
+double numbl_sign(double x) {
+  if (x > 0.0) return 1.0;
+  if (x < 0.0) return -1.0;
+  return 0.0;
+}
+
+double numbl_reduce_flat(int op, const double* data, int64_t len) {
+  double out = 0.0;
+  numbl_real_flat_reduce(op, (size_t)len, data, &out);
+  return out;
+}
+
+double numbl_monotonic_time(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (double)ts.tv_sec + (double)ts.tv_nsec * 1e-9;
+}
+
+double numbl_tic(double* state) {
+  double t = numbl_monotonic_time();
+  *state = t;
+  return t;
+}
+
+double numbl_toc(const double* state) {
+  return numbl_monotonic_time() - *state;
+}
+
+/* ── NaN / Inf / finite predicates ─────────────────────────────────────
+ *
+ * Bit-pattern inspection so the answer doesn't depend on the caller's
+ * `-ffast-math` / `-ffinite-math-only` posture. IEEE-754 binary64
+ * double: sign bit (1) | exponent (11) | mantissa (52). NaN has
+ * exponent all-1s and non-zero mantissa; ±Inf has exponent all-1s and
+ * zero mantissa; finite values have exponent != all-1s.
+ *
+ * memcpy is the portable way to reinterpret the bit pattern (type-
+ * punning through a union is UB in strict C; the compiler may still
+ * generate a type-punning read from memcpy as a single mov on any
+ * real platform).
+ */
+
+static uint64_t bits_of(double x) {
+  uint64_t u;
+  memcpy(&u, &x, sizeof u);
+  return u;
+}
+
+#define NUMBL_DBL_EXP_MASK 0x7FF0000000000000ULL
+#define NUMBL_DBL_MANT_MASK 0x000FFFFFFFFFFFFFULL
+
+int numbl_is_nan(double x) {
+  uint64_t u = bits_of(x);
+  return (u & NUMBL_DBL_EXP_MASK) == NUMBL_DBL_EXP_MASK
+      && (u & NUMBL_DBL_MANT_MASK) != 0;
+}
+
+int numbl_is_inf(double x) {
+  uint64_t u = bits_of(x);
+  return (u & ~0x8000000000000000ULL) == NUMBL_DBL_EXP_MASK;
+}
+
+int numbl_is_finite(double x) {
+  uint64_t u = bits_of(x);
+  return (u & NUMBL_DBL_EXP_MASK) != NUMBL_DBL_EXP_MASK;
+}