jvector Benchmarks

JMH benchmark harness for jvector vector distance kernels. Measures single-pair and bulk scoring throughput across dimensions and access patterns.

Benchmarks

Benchmark	Description
DotProductBenchmark	Float32 dot product (single pair), dims 128–3072
SquareDistanceBenchmark	Float32 squared L2 distance (single pair), dims 128–3072
CosineBenchmark	Float32 cosine similarity, dims 128–1536
DotProductBulkBenchmark	Loop-of-singles scoring at 1024d with sequential and random access, N = 32 / 625 / 32500

The bulk benchmark uses dataset sizes chosen to exceed L1, L2, and L3 cache respectively for 1024-dimensional float32 vectors.

Prerequisites

• JDK 25 (Oracle or Adoptium EA)

Quick start

# Run unit tests
./gradlew test

# Verify jvector implementation path
./gradlew diagnose

# Smoke test — dot product at 1024 dims, minimal iterations
./gradlew jmh -Pbench=DotProduct -Pdims=1024 -Pforks=1 -Pwi=1 -Piters=1

# Full dot product sweep (all dimensions, 3 forks × 5 iterations)
./gradlew jmh -Pbench=DotProduct

# Full bulk scoring
./gradlew jmh -Pbench=DotProductBulk

# Everything
./gradlew jmh

Results are written to build/results/jmh-results.json.

See INSTRUCTIONS.md for detailed run instructions, instance-specific notes, and troubleshooting.