Add software-based CAM retrieval benchmark to compare retrieval quality
and speed against hardware simulation. Includes experiment documentation
with noise sweep analysis on CIFAR-10/100 datasets.
- Add sw_retrieval_benchmark.py for software Hamming distance Top-K retrieval
- Add test_sw_retrieval_benchmark.py with unit tests for dataset loading and metrics
- Add experiment doc (sw_hw_cam_retrieval_benchmark.md) comparing software vs hardware
- Document noise sweep impact on retrieval quality at various WRITE_NOISE_RATE values
- Rename `read_noise` scenarios and noise_mode to `read_pass_through` across
run_cam_correctness.py, test_run_cam_correctness.py, and Makefiles
- Update RTL comment in match_engine_pipeline.sv to reflect pass-through behavior
- Move unit-level cocotb tests from `tests.test_*` flat namespace to
`tests.modules.*` and `tests.top.*` subdirectory layout, matching actual
Makefile paths (hw/sim/tests/modules/..., hw/sim/tests/top/...)
- Remove redundant dual-noise subtarget from read_noise/Makefile
- Update help text and docs to reflect read-path pass-through semantics
- Add .codegraph to .gitignore
- Make cam_read_noise a pass-through module, removing all noise injection logic
- Switch write noise to use noise_mask_bernoulli instead of noise_mask_grouped
- Add state machine to cam_write_noise for mask generation timing
- Remove noise_mask_grouped.sv (no longer needed)
- Remove read noise parameters from cam_noisy and cam_top
- Update simulation and benchmark code to reflect read noise removal
- Sync documentation to reflect Phase 2 architecture
- Add noise_mask_bernoulli.sv RTL module for probabilistic masking
- Add cocotb test suite with reset, threshold, determinism, and distribution checks
- Update rtl-sources.mk to include new module
- Fix PYTHONPATH in devenv.nix shell hook
- Add just recipes for preparing CIFAR10/100 hash artifacts and running benchmarks
- Add CAM_RETRIEVAL_DATASET env var support in Makefile
- Add load_retrieval_dataset_npz() to load pre-prepared retrieval datasets
- Add label_hits counter and recall@k metric for retrieval evaluation
- Rename macro_recall to retrieval_recall to clarify semantics
- Emit rd_valid_o for exactly one combinational cycle before waiting for
read response, ensuring the read-noise PRNG advances once per batch issue
- Fix query handshake: wait for query_ready before asserting query_valid
to avoid valid&&ready handshake drops on clock edges
- Add dynamic timeout estimation in test utilities based on DUT parameters
- Update test-top Makefile to run all noise configurations by default
- Remove uv run prefix from cocotb-config Makefile invocation
Split the monolithic test_cam_basic.py into separate test suites
organized by noise configuration (no_noise, write_noise, read_noise),
with shared utilities extracted to tests/top/utils.py.
- Remove test_cam_basic.py; add no_noise/, write_noise/, read_noise/
test suites with Makefiles that set noise parameters statically
- Extract helpers (reset_dut, write_rows, query_once, collect_topk,
etc.) into tests/top/utils.py
- Update hw/sim/Makefile with per-config test targets and a
test-top-all meta-target
- Update scripts/run_cam_correctness.py to build per-directory
instead of centrally, removing inline parameter overrides
- Add __init__.py for result_serializer and topk_tracker module tests
- Expand docstrings in test_ref_model_noise.py with architectural
context and test rationale
- Introduce ImageHashPipeline Protocol for extensible hash computation
- Rename query_crop_index to query_index for clarity
- Make query_crop nullable to handle missing crop edge case
- Add keyword-only arguments for better API clarity
- Handle empty scene graph objects gracefully
- Add comprehensive test coverage for query_image_against_scene_graph
- Export ImageSceneGraphQueryResult and query_image_against_scene_graph from scenegraph module
- Replace inline hamming-distance-based image matching with dedicated query_image_against_scene_graph function
- Improve top_matches structure by extracting similarity scores and hash_bytes from matches
- Add .codegraph/ to gitignore (machine-local data, should not be committed)
- Add CodeGraph configuration for multi-language indexing
- Extract cam_bank as a parameterized submodule with independent read/write ports
- Replace flat 2D memory array with generate loop of bank instances
- Derive bank selection from address bit slicing instead of modulo arithmetic
- Align rd_base_row_i check with new bank addressing scheme
- Add test verifying bank address isolation across multiple banks
- Add Makefile with cocotb configuration for popcount_pipeline RTL simulation
- Add Python test module with reset, drive/expect helpers
- Test row metadata preservation and bit-count correctness across 7 vectors
- Add SoftwareCamIndex class with xnor_popcount_score for CAM-style matching
- Add CamMatch and SceneGraphMatch dataclasses for query results
- Add query_by_visual_hash method to SimpleSceneGraph
- Add comprehensive tests for SoftwareCamIndex and xnor_popcount_score
- Add write_training_metrics() in new compressors/training_metrics.py
for appending epoch/step/lr/component rows as JSON Lines
- Wire --metrics-path and --log-every CLI options into train.py, passing
them to the training loop so metrics rows are written every N steps
- Accept absolute metrics paths or paths relative to output directory
- Add quantization component to loss log alongside existing distill/contrastive
- Replace inline torch.device() with get_device() utility
- Add test_hash_training_metrics.py covering multi-row JSONL append
Infrastructure:
- Pin torch 2.7.1 + CUDA 12.8 index for Linux/Windows in pyproject.toml
- Add .justfile rsync upload recipe with .stignore exclusion
- Exclude **/__marimo__ from rsync in .stignore
Dependencies updated: numpy 2.4.5, pandas 3.0.3, black 26.5.0,
click 8.4.0, contourpy, etc.
- Set READ_NOISE_EN=1 as default in cam_top.sv
- Wire READ_NOISE_* parameters to NOISE_* makefile variables in cocotb-common.mk
- Add PYTHON env variable support in Makefile for test invocation
- Update .gitignore with glob patterns (**/sim_build/, **/results.xml, *.fst)
- Add justfile recipe for remote cam-test-top execution
- Split monolithic hw/sim/Makefile into modular include files (mk/cocotb-common.mk, mk/rtl-sources.mk)
- Add per-module test Makefiles (cam_core_banked, cam_read_noise, cam_write_noise, match_engine_pipeline, perf, top)
- Add missing simulation tools (yosys, graphviz, xdot) to devenv.nix
- Fix path handling in sweep_noise.py and test modules to be HASH_BITS-aware
- hw/sim/tests/test_cam_perf.py: new cocotb perf test with bounded wait helpers
- scripts/sweep_cam_perf.py: sweep data model, matrix, and make command builders
- tests/test_sweep_cam_perf.py: unit tests for sweep helpers
- tests/conftest.py: pytest path configuration for scripts package
- hw/sim/Makefile: deterministic noise params override for perf test compatibility
Introduce scripts/run_cam_correctness.py — a data-driven CAM correctness
checker that runs cocotb and pytest scenarios across multiple noise modes
and CAM submodules (cam_top, cam_core_banked, match_engine_pipeline).
Outputs structured CSV results and a paper-ready Chinese summary.
Add tests/test_run_cam_correctness.py with contract tests for scenario
spec validation, command building, subprocess error handling, output file
generation, CLI defaults, and environment preservation.
- Extract model loading logic from benchmark CLI into task-owned prepare_benchmark
- Add RetrievalEncoder class wrapping DINO with optional hash compression
- Add accelerate dependency for device management
- Switch dataset from CIFAR-10 to CIFAR-100 with fine_label column
- Delete popcount.sv, argmax_update.sv, cam_core.sv, match_engine.sv
- Remove obsolete VERILOG_SOURCES entries from Makefile
- Update comment in cam_top.sv to reference match_engine_pipeline
- Add verilator to devenv.nix for simulation support
- Replace NOISE_GEN_BITS/NOISE_SAMPLE_BITS parameters with unified NOISE_BITS
- Use xorshift128 (random128) instead of xorshift64 for PRNG
- Add flip_mask_next combinational helper for single-cycle mask computation
- Add random_enable signal to advance PRNG only on accepted noisy writes
- Simplify FSM by removing mask_group_idx counter
- Update parameter validation: GROUP_BITS (= HASH_BITS/NOISE_BITS) must equal 64
- Update ref_model.py and tests to match new seed convention: {seed, seed}
- Update Makefile and sweep_noise.py with renamed parameters
- Add random32, random64 and random128 xorshift PRNG modules
- Refactor cam_noisy FSM: split state register, next-state logic, and datapath into distinct blocks
- Rename state_q/state_d to curr_state/next_state for clarity
- Add MASK_GROUPS localparam and fix type casting in noise generation
- Update .gitignore to exclude docs/superpowers
- Move load_env_file, parse_timeout_seconds, build_remote_script, and
build_ssh_command to scripts/common.py
- Update remote_docker_run.py to import from common module
- Improves code organization and reusability
- Add verilator to dependencies
- Add configurable logging via QUIET/VERBOSE/COCOTB_LOG_LEVEL env vars
- Add optional warning suppression (SUPPRESS_VERILATOR_WARNINGS)
- Clean up and restructure Makefile
- Split cam_core into pure memory (cam_core.sv) and match engine (match_engine.sv)
- Add cam_params.svh with centralized parameter definitions (NUM_ROWS, HASH_BITS, LANES, etc.)
- Update cam_top.sv to use shared parameters and compose match_engine
- Update Makefile to include new match_engine module and correct Verilator define syntax
- Move habitat-baselines and habitat-lab from pip to conda environment
- Add cocotb and cocotb-tools to pyproject.toml dependencies
- Update ty environment roots to include hw/sim directory
- Add sim/sim_build to gitignore
- Create CLAUDE.md with project spec, coding guidelines, and directory structure
- Update uv.lock to reflect dependency changes
- Add FramePacket dataclass to encapsulate per-image pipeline state
- Rename internal methods with underscore prefix convention
- Replace separate filter_batch/crop_batch with unified process_batch method
- Update notebook to use new HashPipeline API
