Skip to content

Commit 23654b3

Browse files
committed
docs: fix outdated API signatures, phantom CLI flags, and broken build commands
1 parent 2efa744 commit 23654b3

14 files changed

Lines changed: 116 additions & 91 deletions

File tree

‎cpp/API.md‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -352,14 +352,14 @@ namespace deglib::optimization {
352352
/// Prune the worst (longest/highest-weight) neighbors per vertex, replacing them with self-loops
353353
void prune_worst_edges(MutableGraph& graph, uint8_t prune_worst, size_t num_threads = 0);
354354

355-
/// Parallel removal of edges violating the Monotonic Relative Neighbor Graph (MRNG) rule
356-
uint32_t prune_non_mrng_edges(MutableGraph& graph, size_t num_threads = 0);
355+
/// Parallel removal of edges violating the Relative Neighborhood Graph (RNG) rule
356+
uint32_t prune_non_rng_edges(MutableGraph& graph, size_t num_threads = 0);
357357

358-
/// Remove non-MRNG edges using a globally weight-sorted strategy
359-
uint32_t prune_non_mrng_edges_weight_sorted(MutableGraph& graph, size_t num_threads = 0);
358+
/// Remove non-RNG edges using a globally weight-sorted strategy
359+
uint32_t prune_non_rng_edges_weight_sorted(MutableGraph& graph, size_t num_threads = 0);
360360

361-
/// Iteratively remove non-MRNG edges per-vertex until convergence
362-
uint32_t prune_non_mrng_edges_iterative(MutableGraph& graph, size_t num_threads = 0);
361+
/// Iteratively remove non-RNG edges per-vertex until convergence
362+
uint32_t prune_non_rng_edges_iterative(MutableGraph& graph, size_t num_threads = 0);
363363

364364
/// Optimize graph edges using continuous EvenRegularGraphBuilder improvement steps
365365
void optimize_edges(MutableGraph& graph, uint8_t k_opt, float eps_opt, uint8_t i_opt, uint32_t iterations);
@@ -381,6 +381,7 @@ vector<uint32_t> presort(
381381

382382
/// Stateful EVP quantizer holding the shared non_zeros setting.
383383
/// Construct once and reuse for database and query quantization.
384+
/// Defined in deglib::quantization::evp; the factory make_evp_quantizer lives in deglib::optimization.
384385
class EvpQuantizer {
385386
explicit EvpQuantizer(uint32_t non_zeros);
386387
void quantize(float* src, byte* dst, size_t count, uint32_t dim, size_t num_threads = 0);
@@ -506,7 +507,7 @@ public:
506507
uint32_t getExternalLabel(uint32_t internal_index);
507508
uint32_t getInternalIndex(uint32_t label);
508509
uint32_t* getNeighborIndices(uint32_t internal_index);
509-
uint32_t* getEntryVertexIndices();
510+
const std::vector<uint32_t>& getEntryVertexIndices() const;
510511
bool hasEdge(uint32_t from_index, uint32_t to_index);
511512

512513
ResultSet search(span<float> query, uint32_t k, float eps = 0.0f, Filter* filter = nullptr, uint32_t max_dc = 0);
@@ -516,8 +517,8 @@ public:
516517
/// Abstract base interface for mutable graphs supporting vertex & edge updates
517518
class MutableGraph : public InternalGraph {
518519
public:
519-
bool addVertex(uint32_t label, byte* feature_vector);
520-
bool removeVertex(uint32_t label);
520+
uint32_t addVertex(uint32_t label, byte* feature_vector);
521+
std::vector<uint32_t> removeVertex(uint32_t label);
521522
void changeEdges(uint32_t internal_index, uint32_t* neighbor_indices, float* neighbor_weights);
522523
float* getNeighborWeights(uint32_t internal_index);
523524
float getEdgeWeight(uint32_t from_index, uint32_t to_index);
@@ -535,7 +536,7 @@ public:
535536
static SizeBoundedGraph create_empty(uint32_t max_vertex_count, uint8_t edges_per_vertex, FloatSpace feature_space);
536537
static SizeBoundedGraph from_graph(InternalGraph& graph, uint32_t new_max_size = 0);
537538
static SizeBoundedGraph from_graph(InternalGraph& graph, FloatSpace custom_space, void* custom_features = nullptr, uint32_t new_max_size = 0);
538-
static SizeBoundedGraph load_from_file(const char* file_path, FloatSpace feature_space);
539+
// Loading is done via the free function deglib::graph::load_sizebounded_graph(const char* file_path, uint32_t new_max_size = 0)
539540
};
540541

541542
/// Mutable graph with chunk-allocated dynamically growing memory
@@ -545,7 +546,7 @@ public:
545546

546547
static DynamicGraph from_graph(InternalGraph& graph, uint32_t chunk_size = 1024);
547548
static DynamicGraph from_graph(InternalGraph& graph, FloatSpace custom_space, void* custom_features = nullptr, uint32_t chunk_size = 1024);
548-
static DynamicGraph load_from_file(const char* file_path, FloatSpace feature_space, uint32_t chunk_size = 1024);
549+
// Loading is done via the free function deglib::graph::load_dynamic_graph(const char* file_path, uint32_t chunk_size = 1024)
549550
};
550551

551552
/// Compact immutable graph layout optimized for query serving
@@ -554,7 +555,7 @@ public:
554555
ReadOnlyGraph(uint32_t max_vertex_count, uint8_t edges_per_vertex, FloatSpace feature_space);
555556
ReadOnlyGraph(uint32_t max_vertex_count, uint8_t edges_per_vertex, FloatSpace feature_space, InternalGraph& graph);
556557

557-
static ReadOnlyGraph load_from_file(const char* file_path, FloatSpace feature_space);
558+
// Loading is done via the free function deglib::graph::load_readonly_graph(const char* file_path)
558559
};
559560

560561
} // namespace deglib::graph
@@ -571,11 +572,13 @@ Runtime hardware feature detection and SIMD instruction set configuration.
571572
```cpp
572573
namespace deglib::cpu {
573574
574-
enum class InstructionSet {
575-
Auto, ///< Automatically select the highest instruction set supported by host CPU
576-
Scalar, ///< Standard scalar operations
577-
AVX2, ///< 256-bit AVX2 + FMA SIMD
578-
AVX512 ///< 512-bit AVX-512 SIMD
575+
enum class InstructionSet : uint8_t {
576+
Auto = 0, ///< Automatically select the highest instruction set supported by host CPU
577+
Scalar = 1, ///< Standard scalar operations
578+
AVX2 = 2, ///< 256-bit AVX2 + FMA SIMD
579+
AVX2_VNNI = 3, ///< 256-bit AVX2 with VNNI acceleration
580+
AVX512 = 4, ///< 512-bit AVX-512 SIMD
581+
AVX512_VNNI = 5 ///< 512-bit AVX-512 with VNNI acceleration
579582
};
580583
581584
/// Runtime AVX2 support check
@@ -584,7 +587,7 @@ bool has_avx2();
584587
/// Runtime AVX-512 support check
585588
bool has_avx512();
586589
587-
/// Returns string representation ("Auto", "Scalar", "AVX2", "AVX512")
590+
/// Returns string representation ("Auto", "Scalar", "AVX2", "AVX2_VNNI", "AVX512", "AVX512_VNNI")
588591
const char* instruction_set_to_string(InstructionSet inst);
589592
590593
} // namespace deglib::cpu
@@ -602,7 +605,7 @@ Cache line prefetching utilities.
602605
namespace deglib::memory {
603606

604607
/// Prefetches memory into L1 cache for subsequent distance computations
605-
void prefetch(void* ptr, size_t size = 128);
608+
void prefetch(const char* ptr, size_t size = 128);
606609

607610
} // namespace deglib::memory
608611
```

