usearch 2.21.3 → 2.25.0

package/numkong/probes/probe.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * NumKong ISA probe script for Node.js / node-gyp builds.
+ *
+ * Try-compiles each probe .c file from probes/ to determine which ISA
+ * extensions the current compiler supports. Writes results to
+ * build/nk_probes.h as #define NK_TARGET_FOO 1/0.
+ *
+ * Usage: node scripts/probe_isa.js
+ * Called automatically via package.json "preinstall" hook.
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const cc = process.env.CC || (process.platform === "win32" ? "cl.exe" : "cc");
+const isWin = process.platform === "win32";
+
+/** Try to compile a probe file. Returns true if compilation succeeds. */
+function probeIsa(probeFile, flags) {
+    const tmpObj = path.join(
+        os.tmpdir(),
+        `nk_probe_${path.basename(probeFile, ".c")}${isWin ? ".obj" : ".o"}`,
+    );
+    try {
+        const cmd = isWin
+            ? `"${cc}" /c ${flags.join(" ")} "${probeFile}" /Fo"${tmpObj}" /nologo`
+            : `"${cc}" -c ${flags.join(" ")} "${probeFile}" -o "${tmpObj}" 2>/dev/null`;
+        execSync(cmd, { stdio: "pipe", timeout: 30000 });
+        return true;
+    } catch {
+        return false;
+    } finally {
+        try {
+            fs.unlinkSync(tmpObj);
+        } catch { }
+    }
+}
+
+// Probe table: [define, probeFile, gccFlags, msvcFlags]
+// x86 probes: GCC flags are minimal — each implies its prerequisites.
+// E.g., -mavx512vnni implies -mavx512f; -mavxvnni implies -mavx2.
+const PROBES = [
+    // x86
+    ["NK_TARGET_HASWELL", "probes/x86_haswell.c", ["-mavx2", "-mfma", "-mf16c"], ["/arch:AVX2"]],
+    ["NK_TARGET_SKYLAKE", "probes/x86_skylake.c", ["-mavx512f", "-mavx512bw", "-mavx512dq", "-mavx512vl"], ["/arch:AVX512"]],
+    ["NK_TARGET_ICELAKE", "probes/x86_icelake.c", ["-mavx512vnni", "-mavx512vl"], ["/arch:AVX512"]],
+    ["NK_TARGET_GENOA", "probes/x86_genoa.c", ["-mavx512bf16", "-mavx512vl"], ["/arch:AVX512"]],
+    ["NK_TARGET_SAPPHIRE", "probes/x86_sapphire.c", ["-mavx512fp16", "-mavx512vl"], ["/arch:AVX512"]],
+    ["NK_TARGET_SAPPHIREAMX", "probes/x86_sapphireamx.c", ["-mamx-tile", "-mamx-int8"], ["/arch:AVX512"]],
+    ["NK_TARGET_GRANITEAMX", "probes/x86_graniteamx.c", ["-mamx-tile", "-mamx-fp16"], ["/arch:AVX512"]],
+    ["NK_TARGET_DIAMOND", "probes/x86_diamond.c", ["-mavx10.2-512"], ["/arch:AVX10.2"]],
+    ["NK_TARGET_TURIN", "probes/x86_turin.c", ["-mavx512vp2intersect"], ["/arch:AVX512"]],
+    ["NK_TARGET_ALDER", "probes/x86_alder.c", ["-mavxvnni"], ["/arch:AVX2"]],
+    ["NK_TARGET_SIERRA", "probes/x86_sierra.c", ["-mavxvnniint8"], ["/arch:AVX2"]],
+    // ARM NEON base probes — msvc_flags are empty because MSVC does not define
+    // __ARM_FEATURE_* macros via /arch: flags. For MSVC header-only builds,
+    // types.h infers features from __ARM_ARCH level instead.
+    ["NK_TARGET_NEON", "probes/arm_neon.c", ["-march=armv8-a+simd"], []], // FEAT_AdvSIMD
+    ["NK_TARGET_NEONHALF", "probes/arm_neon_half.c", ["-march=armv8.2-a+simd+fp16"], ["/arch:armv8.2"]], // FEAT_FP16
+    ["NK_TARGET_NEONSDOT", "probes/arm_neon_sdot.c", ["-march=armv8.2-a+dotprod"], ["/arch:armv8.4"]], // FEAT_DotProd
+    ["NK_TARGET_NEONBFDOT", "probes/arm_neon_bfdot.c", ["-march=armv8.6-a+simd+bf16"], ["/arch:armv8.6"]], // FEAT_BF16
+    ["NK_TARGET_NEONFHM", "probes/arm_neon_fhm.c", ["-march=armv8.2-a+simd+fp16+fp16fml"], ["/arch:armv8.4"]], // FEAT_FHM
+    // ARM SVE/SME
+    ["NK_TARGET_SVE", "probes/arm_sve.c", ["-march=armv8.2-a+sve"], []],
+    ["NK_TARGET_SVEHALF", "probes/arm_sve_half.c", ["-march=armv8.2-a+sve+fp16"], []],
+    ["NK_TARGET_SVEBFDOT", "probes/arm_sve_bfdot.c", ["-march=armv8.2-a+sve+bf16"], []],
+    ["NK_TARGET_SVESDOT", "probes/arm_sve_sdot.c", ["-march=armv8.2-a+sve+dotprod"], []],
+    ["NK_TARGET_SVE2", "probes/arm_sve2.c", ["-march=armv8.2-a+sve2"], []],
+    ["NK_TARGET_SVE2P1", "probes/arm_sve2p1.c", ["-march=armv8.2-a+sve2p1"], []],
+    ["NK_TARGET_NEONFP8", "probes/arm_neonfp8.c", ["-march=armv8-a+simd+fp8dot4"], []],
+    ["NK_TARGET_SME", "probes/arm_sme.c", ["-march=armv8-a+sme"], []],
+    ["NK_TARGET_SME2", "probes/arm_sme2.c", ["-march=armv8-a+sme2"], []],
+    ["NK_TARGET_SME2P1", "probes/arm_sme2p1.c", ["-march=armv8-a+sme2p1"], []],
+    ["NK_TARGET_SMEF64", "probes/arm_sme_f64.c", ["-march=armv8-a+sme+sme-f64f64"], []],
+    ["NK_TARGET_SMEHALF", "probes/arm_sme_half.c", ["-march=armv8-a+sme+sme-f16f16"], []],
+    ["NK_TARGET_SMEBF16", "probes/arm_sme_bf16.c", ["-march=armv8-a+sme2+sme-b16b16"], []],
+    ["NK_TARGET_SMEBI32", "probes/arm_sme_bi32.c", ["-march=armv8-a+sme2"], []],
+    ["NK_TARGET_SMELUT2", "probes/arm_sme_lut2.c", ["-march=armv8-a+sme2+lut"], []],
+    ["NK_TARGET_SMEFA64", "probes/arm_sme_fa64.c", ["-march=armv8-a+sme+sme-fa64"], []],
+    // RISC-V
+    ["NK_TARGET_RVV", "probes/riscv_rvv.c", ["-march=rv64gcv"], []],
+    ["NK_TARGET_RVVHALF", "probes/riscv_rvv_half.c", ["-march=rv64gcv_zvfh"], []],
+    ["NK_TARGET_RVVBF16", "probes/riscv_rvv_bf16.c", ["-march=rv64gcv_zvfbfwma"], []],
+    ["NK_TARGET_RVVBB", "probes/riscv_rvv_bb.c", ["-march=rv64gcv_zvbb"], []],
+    // LoongArch
+    ["NK_TARGET_LOONGSONASX", "probes/loongarch_lasx.c", ["-mlasx"], []],
+    // Power
+    ["NK_TARGET_POWERVSX", "probes/power_vsx.c", ["-mcpu=power9", "-mvsx"], []],
+    // WASM
+    ["NK_TARGET_V128RELAXED", "probes/wasm_v128relaxed.c", ["-mrelaxed-simd"], []],
+];
+
+function main() {
+    const pkgRoot = path.join(__dirname, "..");
+    fs.mkdirSync(pkgRoot, { recursive: true });
+
+    const arch = process.arch; // 'x64', 'arm64', etc.
+    const lines = [
+        "/* Auto-generated by scripts/probe_isa.js — do not edit */",
+        `/* Compiler: ${cc}, Platform: ${process.platform}, Arch: ${arch} */`,
+        "",
+    ];
+
+    let enabled = 0;
+    for (const [define, probeFile, gccFlags, msvcFlags] of PROBES) {
+        const flags = isWin ? msvcFlags : gccFlags;
+        const supported = probeIsa(path.join(pkgRoot, probeFile), flags);
+        lines.push(`#define ${define} ${supported ? 1 : 0}`);
+        if (supported) {
+            enabled++;
+            console.log(`[NumKong] Probe ${define}: supported`);
+        }
+    }
+
+    lines.push("");
+    const header = lines.join("\n");
+    const outPath = path.join(pkgRoot, "nk_probes.h");
+    fs.writeFileSync(outPath, header);
+    console.log(
+        `[NumKong] Wrote ${outPath} (${enabled} ISAs enabled out of ${PROBES.length})`,
+    );
+}
+
+main();

