perf: avoid slow exponentiation and repeated element reads

benchmark/all.js

@@ -0,0 +1,84 @@
+/*
+ * Benchmarks every distance and similarity function so their relative cost can
+ * be compared. Use beforeAfter.js instead to compare two implementations of the
+ * same function.
+ *
+ * Run with: node benchmark/all.js  (or: bun benchmark/all.js)
+ */
+import Benchmark from 'benchmark';
+
+import { distance, similarity } from '../src/index.ts';
+
+const LENGTH = 10000;
+
+function makeVector(seed) {
+  const vector = new Float64Array(LENGTH);
+  let state = seed;
+  for (let i = 0; i < LENGTH; i++) {
+    state = (state * 1103515245 + 12345) % 2147483648;
+    vector[i] = 0.1 + (state / 2147483648) * 2;
+  }
+  return vector;
+}
+
+const a = makeVector(42);
+const b = makeVector(1337);
+
+const entries = [];
+for (const [namespace, functions] of [
+  ['distance', distance],
+  ['similarity', similarity],
+]) {
+  for (const [name, callback] of Object.entries(functions)) {
+    if (typeof callback !== 'function') continue;
+    if (name === 'minkowski') {
+      for (const p of [1, 2, 3]) {
+        entries.push([
+          `${namespace}.${name}(p=${p})`,
+          (x, y) => callback(x, y, p),
+        ]);
+      }
+      continue;
+    }
+    entries.push([`${namespace}.${name}`, callback]);
+  }
+}
+
+function log(message) {
+  // eslint-disable-next-line no-console -- benchmark output
+  console.log(message);
+}
+
+const results = [];
+const suite = new Benchmark.Suite();
+for (const [name, callback] of entries) {
+  suite.add(name, () => callback(a, b), { minSamples: 30 });
+}
+
+suite
+  .on('cycle', (event) => {
+    const { name, hz, stats } = event.target;
+    results.push({
+      name,
+      nanoseconds: 1e9 / hz,
+      rme: stats.rme,
+      samples: stats.sample.length,
+    });
+  })
+  .on('complete', () => {
+    results.sort((first, second) => second.nanoseconds - first.nanoseconds);
+    log(`\nn = ${LENGTH}, sorted slowest first\n`);
+    log(
+      `${'function'.padEnd(32)}${'per call'.padStart(12)}${'per element'.padStart(14)}${'error'.padStart(9)}   result`,
+    );
+    const values = new Map(entries.map(([name, callback]) => [name, callback]));
+    for (const { name, nanoseconds, rme } of results) {
+      // A wide confidence interval means the engine kept re-tiering this one;
+      // treat the number as indicative only.
+      const flag = rme > 10 ? ' (!)' : '';
+      log(
+        `${name.padEnd(32)}${`${(nanoseconds / 1000).toFixed(1)} µs`.padStart(12)}${`${(nanoseconds / LENGTH).toFixed(2)} ns`.padStart(14)}${`±${rme.toFixed(1)}%${flag}`.padStart(13)}   ${values.get(name)(a, b)}`,
+      );
+    }
+  })
+  .run({ async: false });

benchmark/arrayKinds.js