‎cpp/bench/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,12 +100,12 @@ Simulates streaming workloads and incremental graph maintenance:
100100
Evaluates edge refinement and quality improvement on regular graphs over iterations:
101101

102102
```bash
103-
./bench_edge_optimization audio --threads 8
103+
./bench_edge_optimization audio
104104
```
105105

106106
**Options:**
107107
* `--log-after <iters>`: Number of edge-swapping iterations between benchmark checkpoints (default: `100,000`).
108-
* `--max-iterations <iters>`: Maximum total swap iterations (default: `1,000,000`).
108+
* `--iterations <iters>`: Maximum total swap iterations (default: `1,000,000`).
109109

110110
---
111111

@@ -115,7 +115,7 @@ Compares graph build time, cache locality, and resulting ANNS search performance
115115
2. FLAS (Fast Linear Assignment Sorter) 1D pre-sorted ordering.
116116

117117
```bash
118-
./bench_flas_presort sift1m --decay 0.9 --threads 12
118+
./bench_flas_presort sift1m --flas-decay 0.9 --threads 12
119119
```
120120

121121
---

‎cpp/readme.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ It supports both static and dynamic streaming datasets through incremental exten
1818
- Hand-optimized AVX-512 and AVX2 vector kernels with automatic runtime/compiler dispatch and Scalar fallback.
1919
- Metrics: `FP32_L2`, `FP32_InnerProduct`, `Uint8_L2`, `Uint8_InnerProduct`, `Int8_L2`, `Int8_InnerProduct`, `FP16_L2`, `FP16_InnerProduct`, and quantized `EVP_InnerProduct`.
2020
- **Graph Optimization & Diagnostics**:
21-
- Topology pruning (`prune_worst_edges`, `prune_non_mrng_edges`).
21+
- Topology pruning (`prune_worst_edges`, `prune_non_rng_edges`).
2222
- Analysis suite (`analyze_graph`, connectivity validation, exploration reachability).
2323
- **Label Filtering**: Metadata and boolean ID filtering during search via `deglib::search::Filter`.
2424