package/numkong/probes/riscv_rvv.c

@@ -0,0 +1,14 @@
+/* NumKong ISA probe: RVV 1.0 (RISC-V Vector Extension) */
+#if !defined(__riscv_v)
+#error "Feature not available"
+#endif
+#include <riscv_vector.h>
+int main(void) {
+    size_t vl = __riscv_vsetvl_e32m1(4);
+    vfloat32m1_t a = __riscv_vfmv_v_f_f32m1(1.0f, vl);
+    vfloat32m1_t b = __riscv_vfmv_v_f_f32m1(2.0f, vl);
+    vfloat32m1_t c = __riscv_vfadd_vv_f32m1(a, b, vl);
+    vfloat32m1_t sum = __riscv_vfredusum_vs_f32m1_f32m1(c, __riscv_vfmv_v_f_f32m1(0.0f, vl), vl);
+    float result = __riscv_vfmv_f_s_f32m1_f32(sum);
+    return result > 0.0f ? 0 : 1;
+}

package/numkong/probes/riscv_rvv_bb.c

@@ -0,0 +1,15 @@
+/* NumKong ISA probe: RVV Zvbb (basic bit-manipulation) */
+#if !defined(__riscv_zvbb)
+#error "Feature not available"
+#endif
+#include <riscv_vector.h>
+int main(void) {
+    size_t vl = __riscv_vsetvl_e8m1(4);
+    vuint8m1_t a = __riscv_vmv_v_x_u8m1(0xFF, vl);
+    /* vcpop.v — per-element popcount, the key Zvbb instruction */
+    vuint8m1_t popcnt = __riscv_vcpop_v_u8m1(a, vl);
+    vuint8m1_t sum = __riscv_vredsum_vs_u8m1_u8m1(popcnt, __riscv_vmv_v_x_u8m1(0, 1), vl);
+    unsigned char result = __riscv_vmv_x_s_u8m1_u8(sum);
+    /* Each lane is 0xFF → popcount 8, sum of 4 lanes = 32 */
+    return result == 32 ? 0 : 1;
+}

