numbl 0.1.7 → 0.3.0

package/dist-lib/numbl-core/jit/js/jsMultiReduction.d.ts

@@ -0,0 +1,70 @@
+/**
+ * JS-side multi-reduction block emission.
+ *
+ * Detection + dispatch for scalar Assigns of the form
+ *
+ *   acc = <expr tree with >=2 reductions over a single tensor Var>
+ *
+ * On match, the JS codegen emits a block that runs a single-pass
+ * reduction loop (either an inline JS loop, or a compiled C kernel
+ * under --opt e1), stashes each reduction result in a local, and then
+ * emits the Assign's RHS with each reduction Call substituted by the
+ * local that holds its value. The RHS-substitution contract lives in
+ * `jitCodegen._multiReductionSubst`, which this module installs and
+ * clears around the `emitExpr` call the caller provides.
+ *
+ * Limited to:
+ *   - sum / prod / max / min / mean (short-circuit any/all excluded)
+ *   - a single tensor Var argument to every reduction
+ *   - all reductions read the same tensor name
+ *   - the tensor is real-typed
+ *   - at least two reductions in the RHS
+ *
+ * NaN semantics for max/min are matched to MATLAB omit-NaN behaviour:
+ * IEEE unordered compare already skips NaN, and an `any_non_nan` flag
+ * drives the all-NaN → NaN fallback.
+ */
+import type { JitExpr, JitStmt } from "../jitTypes.js";
+import { type MultiReduceOp } from "../e1/multiReductionKernel.js";
+export interface MultiReductionMatch {
+    /** The scalar Assign being emitted (target + original RHS). */
+    stmt: JitStmt & {
+        tag: "Assign";
+    };
+    /** The tensor variable name all reductions read. */
+    tensorName: string;
+    /** Distinct ops that actually appear, in first-occurrence order. Used
+     *  to size the kernel's output buffer and decide which accumulators
+     *  to declare on the JS fallback path. */
+    ops: MultiReduceOp[];
+    /** Every reduction Call node found in the RHS, paired with its op.
+     *  The JS emitter builds a substitution map from each Call to the
+     *  local that holds its result. */
+    sites: {
+        call: JitExpr & {
+            tag: "Call";
+        };
+        op: MultiReduceOp;
+    }[];
+}
+/** Try to match the multi-reduction pattern on a single statement. */
+export declare function tryMatchMultiReduction(stmt: JitStmt): MultiReductionMatch | null;
+/**
+ * Emit the multi-reduction block. Writes into `lines`.
+ *
+ * The block:
+ *   1. Aliases `<tensorName>.data` to a local and reads its length.
+ *   2. Under e1, compiles/dispatches a single-pass C kernel that fills
+ *      a Float64Array scratch with the accumulator values, with an
+ *      inline JS fallback at small `n`. Under non-e1, emits just the
+ *      JS loop.
+ *   3. Post-loop: `mean = sum / n`, and a NaN fixup for max/min when
+ *      every input element was NaN.
+ *   4. Installs `_multiReductionSubst` pointing each reduction Call at
+ *      its local, emits the Assign's RHS via the caller-provided
+ *      `emitExpr`, and writes the final `<target> = <rhs>;`.
+ */
+export declare function emitMultiReductionBlock(lines: string[], indent: string, match: MultiReductionMatch, mangleName: (n: string) => string, emitExprWithSubst: (expr: JitExpr, subst: Map<JitExpr, string>) => string, experimental: string | undefined, par: boolean): void;
+/** Reset per-function counter so generated names stay stable between
+ *  compiles of the same IR. Called from `generateJS`. */
+export declare function resetMultiReductionState(): void;