@@ -113,13 +113,13 @@ auto mutable_graph = deglib::load_mutable_graph("index.deg", /*new_max_size=*/10
113113

114114
### High-Performance Searcher (`eps_or_ef`)
115115

116-
`deglib::search::Searcher` provides a high-throughput query execution pipeline supporting entry vertex optimization, optional on-the-fly query quantization, exact candidate reranking, and multithreaded batch search with unified exploration parameter `eps_or_ef`:
116+
`deglib::search::SearcherBase` provides a high-throughput query execution pipeline supporting entry vertex optimization, optional on-the-fly query quantization, exact candidate reranking, and multithreaded batch search with unified exploration parameter `eps_or_ef`:
117117

118118
```cpp
119-
#include <deglib/search/searcher.h>
119+
#include <deglib/deglib.h>
120120

121121
// 1. Create searcher on top of a graph (optionally with quantizer & refiner)
122-
auto searcher = deglib::search::make_searcher(readonly_graph);
122+
auto searcher = deglib::make_searcher(readonly_graph);
123123
searcher->optimize(/*n_clusters=*/128); // entry vertex medoids via k-means
124124

125125
// 2. Query with relative distance margin (eps_or_ef < 1.0)

‎cpp/test/src/unit/optimization/test_pruning.cpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// test_pruning.cpp — Unit tests for deglib::optimization::pruning methods
22
//
3-
// Covers: prune_worst_edges, prune_non_mrng_edges, prune_non_mrng_edges_weight_sorted,
4-
// prune_non_mrng_edges_iterative
3+
// Covers: prune_worst_edges, prune_non_rng_edges, prune_non_rng_edges_weight_sorted,
4+
// prune_non_rng_edges_iterative
55

66
#include "deglib/analysis.h"
77
#include "deglib/graph/sizebounded_graph.h"

‎docs/README.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,6 @@ uv run sphinx-build -b html . _build/html
2424

2525
Once built, open `_build/html/index.html` in your browser.
2626

27-
### Build Markdown
28-
29-
To build Markdown documentation:
30-
31-
```bash
32-
uv run sphinx-build -b markdown . _build/markdown
33-
```
34-
3527
### Clean Build Directory
3628

3729
To remove previous build artifacts:

‎examples/dynamic_data/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ uv run python main.py [dataset] [options]
2626
### Datasets
2727
- `sift1m` — SIFT1M (1M vectors, 128D, default)
2828
- `deep1m` — DEEP1M (1M vectors, 96D)
29-
- `glove` / `glove-100` — GloVe (1.18M vectors, 100D)
29+
- `glove` — GloVe (1.18M vectors, 100D)
3030
- `audio` — Audio (53.3k vectors, 192D)
3131
- `enron` — Enron (94.9k vectors, 1369D)
3232
- `all` — Run all datasets sequentially

‎examples/knng/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ Given $N$ high-dimensional vectors, the goal of k-NNG construction (self-join) i
1111

1212
The approach demonstrates **Mode 4 (`evp-rerank`)**, which achieves state-of-the-art trade-offs between construction speed and neighbor recall ($\ge 88\%$):
1313

14-
1. **EVP Quantization**: Feature vectors are converted to compact sparse EVP-bit representations using `deglib.optimization.EvpQuantizer` (`--non-zeros 512`).
14+
1. **EVP Quantization**: Feature vectors are converted to compact sparse EVP-bit representations using `deglib.optimization.EvpQuantizer` (`--non-zeros 700`).
1515
2. **DEG Construction**: A dynamic exploration graph is constructed using DEG's `GraphBuilder` with the `EVP_InnerProduct` metric for fast quantized distance computation.
1616
3. **Graph Exploration**: Exploration for vertex $i$ walks the DEG graph neighborhood using fast EVP bit-level inner product distances to collect candidates (`evpK = 50`).
17-
4. **FP16 Candidate Reranking**: Exact inner-product distances are computed using `deglib_cpp.floats_to_fp16` and `deglib_cpp.fp16_to_floats` for candidate sets to produce final $k$-nearest neighbor edges.
17+
4. **FP16 Candidate Reranking**: Candidate sets are reranked with exact half-precision inner-product distances via `deglib.search.rerank` (using an `FP16_InnerProduct` space) to produce final $k$-nearest neighbor edges.
1818

1919
## Prerequisites: Building the Python Library (`deglib`)
2020

@@ -34,7 +34,7 @@ uv sync --reinstall-package deglib
3434
3535
## Running the Benchmark with `uv`
3636

37-
### 1. Run Full Benchmark (200K Wikipedia BGE-M3 vectors)
37+
### 1. Run Benchmark (small Wikipedia BGE-M3 dataset, ~10K vectors)
3838

3939
```bash
4040
uv run main.py
@@ -45,11 +45,13 @@ uv run main.py
4545

4646
## Command-Line Options
4747

48-
- `--dataset`: Path to HDF5 dataset file or `"small"` (default: downloads/uses Wikipedia BGE-M3 200K dataset).
49-
- `--max-vecs`: Limit vector count for fast verification.
48+
- `--dataset`: Path to HDF5 dataset file or `"small"` (default: downloads/uses the small Wikipedia BGE-M3 dataset).
5049
- `--non-zeros`: Number of non-zero active components in EVP quantization
5150
- `--k-graph`: Graph degree per vertex
51+
- `--k-ext`: Builder search size (extension) parameter
5252
- `--max-dist`: Maximum distance calculation budget per query
5353
- `--evpK`: Number of candidate vertices retrieved before FP16 reranking
54+
- `--prune-worst`: Number of worst neighbors to replace with self-loops
5455
- `--threads`: Number of parallel execution threads
5556
- `--output-plot`: Save execution time breakdown chart to a file.
57+
- `--no-show`: Disable GUI plot display.

‎examples/mips/README.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,18 @@ We use a 5-step pipeline that reduces MIPS to $L_2$ graph search while retaining
2222
A `DynamicExplorationGraph` is constructed using `GraphBuilder` in $(d+1)$-dimensional `Metric.FP32_L2` space ($K_{\text{graph}} = 32, K_{\text{ext}} = 64$).
2323

2424
4. **FP16 Feature Swapping & `ReadOnlyGraph`**:
25-
The original $d$-dimensional FP32 database vectors are converted to 16-bit half-precision floats (`deglib.floats_to_fp16`). The graph topology built in step 3 is converted to a `ReadOnlyGraph` with `Metric.FP16_InnerProduct` space by passing the FP16 feature buffer (`graph.to_readonly(feature_space=..., custom_features=...)`).
25+
The original $d$-dimensional FP32 database vectors are converted to 16-bit half-precision floats (`deglib.distances.floats_to_fp16`). The graph topology built in step 3 is converted to a `ReadOnlyGraph` with `Metric.FP16_InnerProduct` space by passing the FP16 feature buffer (`graph.to_readonly(feature_space=..., custom_features=...)`).
2626

2727
5. **SIMD FP16 Inner Product Search**:
28-
Query vectors are converted to FP16 (`deglib.floats_to_fp16`) and searched on the `ReadOnlyGraph` using fast SIMD FP16 inner product distance routines ($\varepsilon_{\text{search}} = 0.18$, max distance evaluation budget sweep: `6000, 6500, 7000, 7500, 8000, 9000`).
28+
Query vectors are converted to FP16 (`deglib.distances.floats_to_fp16`) and searched on the `ReadOnlyGraph` using fast SIMD FP16 inner product distance routines ($\varepsilon_{\text{search}} = 0.18$, max distance evaluation budget sweep: `6000, 6500, 7000, 7500, 8000, 9000`).
2929

3030
---
3131

3232
## Dataset
3333

3434
This example benchmarks on the **SISAP 2026 `llama-dev`** dataset (Llama embeddings):
3535
- **Repository**: [`SISAP-Challenges/SISAP2026`](https://huggingface.co/datasets/SISAP-Challenges/SISAP2026)
36-
- **Files**: `llama-dev/llama-dev.h5` and `config.json`
36+
- **Files**: `llama-dev/llama-dev.h5`
3737
- **Data Structure**:
3838
- `train`: Floating-point database vectors ($N$ vectors, $d$ dimensions)
3939
- `test/queries`: Query vectors
@@ -74,19 +74,29 @@ The script displays an interactive Matplotlib trade-off plot (Recall vs Search T
7474
```
7575
usage: main.py [-h] [--dataset DATASET] [--k-graph K_GRAPH] [--k-ext K_EXT]
7676
[--eps-ext EPS_EXT] [--eps-search EPS_SEARCH] [--no-flas]
77-
[--flas-decay FLAS_DECAY] [--prune-worst PRUNE_WORST]
78-
[--threads THREADS] [--output-plot OUTPUT_PLOT] [--no-show]
77+
[--flas-decay FLAS_DECAY] [--build-threads BUILD_THREADS]
78+
[--search-threads SEARCH_THREADS]
79+
[--opt-target {StreamingData,LowLID,HighLID}]
80+
[--num-runs NUM_RUNS] [--max-dist MAX_DIST]
81+
[--instruction {Auto,Scalar,AVX2,AVX512}]
82+
[--output-plot OUTPUT_PLOT] [--no-show]
7983
8084
options:
8185
--dataset DATASET Path to HDF5 dataset file or 'llama-dev' (default: llama-dev)
8286
--k-graph K_GRAPH Graph degree per vertex (default: 32)
8387
--k-ext K_EXT Builder search size parameter (default: 64)
84-
--eps-ext EPS_EXT Builder search expansion factor (default: 0.2)
88+
--eps-ext EPS_EXT Builder search expansion factor (default: 0.001)
8589
--eps-search EPS_SEARCH Epsilon search factor (default: 0.18)
8690
--no-flas Disable FLAS 1D pre-sorting
8791
--flas-decay FLAS_DECAY FLAS neighborhood radius decay rate (default: 0.9)
88-
--prune-worst PRUNE_WORST Number of worst neighbors to replace with self-loops (default: 0)
89-
--threads THREADS Number of parallel threads (default: 8)
92+
--build-threads BUILD_THREADS Number of threads for graph building (default: 1)
93+
--search-threads SEARCH_THREADS Number of parallel threads for query search (default: 8)
94+
--opt-target {StreamingData,LowLID,HighLID}
95+
Optimization target: StreamingData, LowLID, HighLID (default: LowLID)
96+
--num-runs NUM_RUNS Number of search repetitions for averaging (default: 100)
97+
--max-dist MAX_DIST Comma-separated list of max distance budgets (default: 6000,6500,7000,7500,8000,9000)
98+
--instruction {Auto,Scalar,AVX2,AVX512}
99+
SIMD instruction set: Auto, Scalar, AVX2, AVX512 (default: Auto)
90100
--output-plot OUTPUT_PLOT Path to save trade-off curve PNG
91101
--no-show Disable GUI plot display
92102
```

‎examples/sliding_window/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@ Each round prints the core evaluation metrics:
5656

5757
| Argument | Type | Default | Description |
5858
|---|---|---|---|
59+
| `--dataset` | `str` | `redcaps` | Benchmark dataset to download & use (use `custom` with `--base-file`). |
60+
| `--base-file` | `str` | `None` | Path to a custom `.fvecs` / `.fbin` / `.hdf5` base vector file. |
61+
| `--query-file` | `str` | `None` | Path to a custom `.fvecs` / `.fbin` / `.hdf5` query vector file. |
5962
| `--window-size` | `int` | `500000` | Size of sliding window ($N$). |
6063
| `--batch-size` | `int` | `5000` | Inserts and deletes per round ($M$). |
6164
| `--rounds` | `int` | `100` | Number of update rounds. |

‎examples/static_data/README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This example project demonstrates how to download paper datasets from `readme.md
1111
- `enron` (1369D, 94k base vectors, L2 distance)
1212
- `sift1m` (128D, 1M base vectors, L2 distance)
1313
- `deep1m` (96D, 1M base vectors, L2 distance)
14-
- `glove-100` (100D, 1.18M base vectors, Angular / InnerProduct distance)
14+
- `glove` (100D, 1.18M base vectors, Angular / InnerProduct distance)
1515

1616
## Prerequisites: Building the Python Library (`deglib`)
1717

@@ -36,19 +36,22 @@ uv sync --reinstall-package deglib
3636
### 1. Run Full Benchmark (e.g. SIFT1M)
3737

3838
```bash
39-
uv run main.py --dataset sift1m
39+
uv run main.py sift1m
4040
```
4141

4242
### 2. Fast Test Run (e.g. Audio dataset with 1,000 vectors)
4343

4444
```bash
45-
uv run main.py --dataset audio --max-base-vecs 1000
45+
uv run main.py audio --max-base-vecs 1000
4646
```
4747

4848
## Options
4949

50-
- `--dataset`: Dataset name (`sift1m`, `audio`, `enron`, `deep1m`, `glove-100`). Default: `sift1m`.
50+
- `dataset`: Positional dataset name (`sift1m`, `deep1m`, `glove`, `audio`, `enron`, `all`). Default: `audio`.
51+
- `--graph-path`: Save the generated `.deg` graph file to this path. Default: none (graph kept in RAM).
52+
- `--instruction`: SIMD instruction set (`auto`, `scalar`, `avx2`, `avx512`). Default: `auto`.
53+
- `--force-rebuild`: Force rebuilding graph files even if they already exist.
54+
- `--threads`: Number of threads used for building the graph. Default: `1`.
5155
- `--cache-dir`: Persistent cache folder for datasets. Default: `~/.cache/deg_datasets`.
52-
- `--output-plot`: Optional path to also save the plot to a PNG image (e.g. `--output-plot recall_vs_qps.png`).
5356
- `--no-show`: Disable opening the interactive plot window (useful for headless CI environments).
5457
- `--max-base-vecs`: Limit base vectors for fast debugging / testing.

0 commit comments

Comments
 (0)