package/numkong/probes/riscv_rvv_bf16.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: RVV Zvfbfwma (BF16 widening FMA) */
+#if !defined(__riscv_zvfbfwma)
+#error "Feature not available"
+#endif
+#include <riscv_vector.h>
+int main(void) {
+    size_t vl = __riscv_vsetvl_e16m1(4);
+    vuint16m1_t raw = __riscv_vmv_v_x_u16m1(0x3F80, vl); /* bf16 1.0 */
+    vbfloat16m1_t a = __riscv_vreinterpret_v_u16m1_bf16m1(raw);
+    size_t vl32 = __riscv_vsetvl_e32m2(4);
+    vfloat32m2_t acc = __riscv_vfmv_v_f_f32m2(0.0f, vl32);
+    acc = __riscv_vfwmaccbf16_vv_f32m2(acc, a, a, vl);
+    vfloat32m1_t sum = __riscv_vfredusum_vs_f32m2_f32m1(acc, __riscv_vfmv_v_f_f32m1(0.0f, __riscv_vsetvl_e32m1(1)),
+                                                        vl32);
+    float result = __riscv_vfmv_f_s_f32m1_f32(sum);
+    return result > 0.0f ? 0 : 1;
+}

package/numkong/probes/riscv_rvv_half.c

@@ -0,0 +1,14 @@
+/* NumKong ISA probe: RVV Zvfh (half-precision vector) */
+#if !defined(__riscv_zvfh)
+#error "Feature not available"
+#endif
+#include <riscv_vector.h>
+int main(void) {
+    size_t vl = __riscv_vsetvl_e16m1(4);
+    vfloat16m1_t a = __riscv_vfmv_v_f_f16m1((_Float16)1.0f, vl);
+    vfloat32m2_t wide = __riscv_vfwcvt_f_f_v_f32m2(a, vl);
+    vfloat32m1_t sum = __riscv_vfredusum_vs_f32m2_f32m1(wide, __riscv_vfmv_v_f_f32m1(0.0f, __riscv_vsetvl_e32m1(1)),
+                                                        vl);
+    float result = __riscv_vfmv_f_s_f32m1_f32(sum);
+    return result > 0.0f ? 0 : 1;
+}

