# vectordb-ntu/rabitq-library architecture

> Architecture diagram of the GitHub repository vectordb-ntu/rabitq-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vectordb-ntu/rabitq-library
- Repository: https://github.com/vectordb-ntu/rabitq-library

## Overview

RaBitQ is a C++17 vector-quantization and approximate-nearest-neighbor library with Python bindings. Its user workflow is to provide vectors and configuration, build or use an index, submit queries, and receive neighbor IDs and distances; indexes can also be persisted. The README identifies a standalone quantizer, IVF, HNSW, and SymphonyQG, plus architecture-specific acceleration. The bindings and several SIMD files were sampled, but most index implementations were not; the graph therefore follows documented capabilities and omits uncertain internal call chains.

Main entry points: [`include/rabitqlib/quantization/rabitq.hpp`](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp) (RaBitQ encoding), [`include/rabitqlib/index/ivf/ivf.hpp`](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp) (IVF index), [`src/simd/dispatch.cpp`](https://github.com/vectordb-ntu/rabitq-library/blob/main/src/simd/dispatch.cpp) (SIMD dispatch), [`python_bindings/ivf_bindings.cpp`](https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/ivf_bindings.cpp) (IVF binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_ivf_binding["IVF binding<br/>[ivf_bindings.cpp]"]
  node_hnsw_binding["HNSW binding<br/>[hnsw_bindings.cpp]"]
  node_symqg_binding["SymphonyQG binding<br/>[symqg_bindings.cpp]"]
  node_quant_binding["Quantizer binding"]
end

subgraph group_indexing["Indexes"]
  node_ivf["IVF index<br/>[ivf.hpp]"]
  node_hnsw["HNSW index<br/>[hnsw.hpp]"]
  node_symqg["SymphonyQG<br/>[qg.hpp]"]
  node_cluster["IVF clustering<br/>[cluster.hpp]"]
end

subgraph group_quantization["Quantization"]
  node_query["Query preparation<br/>[query.hpp]"]
  node_rabitq["RaBitQ encoding<br/>[rabitq.hpp]"]
  node_layout["Packed code layout<br/>[data_layout.hpp]"]
end

subgraph group_acceleration["CPU acceleration"]
  node_fastscan["FastScan<br/>[fastscan.hpp]"]
  node_simd_dispatch["SIMD dispatch<br/>[dispatch.cpp]"]
  node_simd_kernels["SIMD kernels<br/>[fastscan_avx2.cpp]"]
  node_cpu_features["CPU detection<br/>[cpu_features.cpp]"]
end

node_caller(("Python caller"))
node_results["Neighbor results"]

node_caller -->|"build / search"| node_ivf_binding
node_caller -->|"build / search"| node_hnsw_binding
node_caller -->|"build / search"| node_symqg_binding
node_caller -->|"quantize vectors"| node_quant_binding
node_ivf_binding -->|"invokes"| node_ivf
node_hnsw_binding -->|"invokes"| node_hnsw
node_symqg_binding -->|"invokes"| node_symqg
node_quant_binding -->|"invokes"| node_rabitq
node_ivf -->|"uses partitions"| node_cluster
node_ivf -->|"encodes vectors"| node_rabitq
node_hnsw -->|"stores compact codes"| node_rabitq
node_symqg -.->|"optional packed codes"| node_rabitq
node_rabitq -->|"packs codes"| node_layout
node_ivf -->|"batched estimates"| node_fastscan
node_symqg -->|"batched estimates"| node_fastscan
node_hnsw -->|"selects search kernels"| node_simd_dispatch
node_fastscan -->|"dispatches kernels"| node_simd_dispatch
node_simd_dispatch -->|"checks capabilities"| node_cpu_features
node_simd_dispatch -->|"selects backend"| node_simd_kernels
node_ivf_binding -->|"returns IDs and distances"| node_results
node_hnsw_binding -->|"returns IDs and distances"| node_results

click node_ivf_binding "https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/ivf_bindings.cpp"
click node_hnsw_binding "https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/hnsw_bindings.cpp"
click node_symqg_binding "https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/symqg_bindings.cpp"
click node_quant_binding "https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/rabitq_bindings.cpp"
click node_ivf "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp"
click node_hnsw "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/hnsw/hnsw.hpp"
click node_symqg "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg.hpp"
click node_cluster "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/ivf/cluster.hpp"
click node_query "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/query.hpp"
click node_rabitq "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp"
click node_layout "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/quantization/data_layout.hpp"
click node_fastscan "https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/fastscan/fastscan.hpp"
click node_simd_dispatch "https://github.com/vectordb-ntu/rabitq-library/blob/main/src/simd/dispatch.cpp"
click node_simd_kernels "https://github.com/vectordb-ntu/rabitq-library/blob/main/src/simd/fastscan_avx2.cpp"
click node_cpu_features "https://github.com/vectordb-ntu/rabitq-library/blob/main/src/utils/cpu_features.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ivf_binding,node_hnsw_binding,node_symqg_binding,node_quant_binding toneBlue
class node_ivf,node_hnsw,node_symqg,node_cluster toneAmber
class node_query,node_rabitq,node_layout toneMint
class node_fastscan,node_simd_dispatch,node_simd_kernels,node_cpu_features toneRose
class node_caller,node_results toneIndigo
```

## Components

### Python API

- [IVF binding](https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/ivf_bindings.cpp): `python_bindings/ivf_bindings.cpp`
- [HNSW binding](https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/hnsw_bindings.cpp): `python_bindings/hnsw_bindings.cpp`
- [SymphonyQG binding](https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/symqg_bindings.cpp): `python_bindings/symqg_bindings.cpp`
- [Quantizer binding](https://github.com/vectordb-ntu/rabitq-library/blob/main/python_bindings/rabitq_bindings.cpp): `python_bindings/rabitq_bindings.cpp`

### Indexes

- [IVF index](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp): `include/rabitqlib/index/ivf/ivf.hpp`
- [HNSW index](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/hnsw/hnsw.hpp): `include/rabitqlib/index/hnsw/hnsw.hpp`
- [SymphonyQG](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg.hpp): `include/rabitqlib/index/symqg/qg.hpp`
- [IVF clustering](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/ivf/cluster.hpp): `include/rabitqlib/index/ivf/cluster.hpp`

### Quantization

- [Query preparation](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/index/query.hpp): `include/rabitqlib/index/query.hpp`
- [RaBitQ encoding](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp): `include/rabitqlib/quantization/rabitq.hpp`
- [Packed code layout](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/quantization/data_layout.hpp): `include/rabitqlib/quantization/data_layout.hpp`

### CPU acceleration

- [FastScan](https://github.com/vectordb-ntu/rabitq-library/blob/main/include/rabitqlib/fastscan/fastscan.hpp): `include/rabitqlib/fastscan/fastscan.hpp`
- [SIMD dispatch](https://github.com/vectordb-ntu/rabitq-library/blob/main/src/simd/dispatch.cpp): `src/simd/dispatch.cpp`
- [SIMD kernels](https://github.com/vectordb-ntu/rabitq-library/blob/main/src/simd/fastscan_avx2.cpp): `src/simd/fastscan_avx2.cpp`
- [CPU detection](https://github.com/vectordb-ntu/rabitq-library/blob/main/src/utils/cpu_features.cpp): `src/utils/cpu_features.cpp`

### Other components

- **Python caller**
- **Neighbor results**

## Connections

- Python caller → IVF binding: build / search
- Python caller → HNSW binding: build / search
- Python caller → SymphonyQG binding: build / search
- Python caller → Quantizer binding: quantize vectors
- IVF binding → IVF index: invokes
- HNSW binding → HNSW index: invokes
- SymphonyQG binding → SymphonyQG: invokes
- Quantizer binding → RaBitQ encoding: invokes
- IVF index → IVF clustering: uses partitions
- IVF index → RaBitQ encoding: encodes vectors
- HNSW index → RaBitQ encoding: stores compact codes
- SymphonyQG → RaBitQ encoding: optional packed codes
- RaBitQ encoding → Packed code layout: packs codes
- IVF index → FastScan: batched estimates
- SymphonyQG → FastScan: batched estimates
- HNSW index → SIMD dispatch: selects search kernels
- FastScan → SIMD dispatch: dispatches kernels
- SIMD dispatch → CPU detection: checks capabilities
- SIMD dispatch → SIMD kernels: selects backend
- IVF binding → Neighbor results: returns IDs and distances
- HNSW binding → Neighbor results: returns IDs and distances