feat: vectorize CAM retrieval with NumPy and add multi-worker support

- Replace scalar hamming distance with NumPy bitwise_count for batch retrieval
- Add ThreadPoolExecutor-based multi-worker query parallelism
- Improve missing dataset error message with generation command hint
- Increase DEFAULT_MAX_QUERIES from 128 to 8192 for meaningful throughput tests

tests/test_sw_retrieval_benchmark.py

@@ -76,8 +76,10 @@ def test_run_benchmark_reports_quality_and_query_speed(tmp_path):
         timer_ns=lambda: next(timer_values),
     )
 
-    assert result["mode"] == "software-hamming"
+    assert result["mode"] == "software-numpy"
     assert result["status"] == "pass"
+    assert result["params"]["engine"] == "numpy"
+    assert result["params"]["workers"] == 1
     assert result["dataset"]["num_queries"] == 2
     assert result["params"]["num_rows"] == 3
     assert result["params"]["topk_k"] == 2
@@ -88,6 +90,59 @@ def test_run_benchmark_reports_quality_and_query_speed(tmp_path):
     assert result["performance"]["queries_per_second"] == 1_000_000.0
 
 
+def test_numpy_topk_matches_reference_with_tiebreak(tmp_path):
+    bench = load_sw_benchmark()
+    dataset_path = tmp_path / "dataset.npz"
+    np.savez_compressed(
+        dataset_path,
+        rows_words=np.array(
+            [
+                [0b11110000],
+                [0b11110000],
+                [0b11100000],
+                [0b00001111],
+            ],
+            dtype=np.uint64,
+        ),
+        row_labels=np.array([0, 0, 0, 1], dtype=np.int64),
+        queries_words=np.array([[0b11110000]], dtype=np.uint64),
+        query_labels=np.array([0], dtype=np.int64),
+    )
+    dataset = bench.load_retrieval_dataset_npz(dataset_path)
+
+    assert bench.match_topk_numpy(dataset.queries_words[0], dataset.rows_words, width=64, k=3) == [0, 1, 2]
+
+
+def test_numpy_batch_topk_vectorizes_across_queries(monkeypatch):
+    bench = load_sw_benchmark()
+    rows_words = np.array(
+        [
+            [0b11110000],
+            [0b11100000],
+            [0b00001111],
+        ],
+        dtype=np.uint64,
+    )
+    queries_words = np.array(
+        [
+            [0b11110000],
+            [0b00001111],
+        ],
+        dtype=np.uint64,
+    )
+
+    monkeypatch.setattr(
+        bench,
+        "match_topk_numpy",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("scalar path called")),
+    )
+
+    assert bench._match_topk_numpy_batch(queries_words, rows_words, width=64, k=2) == [
+        [0, 1],
+        [2, 1],
+    ]
+
+
 def test_run_benchmark_exact_match_compares_against_reference(tmp_path, monkeypatch):
     bench = load_sw_benchmark()
     dataset_path = tmp_path / "dataset.npz"
@@ -105,6 +160,35 @@ def test_run_benchmark_exact_match_compares_against_reference(tmp_path, monkeypa
     assert result["metrics"]["1"]["exact_match_rate"] == 0.0
 
 
+def test_run_benchmark_threaded_numpy_matches_single_worker(tmp_path):
+    bench = load_sw_benchmark()
+    dataset_path = tmp_path / "dataset.npz"
+    _write_dataset(dataset_path)
+
+    single = bench.run_benchmark(
+        dataset_path,
+        hash_bits=64,
+        topk_values=(1, 2),
+        run_id="single",
+        workers=1,
+        timer_ns=lambda: 0,
+    )
+    threaded = bench.run_benchmark(
+        dataset_path,
+        hash_bits=64,
+        topk_values=(1, 2),
+        run_id="threaded",
+        workers=2,
+        timer_ns=lambda: 0,
+    )
+
+    assert single["mode"] == "software-numpy"
+    assert threaded["mode"] == "software-numpy"
+    assert single["params"]["engine"] == "numpy"
+    assert threaded["params"]["workers"] == 2
+    assert threaded["metrics"] == single["metrics"]
+
+
 def test_run_benchmark_rejects_hash_bits_that_do_not_match_npz_width(tmp_path):
     bench = load_sw_benchmark()
     dataset_path = tmp_path / "dataset.npz"
@@ -114,13 +198,46 @@ def test_run_benchmark_rejects_hash_bits_that_do_not_match_npz_width(tmp_path):
         bench.run_benchmark(dataset_path, hash_bits=8)
 
 
+def test_cli_missing_dataset_prints_generation_hint_without_traceback(monkeypatch, capsys):
+    bench = load_sw_benchmark()
+    missing_path = Path("outputs/cam_retrieval_benchmark/datasets/cifar100_hash512_rows512_queries8192.npz")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "sw_retrieval_benchmark.py",
+            "--dataset",
+            str(missing_path),
+            "--hash-bits",
+            "512",
+            "--topk-k",
+            "5",
+            "--workers",
+            "1",
+        ],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        bench.main()
+
+    assert exc_info.value.code == 2
+    captured = capsys.readouterr()
+    assert "retrieval dataset not found" in captured.err
+    assert "python scripts/prepare_cam_retrieval_dataset.py" in captured.err
+    assert "--dataset cifar100" in captured.err
+    assert "--num-rows 512" in captured.err
+    assert "--max-queries 8192" in captured.err
+    assert "--hash-bits 512" in captured.err
+    assert "Traceback" not in captured.err
+
+
 def test_write_outputs_includes_quality_and_performance_csv(tmp_path):
     bench = load_sw_benchmark()
     result = {
         "run_id": "unit-test",
-        "mode": "software-hamming",
+        "mode": "software-numpy",
         "status": "pass",
-        "params": {"num_rows": 3, "hash_bits": 64, "topk_k": 2},
+        "params": {"num_rows": 3, "hash_bits": 64, "topk_k": 2, "workers": 2, "engine": "numpy"},
         "dataset": {"num_classes": 2, "num_queries": 2},
         "metrics": {
             "1": {
@@ -149,4 +266,7 @@ def test_write_outputs_includes_quality_and_performance_csv(tmp_path):
     assert "queries_per_second" in metrics_csv
     assert "1000000.0" in metrics_csv
     assert "Software CAM Retrieval Benchmark Summary" in summary_md
+    assert "software-numpy" in metrics_csv
+    assert "workers" in metrics_csv
+    assert "workers: `2`" in summary_md
     assert "queries_per_second" in summary_md