package/numkong/probes/wasm_v128relaxed.c

@@ -0,0 +1,11 @@
+/* NumKong ISA probe: WASM Relaxed SIMD (v128) */
+#if !defined(__wasm_relaxed_simd__)
+#error "WASM Relaxed SIMD not available"
+#endif
+#include <wasm_simd128.h>
+int main(void) {
+    v128_t a = wasm_f32x4_splat(1.0f);
+    v128_t b = wasm_f32x4_splat(2.0f);
+    v128_t c = wasm_f32x4_relaxed_madd(a, b, a);
+    return wasm_f32x4_extract_lane(c, 0) > 0.0f ? 0 : 1;
+}

package/numkong/probes/x86_alder.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Alder Lake (AVX-VNNI 256-bit) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVXVNNI__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int two = 2;
+    __m256i acc = _mm256_setzero_si256();
+    __m256i a = _mm256_set1_epi8((char)two);
+    __m256i b = _mm256_set1_epi8((char)(two + 1));
+    acc = _mm256_dpbusd_avx_epi32(acc, a, b);
+    return _mm256_extract_epi32(acc, 0) == 24 ? 0 : 1;
+}

package/numkong/probes/x86_diamond.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Diamond Rapids (AVX10.2) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512FP16__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int one = 1;
+    __m256i acc = _mm256_setzero_si256();
+    __m256i a = _mm256_set1_epi8((char)one);
+    __m256i b = _mm256_set1_epi8((char)one);
+    acc = _mm256_dpbe4ss_epi32(acc, a, b);
+    return _mm256_extract_epi32(acc, 0) != 0 ? 0 : 1;
+}

package/numkong/probes/x86_genoa.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Genoa (AVX-512F/BW/DQ/VL + BF16) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512BF16__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile float one = 1.0f;
+    __m512 f = _mm512_set1_ps(one);
+    __m256bh a = _mm512_cvtneps_pbh(f);
+    __m512bh wide = (__m512bh)_mm512_castsi512_ps(_mm512_inserti64x4(_mm512_setzero_si512(), (__m256i)a, 0));
+    __m512 r = _mm512_dpbf16_ps(_mm512_setzero_ps(), wide, wide);
+    return _mm512_reduce_add_ps(r) >= 0.0f ? 0 : 1;
+}

package/numkong/probes/x86_graniteamx.c