package/dist-lib/numbl-core/jit/scalarEmit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared scalar-expression emission used by both the JS-JIT and C-JIT
+ * backends.
+ *
+ * The value-form switches for scalar Binary/Unary and the truthiness
+ * walker have identical IR traversal between the two backends — only
+ * the leaf syntax (operator spelling, coercion rules) differs. A
+ * backend supplies a `ScalarOpTarget` describing how to spell each op,
+ * and the shared functions below handle the dispatch.
+ *
+ * Complex-scalar and tensor ops are *not* covered here — those remain
+ * backend-specific (JS uses `$h.cAdd` etc.; C-JIT bails on complex).
+ */
+import { BinaryOperation, UnaryOperation } from "../parser/types.js";
+import type { JitExpr } from "./jitTypes.js";
+export interface ScalarOpTarget {
+    binAdd(l: string, r: string): string;
+    binSub(l: string, r: string): string;
+    binMul(l: string, r: string): string;
+    binDiv(l: string, r: string): string;
+    binPow(l: string, r: string): string;
+    binEq(l: string, r: string): string;
+    binNe(l: string, r: string): string;
+    binLt(l: string, r: string): string;
+    binLe(l: string, r: string): string;
+    binGt(l: string, r: string): string;
+    binGe(l: string, r: string): string;
+    binAnd(l: string, r: string): string;
+    binOr(l: string, r: string): string;
+    unaryPlus(operand: string): string;
+    unaryMinus(operand: string): string;
+    unaryNot(operand: string): string;
+    toTruthy(valueExpr: string): string;
+    condEq(l: string, r: string): string;
+    condNe(l: string, r: string): string;
+    condLt(l: string, r: string): string;
+    condLe(l: string, r: string): string;
+    condGt(l: string, r: string): string;
+    condGe(l: string, r: string): string;
+    condNot(truthyExpr: string): string;
+    condAnd(l: string, r: string): string;
+    condOr(l: string, r: string): string;
+}
+/** Dispatch a scalar Binary op to the target. Throws on unsupported ops. */
+export declare function emitScalarBinaryOp(op: BinaryOperation, left: string, right: string, target: ScalarOpTarget): string;
+/** Dispatch a scalar Unary op to the target. Transpose is scalar-identity. */
+export declare function emitScalarUnaryOp(op: UnaryOperation, operand: string, target: ScalarOpTarget): string;
+/**
+ * Emit a condition expression for `if` / `while` / `&&` / `||` operands.
+ *
+ * Recurses through nested comparison / logical operators so that the
+ * whole condition emits as a native boolean/condition expression rather
+ * than being wrapped in a trailing `!= 0` on every nested result.
+ *
+ * `emitValue` is the backend's value-form expression emitter — it is
+ * called for the leaf operands of comparisons and for the fallback path.
+ */
+export declare function emitScalarTruthiness(expr: JitExpr, emitValue: (e: JitExpr) => string, target: ScalarOpTarget): string;

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

@@ -68,7 +68,8 @@ export declare enum Token {
     Ellipsis = 66,
     Newline = 67,
     Section = 68,
-    Error = 69
+    Error = 69,
+    Directive = 70
 }
 export interface SpannedToken {
     token: Token;

package/dist-lib/numbl-core/native/lapack-bridge.d.ts

@@ -18,7 +18,7 @@
  * Expected native addon version. Bump this whenever the C++ addon API changes
  * (must match ADDON_VERSION in numbl_addon.cpp).
  */
-export declare const NATIVE_ADDON_EXPECTED_VERSION = 3;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 8;
 export interface LapackBridge {
     /** Returns the native addon's version number. */
     addonVersion?(): number;
@@ -439,6 +439,44 @@ export interface LapackBridge {
         re: Float64Array;
         im?: Float64Array;
     };
+    /** Real binary elemwise: out[i] = a[i] OP b[i]. op codes per OpRealBin. */
+    tensorOpRealBinary?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    /** Real scalar-tensor binary elemwise. */
+    tensorOpRealScalarBinary?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Complex binary elemwise (split storage). aIm/bIm may be null. */
+    tensorOpComplexBinary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    /** Complex scalar-tensor binary elemwise. arrIm may be null. */
+    tensorOpComplexScalarBinary?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    /** Real unary elemwise: out[i] = OP(a[i]). op codes per OpUnary. */
+    tensorOpRealUnary?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    /** Complex unary elemwise (split storage). aIm may be null. ABS unsupported. */
+    tensorOpComplexUnary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    /** Complex absolute value (real-valued output). aIm may be null. */
+    tensorOpComplexAbs?(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    /** Real comparison: out[i] = (a[i] OP b[i]) ? 1 : 0. */
+    tensorOpRealComparison?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    /** Real scalar-tensor comparison. */
+    tensorOpRealScalarComparison?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Complex comparison. EQ/NE use both parts; LT/LE/GT/GE use real parts. */
+    tensorOpComplexComparison?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    /** Complex scalar-tensor comparison. */
+    tensorOpComplexScalarComparison?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Flat real reduction (output is a 1-element Float64Array). */
+    tensorOpRealFlatReduce?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    /** Flat complex reduction.  outIm may be null for ANY/ALL. */
+    tensorOpComplexFlatReduce?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    /**
+     * Real Bessel tensor op: out[i] = besselX(nu, z[i]).
+     * op codes per OpBessel. scale: 0 unscaled, 1 scaled.
+     */
+    tensorOpBesselReal?(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    /**
+     * Hankel function tensor op (complex output, real input).
+     * kKind: 1 → J + i*Y; 2 → J - i*Y.
+     */
+    tensorOpBesselH?(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+    /** Dump op-code enum values as a stable string (drift detection). */
+    tensorOpDumpCodes?(): string;
 }
 export declare function setLapackBridge(bridge: LapackBridge): void;
 export declare function getLapackBridge(): LapackBridge | null;

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.3.0";