@@ -0,0 +1,105 @@
+/*
+ * Cost of `(ai * bi) / (ai + bi)` depending on the element representation.
+ * One kind per process, so the loads stay monomorphic.
+ *
+ * `cached` copies `x[i]` into a local, `direct` reads it on every use.
+ *
+ * Run with: node benchmark/arrayKinds.js <array|typed|mixed> <cached|direct>
+ */
+import { argv } from 'node:process';
+
+const LENGTH = 10000;
+const WARMUP_MS = 1000;
+const TARGET_MS = 2000; // keep at 1000 or more, shorter runs are too noisy
+
+const kind = argv[2] ?? 'typed';
+const reads = argv[3] ?? 'cached';
+
+function fill(target) {
+  let state = 42;
+  for (let i = 0; i < target.length; i++) {
+    state = (state * 1103515245 + 12345) % 2147483648;
+    target[i] = 0.1 + (state / 2147483648) * 2;
+  }
+  return target;
+}
+
+function plainVector() {
+  return fill(Array.from({ length: LENGTH }, () => 0));
+}
+
+function typedVector() {
+  return fill(new Float64Array(LENGTH));
+}
+
+let a;
+let b;
+if (kind === 'array') {
+  a = plainVector();
+  b = plainVector();
+} else if (kind === 'typed') {
+  a = typedVector();
+  b = typedVector();
+} else if (kind === 'mixed') {
+  a = typedVector();
+  b = plainVector();
+} else {
+  throw new Error(`unknown kind: ${kind}`);
+}
+
+function cachedKernel(x, y) {
+  let sum = 0;
+  for (let i = 0; i < x.length; i++) {
+    const xi = x[i];
+    const yi = y[i];
+    sum += (xi * yi) / (xi + yi);
+  }
+  return sum;
+}
+
+function directKernel(x, y) {
+  let sum = 0;
+  for (let i = 0; i < x.length; i++) {
+    sum += (x[i] * y[i]) / (x[i] + y[i]);
+  }
+  return sum;
+}
+
+const kernel = reads === 'cached' ? cachedKernel : directKernel;
+
+let sink = 0;
+// the arguments are swapped after each call, so `mixed` really sees both orders
+let x = a;
+let y = b;
+
+let start = performance.now();
+while (performance.now() - start < WARMUP_MS) {
+  sink += kernel(x, y);
+  [x, y] = [y, x];
+}
+
+let rounds = 0;
+let elapsed = 0;
+start = performance.now();
+while (elapsed < TARGET_MS) {
+  sink += kernel(x, y);
+  [x, y] = [y, x];
+  rounds++;
+  elapsed = performance.now() - start;
+}
+
+// keeps the loop from being dropped as dead code
+if (!Number.isFinite(sink)) throw new Error('kernel diverged');
+
+const operationsPerSecond = (rounds * LENGTH * 1000) / elapsed;
+// eslint-disable-next-line no-console -- benchmark output
+console.log(
+  [
+    kind,
+    reads,
+    operationsPerSecond.toFixed(0),
+    LENGTH,
+    kernel(a, b).toFixed(10),
+    kernel(b, a).toFixed(10),
+  ].join('\t'),
+);

benchmark/arrayKinds.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Runs every element representation against both read styles, one process each,
+# then prints a summary table.
+set -euo pipefail
+
+directory="$(dirname "$0")"
+measurements=""
+
+for kind in array typed mixed; do
+  for reads in cached direct; do
+    measurements="${measurements}$(node "$directory/arrayKinds.js" "$kind" "$reads")
+"
+  done
+done
+
+printf '%s' "$measurements" | awk -F'\t' '
+  {
+    speed[$1 "/" $2] = $3 / 1e6
+    length_ = $4
+    results[$5] = 1
+    results[$6] = 1
+  }
+  END {
+    printf "\n  (ai * bi) / (ai + bi) on %d elements, arguments swapped at each call\n\n", length_
+    printf "  %-8s %14s %14s %10s\n", "kind", "cached", "direct", "ratio"
+    printf "  %-8s %14s %14s %10s\n", "--------", "--------------", "--------------", "----------"
+    split("array typed mixed", kinds, " ")
+    for (i = 1; i <= 3; i++) {
+      cached = speed[kinds[i] "/cached"]
+      direct = speed[kinds[i] "/direct"]
+      printf "  %-8s %11.0f M/s %11.0f M/s %9.2fx\n", kinds[i], cached, direct, cached / direct
+    }
+    distinct = 0
+    for (result in results) { distinct++; sample = result }
+    if (distinct == 1) {
+      printf "\n  all results identical: %s\n\n", sample
+    } else {
+      printf "\n  WARNING: %d different results\n\n", distinct
+    }
+  }
+'