@@ -0,0 +1,19 @@
+/* NumKong ISA probe: Granite Rapids AMX (AMX-TILE + AMX-FP16) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if defined(__FreeBSD__)
+#error "AMX not supported on FreeBSD"
+#endif
+
+#if !defined(__AMX_FP16__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+#include <amxfp16intrin.h>
+int main(void) {
+    volatile int zero = 0;
+    _tile_release();
+    return zero;
+}

package/numkong/probes/x86_haswell.c

@@ -0,0 +1,11 @@
+/* NumKong ISA probe: Haswell (AVX2 + FMA + F16C) */
+#if !defined(__AVX2__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int one = 1;
+    __m256i a = _mm256_set1_epi32(one);
+    __m256i b = _mm256_add_epi32(a, a);
+    return _mm256_extract_epi32(b, 0) == 2 ? 0 : 1;
+}

package/numkong/probes/x86_icelake.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Ice Lake (AVX-512F/BW/DQ/VL + VNNI + VBMI + VPOPCNTDQ) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512VNNI__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int one = 1;
+    __m512i acc = _mm512_setzero_si512();
+    __m512i a = _mm512_set1_epi8((char)one);
+    __m512i b = _mm512_set1_epi8((char)one);
+    acc = _mm512_dpbusd_epi32(acc, a, b);
+    return (int)_mm512_reduce_add_epi32(acc) == 64 ? 0 : 1;
+}

package/numkong/probes/x86_sapphire.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: Sapphire Rapids (AVX-512F/BW/DQ/VL + FP16) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512FP16__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile float one = 1.0f;
+    __m512h a = _mm512_set1_ph((_Float16)one);
+    __m512h b = _mm512_set1_ph((_Float16)(one + one));
+    __m512h c = _mm512_fmadd_ph(a, b, a);
+    return (int)_mm_extract_epi16(_mm256_castsi256_si128(_mm512_castsi512_si256((__m512i)c)), 0) != 0 ? 0 : 1;
+}

package/numkong/probes/x86_sapphireamx.c

@@ -0,0 +1,18 @@
+/* NumKong ISA probe: Sapphire Rapids AMX (AMX-TILE + AMX-INT8) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if defined(__FreeBSD__)
+#error "AMX not supported on FreeBSD"
+#endif
+
+#if !defined(__AMX_INT8__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int zero = 0;
+    _tile_release();
+    return zero;
+}

package/numkong/probes/x86_sierra.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Sierra Forest (AVXVNNIINT8) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVXVNNIINT8__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int two = 2;
+    __m256i acc = _mm256_setzero_si256();
+    __m256i a = _mm256_set1_epi8((char)two);
+    __m256i b = _mm256_set1_epi8((char)(two + 1));
+    acc = _mm256_dpbssd_epi32(acc, a, b);
+    return _mm256_extract_epi32(acc, 0) == 24 ? 0 : 1;
+}

package/numkong/probes/x86_skylake.c

@@ -0,0 +1,15 @@
+/* NumKong ISA probe: Skylake (AVX-512F/BW/DQ/VL) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512F__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int one = 1;
+    __m512i a = _mm512_set1_epi32(one);
+    __m512i b = _mm512_add_epi32(a, a);
+    return (int)_mm512_reduce_add_epi32(b) == 32 ? 0 : 1;
+}

package/numkong/probes/x86_turin.c

@@ -0,0 +1,17 @@
+/* NumKong ISA probe: Turin (AVX-512F + VP2INTERSECT) */
+#if defined(__APPLE__)
+#error "AVX-512 not available on macOS"
+#endif
+
+#if !defined(__AVX512VP2INTERSECT__)
+#error "Feature not available"
+#endif
+#include <immintrin.h>
+int main(void) {
+    volatile int val = 42;
+    __m512i a = _mm512_set1_epi32(val);
+    __m512i b = _mm512_set1_epi32(val);
+    __mmask16 k0, k1;
+    _mm512_2intersect_epi32(a, b, &k0, &k1);
+    return k0 != 0 ? 0 : 1;
+}