add read the docs documentation

Bluemi · Bluemi · commit 880d0c16140f · 2025-09-08T09:59:51.000+02:00
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,13 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build/
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/api/builder.rst b/docs/api/builder.rst
@@ -0,0 +1,20 @@
+Graph Builder
+=============
+
+EvenRegularGraphBuilder
+***********************
+
+The class `EvenRegularGraphBuilder` is used to construct search graphs.
+
+.. autoclass:: deglib.builder.EvenRegularGraphBuilder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+
+.. _build_from_data:
+
+build_from_data()
+*****************
+.. autofunction:: deglib.builder.build_from_data
+
diff --git a/docs/api/graphs/index.rst b/docs/api/graphs/index.rst
@@ -0,0 +1,18 @@
+Overview Graphs
+===============
+
+The following graph classes are defined:
+
+* SearchGraph: An abstract interface for all graph classes.
+* MutableGraph: An abstract base class, that can change by adding/removing vertices.
+* SizeBoundedGraph: An implementation of the `MutableGraph`-class.
+* ReadOnlyGraph: Once a `MutableGraph` is built, you can instantiate a `ReadOnlyGraph` from it.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Graph classes:
+
+   search_graph
+   mutable_graph
+   read_only_graph
+   size_bounded_graph
diff --git a/docs/api/graphs/mutable_graph.rst b/docs/api/graphs/mutable_graph.rst
@@ -0,0 +1,13 @@
+MutableGraph
+============
+
+The MutableGraph is an abstract base class, that allows modifications and additions to the graph.
+It is used to build graphs.
+`SizeBoundedGraph` is a subclass.
+
+.. autoclass:: deglib.graph.MutableGraph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: to_cpp
+   :member-order: bysource
diff --git a/docs/api/graphs/read_only_graph.rst b/docs/api/graphs/read_only_graph.rst
@@ -0,0 +1,13 @@
+ReadOnlyGraph
+=============
+
+The ReadOnlyGraph can not be modified. It is usually created using a `MutableGraph`.
+
+.. autoclass:: deglib.graph.ReadOnlyGraph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: to_cpp
+   :member-order: bysource
+
+.. autofunction:: deglib.graph.load_readonly_graph
diff --git a/docs/api/graphs/search_graph.rst b/docs/api/graphs/search_graph.rst
@@ -0,0 +1,13 @@
+.. _search_graph:
+
+SearchGraph
+===========
+
+The SearchGraph class defines an abstract interface for all graph classes.
+
+.. autoclass:: deglib.graph.SearchGraph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: to_cpp
+   :member-order: bysource
diff --git a/docs/api/graphs/size_bounded_graph.rst b/docs/api/graphs/size_bounded_graph.rst
@@ -0,0 +1,11 @@
+SizeBoundedGraph
+================
+
+The SizeBoundedGraph class is an implementation for `MutableGraph` and is used to build graphs.
+
+.. autoclass:: deglib.graph.SizeBoundedGraph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: to_cpp
+   :member-order: bysource
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,11 @@
+API
+===
+
+This is the API Documentation for the deglib project.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   graphs/index
+   builder
diff --git a/docs/build.sh b/docs/build.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+sphinx-build -M markdown ./ _build
+sphinx-build -M html ./ _build
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Dynamic Exploration Graph'
+copyright = '2025, Nico Hezel, Bruno Schilling'
+author = 'Nico Hezel, Bruno Schilling'
+release = '0.1.5'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,21 @@
+.. Dynamic Exploration Graph documentation master file, created by
+   sphinx-quickstart on Fri Sep  5 10:24:50 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Dynamic Exploration Graph documentation
+=======================================
+
+The Dynamic Exploration Graph (DEG) algorithm is a graphbased approximate nearest neighbor search technique.
+It offers performance comparable to HNSW while providing the added benefits of dynamic graph modification and robust exploration capabilities.
+
+.. image:: https://raw.githubusercontent.com/Visual-Computing/DynamicExplorationGraph/5a9e1274876539ffdbaedf916e8c077e0dec7798/figures/anns_qps_vs_recall.jpg
+   :alt: Plot visualizing the performance of different Search Methods
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   tutorials/index
+   api/index
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+deglib
diff --git a/docs/tutorials/building_graphs.rst b/docs/tutorials/building_graphs.rst
@@ -0,0 +1,99 @@
+Building Graphs
+===============
+
+This tutorial shows different methods of building graphs.
+
+Using the shorthand
+*******************
+
+The easiest way to build a search graph is to use the function `deglib.builder.build_from_data()`.
+
+.. code-block:: python
+
+    import numpy as np
+    import deglib
+
+    data = np.random.random((10_000, 256)).astype(np.float32)
+    graph = deglib.builder.build_from_data(data)
+
+This will instantiate a `SizeBoundedGraph` containing 10_000 random feature vectors from `data`.
+
+There are many different parameters to control the building process. See :ref:`build_from_data` for more information.
+
+LID.Unknown vs LID.High or LID.Low
+**********************************
+The crEG paper introduces an additional parameter, *LIDType*, to determine whether a dataset exhibits high complexity and Local Intrinsic Dimensionality (LID) or if it is relatively low. In contrast, the DEG paper presents a new algorithm that does not rely on this information. Consequently, DEG defaults to *LID.Unknown*. However, if the LID is known, utilizing it can be beneficial, as multi-threaded graph construction is only possible with these parameters.
+
+Metrics
+*******
+
+Deglib implements two different metrics:
+
+- The `L2` distance or euclidean distance.
+- The `InnerProduct` distance.
+
+The L2 metric is also available for uint8 features as `L2_Uint8`.
+
+Internal Index vs External Label
+********************************
+
+There are two kinds of indices used in a graph: `internal_index` and `external_label`. Both are integers and specify
+a vertex in a graph.
+
+Internal Indices are dense, which means that every `internal_index < len(graph)` can be used.
+For example: If you add 100 vertices and remove the vertex with internal_index 42, the last vertex in the graph will
+be moved to index 42.
+
+In contrast, external label is a user defined identifier for each added vertex
+(see `builder.add_entry(external_label, feature_vector)`). Adding or Removing vertices to the graph will keep the
+connection between external labels and associated feature vector.
+
+When you create the external labels by starting with `0` and increasing it for each entry by `1` and don't remove
+elements from the graph, external labels and internal indices are equal.
+
+.. code-block:: python
+
+    # as long as no elements are removed
+    # external labels and internal indices are equal
+    for i, vec in enumerate(data):
+        builder.add_entry(i, vec)
+
+Using builder object
+********************
+
+The above method is easy to use, but has drawbacks.
+For example it does not allow to load the data step by step, which leads to more memory usage.
+
+If we iterate over batches of data, we can add them to the graph like this:
+
+.. code-block:: python
+
+    graph = deglib.graph.SizeBoundedGraph.create_empty(N_SAMPLES, DIM, 16, deglib.Metric.L2)
+    builder = deglib.builder.EvenRegularGraphBuilder(graph)
+
+    counter = 0
+    for batch in enumerate(batches):
+        labels = np.arange(counter, batch.shape[0])
+        builder.add_entry(labels, batch)
+        counter += batch.shape[0]
+
+    builder.build()
+
+    graph.remove_non_mrng_edges()  # optional. This can help improve performance
+
+    # now you can use the graph
+
+
+Progress callback
+*****************
+
+If you want to get more feedback on the progress you can supply a callback function to `builder.build(callback)`.
+The callback takes a `BuilderStatus` as only argument.
+
+A `BuilderStatus` has the following attributes:
+
+* step (int) - number of graph manipulation steps
+* added (int) - number of added vertices
+* deleted (int) - number of deleted vertices
+* improved (int) - number of successful improvements
+* tries (int) - number of improvement tries
diff --git a/docs/tutorials/faq.rst b/docs/tutorials/faq.rst
@@ -0,0 +1,36 @@
+FAQ & Caveats
+=============
+
+What problem does deglib solve?
+*******************************
+
+The Dynamic Exploration Graph library (deglib) solves the approximate nearest neighbor (ANN) search problem.
+This involves finding data points that are most similar or "closest" to a given query point in a high-dimensional space, without having to check every single data point.
+
+Memory Management
+*****************
+
+A graph object owns the feature vectors. If the graph is freed, feature vectors are not longer valid.
+
+.. code-block:: python
+
+    feature_vector = graph.get_feature_vector(42)
+    del graph
+    print(feature_vector)
+
+This will crash as `feature_vector` is holding a reference to memory that is owned by `graph`. This can lead to undefined behaviour (most likely segmentation fault).
+Be careful to keep objects in memory that are referenced. If you need it use the `copy=True` option:
+
+.. code-block:: python
+
+    feature_vector = graph.get_feature_vector(10, copy=True)
+    del graph
+    print(feature_vector)  # no problem
+
+Copying feature vectors will be slower.
+
+Limitations
+***********
+
+- The python wrapper at the moment only supports `float32` and `uint8` feature vectors. For `uint8` vectors only `L2` Distance is supported.
+- Threaded building is not supported for `lid=LID.Unknown`. Use `LID.High` or `LID.Low` instead.
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -0,0 +1,14 @@
+Tutorials
+=========
+
+View the following tutorials to get started.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   quickstart
+   building_graphs
+   searching
+   faq
diff --git a/docs/tutorials/installation.rst b/docs/tutorials/installation.rst
diff --git a/docs/tutorials/quickstart.rst b/docs/tutorials/quickstart.rst
diff --git a/docs/tutorials/searching.rst b/docs/tutorials/searching.rst
