numkong 7.0.0

package/javascript/dist/esm/numkong.d.ts

@@ -0,0 +1,343 @@
+/**
+ * @fileoverview NumKong - Portable mixed-precision BLAS-like vector math library
+ *
+ * NumKong provides SIMD-accelerated distance metrics and vector operations for
+ * x86, ARM, RISC-V, and WASM platforms. The library automatically detects and uses
+ * the best available SIMD instruction set at runtime.
+ *
+ * @module numkong
+ * @author Ash Vardanian
+ *
+ * @example
+ * ```typescript
+ * import { dot, euclidean, Float16Array } from 'numkong';
+ *
+ * // Auto-detected types
+ * const a = new Float32Array([1, 2, 3]);
+ * const b = new Float32Array([4, 5, 6]);
+ * dot(a, b);        // 32
+ * euclidean(a, b);  // 5.196...
+ *
+ * // Custom types with explicit dtype
+ * const c = new Float16Array([1, 2, 3]);
+ * const d = new Float16Array([4, 5, 6]);
+ * dot(c, d, DType.F16); // 32
+ * ```
+ */
+import { Float16Array, BFloat16Array, E4M3Array, E5M2Array, BinaryArray, TensorBase, VectorBase, VectorView, Vector, MatrixBase, Matrix, PackedMatrix, DType, outputDtype } from "./types.js";
+/**
+ * CPU capability bit masks in chronological order (by first commercial silicon).
+ * Use these with getCapabilities() to check for specific SIMD support.
+ */
+export declare const Capability: {
+    readonly SERIAL: bigint;
+    readonly NEON: bigint;
+    readonly HASWELL: bigint;
+    readonly SKYLAKE: bigint;
+    readonly NEONHALF: bigint;
+    readonly NEONSDOT: bigint;
+    readonly NEONFHM: bigint;
+    readonly ICELAKE: bigint;
+    readonly GENOA: bigint;
+    readonly NEONBFDOT: bigint;
+    readonly SVE: bigint;
+    readonly SVEHALF: bigint;
+    readonly SVESDOT: bigint;
+    readonly SIERRA: bigint;
+    readonly SVEBFDOT: bigint;
+    readonly SVE2: bigint;
+    readonly V128RELAXED: bigint;
+    readonly SAPPHIRE: bigint;
+    readonly SAPPHIREAMX: bigint;
+    readonly RVV: bigint;
+    readonly RVVHALF: bigint;
+    readonly RVVBF16: bigint;
+    readonly GRANITEAMX: bigint;
+    readonly TURIN: bigint;
+    readonly SME: bigint;
+    readonly SME2: bigint;
+    readonly SMEF64: bigint;
+    readonly SMEFA64: bigint;
+    readonly SVE2P1: bigint;
+    readonly SME2P1: bigint;
+    readonly SMEHALF: bigint;
+    readonly SMEBF16: bigint;
+    readonly SMELUT2: bigint;
+    readonly RVVBB: bigint;
+};
+export { Float16Array, BFloat16Array, E4M3Array, E5M2Array, BinaryArray, TensorBase, VectorBase, VectorView, Vector, MatrixBase, Matrix, PackedMatrix, outputDtype };
+/** Convert a single FP16 value (as uint16 bits) to FP32 */
+export declare const castF16ToF32: any;
+/** Convert a single FP32 value to FP16 (returns uint16 bits) */
+export declare const castF32ToF16: any;
+/** Convert a single BF16 value (as uint16 bits) to FP32 */
+export declare const castBF16ToF32: any;
+/** Convert a single FP32 value to BF16 (returns uint16 bits) */
+export declare const castF32ToBF16: any;
+/** Convert a single E4M3 value (as uint8 bits) to FP32 */
+export declare const castE4M3ToF32: any;
+/** Convert a single FP32 value to E4M3 (returns uint8 bits) */
+export declare const castF32ToE4M3: any;
+/** Convert a single E5M2 value (as uint8 bits) to FP32 */
+export declare const castE5M2ToF32: any;
+/** Convert a single FP32 value to E5M2 (returns uint8 bits) */
+export declare const castF32ToE5M2: any;
+/** Bulk conversion between different numeric types (modifies destination array in-place) */
+export declare const cast: any;
+export { DType };
+/**
+ * Numeric arrays supported by distance metrics with auto-detected dtype.
+ *
+ * These standard TypedArrays are auto-detected by the N-API binding.
+ */
+export type NumericArray = Float64Array | Float32Array | Int8Array | Uint8Array;
+/**
+ * Extended array types supported by distance metrics with explicit dtype parameter.
+ *
+ * Includes Uint16Array (backing type for Float16Array and BFloat16Array) in addition
+ * to the auto-detected types. Pass a dtype string as the third argument to distance
+ * functions when using custom types.
+ */
+export type DistanceArray = Float64Array | Float32Array | Int8Array | Uint8Array | Uint16Array;
+/**
+ * Union type for all array types (including custom types for conversions)
+ */
+export type NumKongArray = Float64Array | Float32Array | Float16Array | BFloat16Array | E4M3Array | E5M2Array | Int8Array | Uint8Array | BinaryArray;
+/**
+ * Returns the runtime-detected SIMD capabilities as a bitmask.
+ *
+ * The bitmask includes flags for various SIMD instruction sets like AVX2, AVX-512,
+ * ARM NEON, ARM SVE, ARM SME, RISC-V Vector, and WASM SIMD extensions.
+ * Use with Capability constants to check for specific instruction sets.
+ *
+ * @returns {bigint} Bitmask of capability flags (use with Capability constants)
+ *
+ * @example
+ * ```ts
+ * import { getCapabilities, Capability } from 'numkong';
+ *
+ * const caps = getCapabilities();
+ * console.log(`Capabilities: 0x${caps.toString(16)}`);
+ *
+ * // Check for specific SIMD support
+ * if (caps & Capability.HASWELL) {
+ *   console.log('AVX2 available');
+ * }
+ * ```
+ */
+export declare const getCapabilities: () => bigint;
+/**
+ * Checks if a specific SIMD capability is available at runtime.
+ *
+ * This is a convenience wrapper around getCapabilities() that tests for a single capability.
+ *
+ * @param {bigint} cap - Capability flag to check (from Capability constants)
+ * @returns {boolean} True if the capability is available, false otherwise
+ *
+ * @example
+ * ```ts
+ * import { hasCapability, Capability } from 'numkong';
+ *
+ * if (hasCapability(Capability.HASWELL)) {
+ *   console.log('Intel AVX2 (Haswell) available');
+ * }
+ * if (hasCapability(Capability.NEON)) {
+ *   console.log('ARM NEON available');
+ * }
+ * if (hasCapability(Capability.V128RELAXED)) {
+ *   console.log('WASM Relaxed SIMD available');
+ * }
+ * ```
+ */
+export declare const hasCapability: (cap: bigint) => boolean;
+/**
+ * Computes the squared Euclidean distance between two vectors.
+ * @param a - The first vector.
+ * @param b - The second vector (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16', 'e4m3').
+ * @returns {number} The squared Euclidean distance between vectors a and b.
+ */
+export declare function sqeuclidean(a: NumericArray, b: NumericArray): number;
+export declare function sqeuclidean(a: DistanceArray, b: DistanceArray, dtype: DType): number;
+export declare function sqeuclidean(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the Euclidean distance between two vectors.
+ * @param a - The first vector.
+ * @param b - The second vector (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16', 'e4m3').
+ * @returns {number} The Euclidean distance between vectors a and b.
+ */
+export declare function euclidean(a: NumericArray, b: NumericArray): number;
+export declare function euclidean(a: DistanceArray, b: DistanceArray, dtype: DType): number;
+export declare function euclidean(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the angular distance between two vectors.
+ * @param a - The first vector.
+ * @param b - The second vector (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16', 'e4m3').
+ * @returns {number} The angular distance between vectors a and b.
+ */
+export declare function angular(a: NumericArray, b: NumericArray): number;
+export declare function angular(a: DistanceArray, b: DistanceArray, dtype: DType): number;
+export declare function angular(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the inner product of two vectors (same as dot product).
+ * @param a - The first vector.
+ * @param b - The second vector (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16', 'e4m3').
+ * @returns {number} The inner product of vectors a and b.
+ */
+export declare function inner(a: NumericArray, b: NumericArray): number;
+export declare function inner(a: DistanceArray, b: DistanceArray, dtype: DType): number;
+export declare function inner(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the dot product of two vectors (same as inner product).
+ * @param a - The first vector.
+ * @param b - The second vector (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16', 'e4m3').
+ * @returns {number} The dot product of vectors a and b.
+ */
+export declare function dot(a: NumericArray, b: NumericArray): number;
+export declare function dot(a: DistanceArray, b: DistanceArray, dtype: DType): number;
+export declare function dot(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the bitwise Hamming distance between two vectors.
+ *
+ * Both vectors are treated as bit-packed (u1 dtype), where each byte contains 8 bits.
+ * Use toBinary() to convert numeric arrays to bit-packed format.
+ *
+ * @param {Uint8Array | BinaryArray} a - The first bit-packed vector.
+ * @param {Uint8Array | BinaryArray} b - The second bit-packed vector.
+ * @returns {number} The Hamming distance (number of differing bits) between vectors a and b.
+ */
+export declare const hamming: (a: Uint8Array | BinaryArray | TensorBase, b: Uint8Array | BinaryArray | TensorBase) => number;
+/**
+ * Computes the bitwise Jaccard distance between two vectors.
+ *
+ * Both vectors are treated as bit-packed (u1 dtype), where each byte contains 8 bits.
+ * Use toBinary() to convert numeric arrays to bit-packed format.
+ *
+ * @param {Uint8Array | BinaryArray} a - The first bit-packed vector.
+ * @param {Uint8Array | BinaryArray} b - The second bit-packed vector.
+ * @returns {number} The Jaccard distance (1 - Jaccard similarity) between vectors a and b.
+ */
+export declare const jaccard: (a: Uint8Array | BinaryArray | TensorBase, b: Uint8Array | BinaryArray | TensorBase) => number;
+/**
+ * Computes the Kullback-Leibler divergence between two probability distributions.
+ *
+ * Both vectors must represent valid probability distributions (non-negative, sum to 1).
+ * Supports f64, f32 (auto-detected) and f16, bf16 (with explicit dtype).
+ *
+ * @param a - The first probability distribution.
+ * @param b - The second probability distribution (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16').
+ * @returns {number} The Kullback-Leibler divergence KL(a || b) = Σ a[i] * log(a[i] / b[i]).
+ */
+export declare function kullbackleibler(a: Float64Array | Float32Array, b: Float64Array | Float32Array): number;
+export declare function kullbackleibler(a: Float64Array | Float32Array | Uint16Array, b: Float64Array | Float32Array | Uint16Array, dtype: DType): number;
+export declare function kullbackleibler(a: TensorBase, b: TensorBase): number;
+/**
+ * Computes the Jensen-Shannon distance between two probability distributions.
+ *
+ * Both vectors must represent valid probability distributions (non-negative, sum to 1).
+ * Supports f64, f32 (auto-detected) and f16, bf16 (with explicit dtype).
+ * JSD is the square root of the symmetrized KL divergence, forming a true metric.
+ *
+ * @param a - The first probability distribution.
+ * @param b - The second probability distribution (must match the type of a).
+ * @param dtype - Optional dtype string for custom types (e.g. 'f16', 'bf16').
+ * @returns {number} The Jensen-Shannon distance d_JS(a, b) = √(0.5 × (KL(a‖m) + KL(b‖m))), where m = (a + b) / 2.
+ */
+export declare function jensenshannon(a: Float64Array | Float32Array, b: Float64Array | Float32Array): number;
+export declare function jensenshannon(a: Float64Array | Float32Array | Uint16Array, b: Float64Array | Float32Array | Uint16Array, dtype: DType): number;
+export declare function jensenshannon(a: TensorBase, b: TensorBase): number;
+/**
+ * Quantizes a numeric vector into a bit-packed binary representation.
+ *
+ * Converts each element to a single bit: 1 for positive values, 0 for non-positive values.
+ * The bits are packed into bytes (8 bits per byte) in big-endian bit order within each byte.
+ * This is the required format for hamming() and jaccard() distance functions.
+ *
+ * @param {Float32Array | Float64Array | Int8Array} vector - The vector to quantize and pack.
+ * @returns {Uint8Array} A bit-packed array where each byte contains 8 binary values.
+ *
+ * @example
+ * ```ts
+ * const vec = new Float32Array([1.5, -2.3, 0.0, 3.1, -1.0, 2.0, 0.5, -0.5]);
+ * const binary = toBinary(vec);
+ * // Result: Uint8Array([0b10010110]) = [0x96]
+ * //   bits: [1, 0, 0, 1, 0, 1, 1, 0] for elements [+, -, 0, +, -, +, +, -]
+ *
+ * // Use with Hamming distance
+ * const a = toBinary(new Float32Array([1, 2, 3]));
+ * const b = toBinary(new Float32Array([1, -2, 3]));
+ * const dist = hamming(a, b); // Counts differing bits
+ * ```
+ */
+export declare const toBinary: (vector: Float32Array | Float64Array | Int8Array) => Uint8Array;
+/**
+ * Query the packed buffer byte count for a given matrix shape and dtype.
+ */
+export declare function dotsPackedSize(width: number, depth: number, dtype: DType): number;
+/**
+ * Pack a Matrix for use with packed GEMM-like operations.
+ */
+export declare function dotsPack(matrix: Matrix): PackedMatrix;
+export declare function dotsPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function angularsPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function euclideansPacked(a: Matrix, packed: PackedMatrix, out?: Matrix): Matrix;
+export declare function dotsSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+export declare function angularsSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+export declare function euclideansSymmetric(vectors: Matrix, out?: Matrix, options?: {
+    rowStart?: number;
+    rowCount?: number;
+}): Matrix;
+declare const _default: {
+    dot: typeof dot;
+    inner: typeof inner;
+    sqeuclidean: typeof sqeuclidean;
+    euclidean: typeof euclidean;
+    angular: typeof angular;
+    hamming: (a: Uint8Array | BinaryArray | TensorBase, b: Uint8Array | BinaryArray | TensorBase) => number;
+    jaccard: (a: Uint8Array | BinaryArray | TensorBase, b: Uint8Array | BinaryArray | TensorBase) => number;
+    kullbackleibler: typeof kullbackleibler;
+    jensenshannon: typeof jensenshannon;
+    toBinary: (vector: Float32Array | Float64Array | Int8Array) => Uint8Array;
+    Float16Array: typeof Float16Array;
+    BFloat16Array: typeof BFloat16Array;
+    E4M3Array: typeof E4M3Array;
+    E5M2Array: typeof E5M2Array;
+    BinaryArray: typeof BinaryArray;
+    TensorBase: typeof TensorBase;
+    VectorBase: typeof VectorBase;
+    VectorView: typeof VectorView;
+    Vector: typeof Vector;
+    MatrixBase: typeof MatrixBase;
+    Matrix: typeof Matrix;
+    PackedMatrix: typeof PackedMatrix;
+    castF16ToF32: any;
+    castF32ToF16: any;
+    castBF16ToF32: any;
+    castF32ToBF16: any;
+    castE4M3ToF32: any;
+    castF32ToE4M3: any;
+    castE5M2ToF32: any;
+    castF32ToE5M2: any;
+    cast: any;
+    dotsPack: typeof dotsPack;
+    dotsPacked: typeof dotsPacked;
+    angularsPacked: typeof angularsPacked;
+    euclideansPacked: typeof euclideansPacked;
+    dotsSymmetric: typeof dotsSymmetric;
+    angularsSymmetric: typeof angularsSymmetric;
+    euclideansSymmetric: typeof euclideansSymmetric;
+    dotsPackedSize: typeof dotsPackedSize;
+    outputDtype: typeof outputDtype;
+};
+export default _default;