usearch 2.15.2 → 2.15.3

package/simsimd/README.md

@@ -1,14 +1,15 @@
-# SimSIMD 📏
-
-![SimSIMD banner](https://github.com/ashvardanian/ashvardanian/blob/master/repositories/SimSIMD.png?raw=true)
+![SimSIMD banner](https://github.com/ashvardanian/ashvardanian/blob/master/repositories/SimSIMD.jpg?raw=true)
 
 Computing dot-products, similarity measures, and distances between low- and high-dimensional vectors is ubiquitous in Machine Learning, Scientific Computing, Geo-Spatial Analysis, and Information Retrieval.
-These algorithms generally have linear complexity in time, constant complexity in space, and are data-parallel.
-In other words, it is easily parallelizable and vectorizable and often available in packages like BLAS and LAPACK, as well as higher-level `numpy` and `scipy` Python libraries.
+These algorithms generally have linear complexity in time, constant or linear complexity in space, and are data-parallel.
+In other words, it is easily parallelizable and vectorizable and often available in packages like BLAS (level 1) and LAPACK, as well as higher-level `numpy` and `scipy` Python libraries.
 Ironically, even with decades of evolution in compilers and numerical computing, [most libraries can be 3-200x slower than hardware potential][benchmarks] even on the most popular hardware, like 64-bit x86 and Arm CPUs.
-SimSIMD attempts to fill that gap.
+Moreover, most lack mixed-precision support, which is crucial for modern AI!
+The rare few that support minimal mixed precision, run only on one platform, and are vendor-locked, by companies like Intel and Nvidia.
+SimSIMD provides an alternative.
 1️⃣ SimSIMD functions are practically as fast as `memcpy`.
-2️⃣ SimSIMD [compiles to more platforms than NumPy (105 vs 35)][compatibility] and has more backends than most BLAS implementations.
+2️⃣ Unlike BLAS, most kernels are designed for mixed-precision and bit-level operations.
+3️⃣ SimSIMD [compiles to more platforms than NumPy (105 vs 35)][compatibility] and has more backends than most BLAS implementations, and more high-level interfaces than most libraries.
 
 [benchmarks]: https://ashvardanian.com/posts/simsimd-faster-scipy
 [compatibility]: https://pypi.org/project/simsimd/#files
@@ -41,40 +42,50 @@ SimSIMD attempts to fill that gap.
 
 ## Features
 
-SimSIMD provides over 100 SIMD-optimized kernels for various distance and similarity measures, accelerating search in [USearch](https://github.com/unum-cloud/usearch) and several DBMS products.
+__SimSIMD__ (Arabic: "سيمسيم دي") is a library of __over 200 SIMD-optimized kernels__ for distance and similarity measures, boosting search performance in [USearch](https://github.com/unum-cloud/usearch) and several database systems.
+Named after the iconic ["Open Sesame"](https://en.wikipedia.org/wiki/Open_sesame) command from _Ali Baba and the Forty Thieves_, it opens the doors to a modern treasure: maximizing the potential of today's hardware for high resource utilization.
 Implemented distance functions include:
 
-- Euclidean (L2) and Cosine (Angular) spatial distances for Vector Search.
-- Dot-Products for real & complex vectors for DSP & Quantum computing.
-- Hamming (~ Manhattan) and Jaccard (~ Tanimoto) bit-level distances.
-- Kullback-Leibler and Jensen–Shannon divergences for probability distributions.
-- Haversine and Vincenty's formulae for Geospatial Analysis.
-- For Levenshtein, Needleman–Wunsch and other text metrics, check [StringZilla][stringzilla].
-
+- Euclidean (L2) and Cosine (Angular) spatial distances for Vector Search. _[docs][docs-spatial]_
+- Dot-Products for real & complex vectors for DSP & Quantum computing. _[docs][docs-dot]_
+- Hamming (~ Manhattan) and Jaccard (~ Tanimoto) bit-level distances. _[docs][docs-binary]_
+- Set Intersections for Sparse Vectors and Text Analysis. _[docs][docs-sparse]_
+- Mahalanobis distance and Quadratic forms for Scientific Computing. _[docs][docs-curved]_
+- Kullback-Leibler and Jensen–Shannon divergences for probability distributions. _[docs][docs-probability]_
+- For Levenshtein, Needleman–Wunsch, and Smith-Waterman, check [StringZilla][stringzilla].
+- 🔜 Haversine and Vincenty's formulae for Geospatial Analysis.
+
+[docs-spatial]: #cosine-similarity-reciprocal-square-root-and-newton-raphson-iteration
+[docs-curved]: #curved-spaces-mahalanobis-distance-and-bilinear-quadratic-forms
+[docs-sparse]: #set-intersection-galloping-and-binary-search
+[docs-binary]: https://github.com/ashvardanian/SimSIMD/pull/138
+[docs-dot]: #complex-dot-products-conjugate-dot-products-and-complex-numbers
+[docs-probability]: #logarithms-in-kullback-leibler--jensenshannon-divergences
 [scipy]: https://docs.scipy.org/doc/scipy/reference/spatial.distance.html#module-scipy.spatial.distance
 [numpy]: https://numpy.org/doc/stable/reference/generated/numpy.inner.html
 [stringzilla]: https://github.com/ashvardanian/stringzilla
 
 Moreover, SimSIMD...
 
-- handles `f64`, `f32`, and `f16` real & complex vectors.
-- handles `i8` integral and `b8` binary vectors.
+- handles `f64`, `f32`, `f16`, and `bf16` real & complex vectors.
+- handles `i8` integral and `b8` bit vectors.
 - is a zero-dependency [header-only C 99](#using-simsimd-in-c) library.
-- has bindings for [Python](#using-simsimd-in-python), [Rust](#using-simsimd-in-rust) and [JavaScript](#using-simsimd-in-javascript).
-- has Arm backends for NEON and Scalable Vector Extensions (SVE).
-- has x86 backends for Haswell, Skylake, Ice Lake, and Sapphire Rapids.
+- has bindings for [Python](#using-simsimd-in-python), [Rust](#using-simsimd-in-rust) and [JS](#using-simsimd-in-javascript).
+- has Arm backends for NEON, Scalable Vector Extensions (SVE), and SVE2.
+- has x86 backends for Haswell, Skylake, Ice Lake, Genoa, and Sapphire Rapids.
+- with both compile-time and runtime CPU feature detection easily integrates anywhere!
 
-Due to the high-level of fragmentation of SIMD support in different x86 CPUs, SimSIMD uses the names of select Intel CPU generations for its backends.
+Due to the high-level of fragmentation of SIMD support in different x86 CPUs, SimSIMD generally uses the names of select Intel CPU generations for its backends.
 They, however, also work on AMD CPUs.
 Intel Haswell is compatible with AMD Zen 1/2/3, while AMD Genoa Zen 4 covers AVX-512 instructions added to Intel Skylake and Ice Lake.
 You can learn more about the technical implementation details in the following blog-posts:
 
 - [Uses Horner's method for polynomial approximations, beating GCC 12 by 119x](https://ashvardanian.com/posts/gcc-12-vs-avx512fp16/).
 - [Uses Arm SVE and x86 AVX-512's masked loads to eliminate tail `for`-loops](https://ashvardanian.com/posts/simsimd-faster-scipy/#tails-of-the-past-the-significance-of-masked-loads).
-- [Uses AVX-512 FP16 for half-precision operations, that few compilers vectorize](https://ashvardanian.com/posts/simsimd-faster-scipy/#the-challenge-of-f16).
-- [Substitutes LibC's `sqrt` calls with bit-hacks using Jan Kadlec's constant](https://ashvardanian.com/posts/simsimd-faster-scipy/#bonus-section-bypassing-sqrt-and-libc-dependencies).
-- [For Python avoids slow PyBind11, SWIG, and even `PyArg_ParseTuple` for speed](https://ashvardanian.com/posts/pybind11-cpython-tutorial/).
-- [For JavaScript uses typed arrays and NAPI for zero-copy calls](https://ashvardanian.com/posts/javascript-ai-vector-search/).
+- [Substitutes LibC's `sqrt` with Newton Raphson iterations](https://github.com/ashvardanian/SimSIMD/releases/tag/v5.4.0).
+- [Uses Galloping and SVE2 histograms to intersect sparse vectors](https://ashvardanian.com/posts/simd-set-intersections-sve2-avx512/).
+- For Python: [avoids slow PyBind11, SWIG, & `PyArg_ParseTuple`](https://ashvardanian.com/posts/pybind11-cpython-tutorial/) [using faster calling convention](https://ashvardanian.com/posts/discount-on-keyword-arguments-in-python/).
+- For JavaScript: [uses typed arrays and NAPI for zero-copy calls](https://ashvardanian.com/posts/javascript-ai-vector-search/).
 
 ## Benchmarks
 
@@ -82,12 +93,12 @@ You can learn more about the technical implementation details in the following b
 
 Given 1000 embeddings from OpenAI Ada API with 1536 dimensions, running on the Apple M2 Pro Arm CPU with NEON support, here's how SimSIMD performs against conventional methods:
 
-| Kind                      | `f32` improvement | `f16` improvement | `i8` improvement | Conventional method                    | SimSIMD         |
-| :------------------------ | ----------------: | ----------------: | ---------------: | :------------------------------------- | :-------------- |
-| Inner Product             |           __2 x__ |           __9 x__ |         __18 x__ | `numpy.inner`                          | `inner`         |
-| Cosine Distance           |          __32 x__ |          __79 x__ |        __133 x__ | `scipy.spatial.distance.cosine`        | `cosine`        |
-| Euclidean Distance ²      |           __5 x__ |          __26 x__ |         __17 x__ | `scipy.spatial.distance.sqeuclidean`   | `sqeuclidean`   |
-| Jensen-Shannon Divergence |          __31 x__ |          __53 x__ |                  | `scipy.spatial.distance.jensenshannon` | `jensenshannon` |
+| Kind                      | `f32` improvement | `f16` improvement | `i8` improvement | Conventional method       | SimSIMD         |
+| :------------------------ | ----------------: | ----------------: | ---------------: | :------------------------ | :-------------- |
+| Inner (Dot) Product       |           __2 x__ |           __9 x__ |         __18 x__ | `numpy.inner`             | `inner`         |
+| Cosine Distance           |          __32 x__ |          __79 x__ |        __133 x__ | `scipy.*.*.cosine`        | `cosine`        |
+| Euclidean Distance ²      |           __5 x__ |          __26 x__ |         __17 x__ | `scipy.*.*.sqeuclidean`   | `sqeuclidean`   |
+| Jensen-Shannon Divergence |          __31 x__ |          __53 x__ |                  | `scipy.*.*.jensenshannon` | `jensenshannon` |
 
 ### Against GCC Auto-Vectorization
 
@@ -112,7 +123,7 @@ __Broader Benchmarking Results__:
 The package is intended to replace the usage of `numpy.inner`, `numpy.dot`, and `scipy.spatial.distance`.
 Aside from drastic performance improvements, SimSIMD significantly improves accuracy in mixed precision setups.
 NumPy and SciPy, processing `i8` or `f16` vectors, will use the same types for accumulators, while SimSIMD can combine `i8` enumeration, `i16` multiplication, and `i32` accumulation to avoid overflows entirely.
-The same applies to processing `f16` values with `f32` precision.
+The same applies to processing `f16` and `bf16` values with `f32` precision.
 
 ### Installation
 
@@ -123,6 +134,9 @@ pip install simsimd
 python -c "import simsimd; print(simsimd.get_capabilities())"
 ```
 
+With precompiled binaries, SimSIMD ships `.pyi` interface files for type hinting and static analysis.
+You can check all the available functions in [`python/annotations/__init__.pyi`](https://github.com/ashvardanian/SimSIMD/blob/main/python/annotations/__init__.pyi).
+
 ### One-to-One Distance
 
 ```py
@@ -134,7 +148,7 @@ vec2 = np.random.randn(1536).astype(np.float32)
 dist = simsimd.cosine(vec1, vec2)
 ```
 
-Supported functions include `cosine`, `inner`, `sqeuclidean`, `hamming`, and `jaccard`.
+Supported functions include `cosine`, `inner`, `sqeuclidean`, `hamming`, `jaccard`, `kulbackleibler`, `jensenshannon`, and `intersect`.
 Dot products are supported for both real and complex numbers:
 
 ```py
@@ -153,6 +167,8 @@ dist = simsimd.cosine(vec1, vec2, "i8")
 dist = simsimd.cosine(vec1, vec2, "f16")
 dist = simsimd.cosine(vec1, vec2, "f32")
 dist = simsimd.cosine(vec1, vec2, "f64")
+dist = simsimd.hamming(vec1, vec2, "bits")
+dist = simsimd.jaccard(vec1, vec2, "bits")
 ```
 
 It also allows using SimSIMD for half-precision complex numbers, which NumPy does not support.
@@ -165,6 +181,22 @@ simd.dot(vec1, vec2, "complex32")
 simd.vdot(vec1, vec2, "complex32")
 ```
 
+When dealing with sparse representations and integer sets, you can apply the `intersect` function to two 1-dimensional arrays of `uint16` or `uint32` integers:
+
+```py
+from random import randint
+import numpy as np
+import simsimd as simd
+
+length1, length2 = randint(1, 100), randint(1, 100)
+vec1 = np.random.randint(0, 1000, length1).astype(np.uint16)
+vec2 = np.random.randint(0, 1000, length2).astype(np.uint16)
+
+slow_result = np.intersect1d(vec1, vec2)
+fast_result = simd.intersect(vec1, vec2)
+assert slow_result == fast_result
+```
+
 ### One-to-Many Distances
 
 Every distance function can be used not only for one-to-one but also one-to-many and many-to-many distance calculations.
@@ -205,18 +237,44 @@ from simsimd import cdist, DistancesTensor
 
 matrix1 = np.random.randn(1000, 1536).astype(np.float32)
 matrix2 = np.random.randn(10, 1536).astype(np.float32)
-distances: DistancesTensor = simsimd.cdist(matrix1, matrix2, metric="cosine") # zero-copy
-distances_array: np.ndarray = np.array(distances, copy=True) # now managed by NumPy
+distances: DistancesTensor = simsimd.cdist(matrix1, matrix2, metric="cosine")   # zero-copy, managed by SimSIMD
+distances_array: np.ndarray = np.array(distances, copy=True)                    # now managed by NumPy
 ```
 
-### Multithreading
+### Multithreading and Memory Usage
 
 By default, computations use a single CPU core.
-To optimize and utilize all CPU cores on Linux systems, add the `threads=0` argument.
-Alternatively, specify a custom number of threads:
+To override this behavior, use the `threads` argument.
+Set it to `0` to use all available CPU cores.
+Here is an example of dealing with large sets of binary vectors:
+
+```py
+ndim = 1536 # OpenAI Ada embeddings
+matrix1 = np.packbits(np.random.randint(2, size=(10_000, ndim)).astype(np.uint8))
+matrix2 = np.packbits(np.random.randint(2, size=(1_000, ndim)).astype(np.uint8))
+
+distances = simsimd.cdist(matrix1, matrix2, 
+    metric="hamming", # Unlike SciPy, SimSIMD doesn't divide by the number of dimensions
+    out_dtype="u8",   # so we can use `u8` instead of `f64` to save memory.
+    threads=0,        # Use all CPU cores with OpenMP.
+    dtype="b8",       # Override input argument type to `b8` eight-bit words.
+)
+```
+
+By default, the output distances will be stored in double-precision `f64` floating-point numbers.
+That behavior may not be space-efficient, especially if you are computing the hamming distance between short binary vectors, that will generally fit into 8x smaller `u8` or `u16` types.
+To override this behavior, use the `dtype` argument.
+
+### Helper Functions
+
+You can turn specific backends on or off depending on the exact environment.
+A common case may be avoiding AVX-512 on older AMD CPUs and [Intel Ice Lake](https://travisdowns.github.io/blog/2020/08/19/icl-avx512-freq.html) CPUs to ensure the CPU doesn't change the frequency license and throttle performance.
 
 ```py
-distances = simsimd.cdist(matrix1, matrix2, metric="cosine", threads=0)
+$ simsimd.get_capabilities()
+> {'serial': True, 'neon': False, 'sve': False, 'neon_f16': False, 'sve_f16': False, 'neon_bf16': False, 'sve_bf16': False, 'neon_i8': False, 'sve_i8': False, 'haswell': True, 'skylake': True, 'ice': True, 'genoa': True, 'sapphire': True}
+$ simsimd.disable_capability("sapphire")
+$ simsimd.enable_capability("sapphire")
 ```
 
 ### Using Python API with USearch
@@ -409,9 +467,9 @@ expected = np.inner(a_f32rounded, b_f32rounded)
 result = simd.inner(a_bf16, b_bf16, "bf16")
 ```
 
-### Dynamic Dispatch
+### Dynamic Dispatch in Rust
 
-SimSIMD provides a dynamic dispatch mechanism to select the most advanced micro-kernel for the current CPU.
+SimSIMD provides a [dynamic dispatch](#dynamic-dispatch) mechanism to select the most advanced micro-kernel for the current CPU.
 You can query supported backends and use the `SimSIMD::capabilities` function to select the best one.
 
 ```rust
@@ -448,7 +506,7 @@ console.log('Squared Euclidean Distance:', distance);
 ```
 
 Other numeric types and precision levels are supported as well.
-For double-precsion floating-point numbers, use `Float64Array`:
+For double-precision floating-point numbers, use `Float64Array`:
 
 ```js
 const vectorA = new Float64Array([1.0, 2.0, 3.0]);
@@ -457,11 +515,11 @@ const distance = cosine(vectorA, vectorB);
 ```
 
 When doing machine learning and vector search with high-dimensional vectors you may want to quantize them to 8-bit integers.
-You may want to project values from the $[-1, 1]$ range to the $[-100, 100]$ range and then cast them to `Uint8Array`:
+You may want to project values from the $[-1, 1]$ range to the $[-127, 127]$ range and then cast them to `Int8Array`:
 
 ```js
-const quantizedVectorA = new Uint8Array(vectorA.map(v => (v * 100)));
-const quantizedVectorB = new Uint8Array(vectorB.map(v => (v * 100)));
+const quantizedVectorA = new Int8Array(vectorA.map(v => (v * 127)));
+const quantizedVectorB = new Int8Array(vectorB.map(v => (v * 127)));
 const distance = cosine(quantizedVectorA, quantizedVectorB);
 ```
 
@@ -500,22 +558,25 @@ int main() {
     simsimd_f32_t vector_a[1536];
     simsimd_f32_t vector_b[1536];
     simsimd_metric_punned_t distance_function = simsimd_metric_punned(
-        simsimd_metric_cos_k, // Metric kind, like the angular cosine distance
+        simsimd_metric_cos_k,   // Metric kind, like the angular cosine distance
         simsimd_datatype_f32_k, // Data type, like: f16, f32, f64, i8, b8, and complex variants
-        simsimd_cap_any_k); // Which CPU capabilities are we allowed to use
+        simsimd_cap_any_k);     // Which CPU capabilities are we allowed to use
     simsimd_distance_t distance;
     distance_function(vector_a, vector_b, 1536, &distance);
     return 0;
 }
 ```
 
-### Dynamic Dispatch
+### Dynamic Dispatch in C
 
 To avoid hard-coding the backend, you can rely on `c/lib.c` to prepackage all possible backends in one binary, and select the most recent CPU features at runtime.
-That feature of the C library is called dynamic dispatch and is extensively used in the Python, JavaScript, and Rust bindings.
+That feature of the C library is called [dynamic dispatch](#dynamic-dispatch) and is extensively used in the Python, JavaScript, and Rust bindings.
 To test which CPU features are available on the machine at runtime, use the following APIs:
 
 ```c
+int uses_dynamic_dispatch = simsimd_uses_dynamic_dispatch(); // Check if dynamic dispatch was enabled
+simsimd_capability_t capabilities = simsimd_capabilities();  // Returns a bitmask
+
 int uses_neon = simsimd_uses_neon();
 int uses_sve = simsimd_uses_sve();
 int uses_haswell = simsimd_uses_haswell();
@@ -523,11 +584,9 @@ int uses_skylake = simsimd_uses_skylake();
 int uses_ice = simsimd_uses_ice();
 int uses_genoa = simsimd_uses_genoa();
 int uses_sapphire = simsimd_uses_sapphire();
-
-simsimd_capability_t capabilities = simsimd_capabilities();
 ```
 
-To differentiate between runtime and compile-time dispatch, define the following macro:
+To override compilation settings and switch between runtime and compile-time dispatch, define the following macro:
 
 ```c
 #define SIMSIMD_DYNAMIC_DISPATCH 1 // or 0
@@ -647,116 +706,345 @@ To explicitly disable half-precision support, define the following macro before
 #include <simsimd/simsimd.h>
 ```
 
-### Target Specific Backends
+### Compilation Settings and Debugging
+
+`SIMSIMD_DYNAMIC_DISPATCH`:
+
+> By default, SimSIMD is a header-only library.
+> But if you are running on different generations of devices, it makes sense to pre-compile the library for all supported generations at once, and dispatch at runtime.
+> This flag does just that and is used to produce the `simsimd.so` shared library, as well as the Python and other bindings.
+
+`SIMSIMD_TARGET_ARM` (`SIMSIMD_TARGET_NEON`, `SIMSIMD_TARGET_SVE`, `SIMSIMD_TARGET_SVE2`, `SIMSIMD_TARGET_NEON_F16`, `SIMSIMD_TARGET_SVE_F16`, `SIMSIMD_TARGET_NEON_BF16`, `SIMSIMD_TARGET_SVE_BF16`), `SIMSIMD_TARGET_X86` (`SIMSIMD_TARGET_HASWELL`, `SIMSIMD_TARGET_SKYLAKE`, `SIMSIMD_TARGET_ICE`, `SIMSIMD_TARGET_GENOA`, `SIMSIMD_TARGET_SAPPHIRE`): 
+
+> By default, SimSIMD automatically infers the target architecture and pre-compiles as many kernels as possible.
+> In some cases, you may want to explicitly disable some of the kernels.
+> Most often it's due to compiler support issues, like the lack of some recent intrinsics or low-precision numeric types.
+> In other cases, you may want to disable some kernels to speed up the compilation process and trim the binary size.
+
+`SIMSIMD_SQRT`, `SIMSIMD_RSQRT`, `SIMSIMD_LOG`:
+
+> By default, for __non__-SIMD backends, SimSIMD may use `libc` functions like `sqrt` and `log`.
+> Those are generally very accurate, but slow, and introduce a dependency on the C standard library.
+> To avoid that you can override those definitions with your custom implementations, like: `#define SIMSIMD_RSQRT(x) (1 / sqrt(x))`.
+
+## Algorithms & Design Decisions 📚
+
+In general there are a few principles that SimSIMD follows:
+
+- Avoid loop unrolling.
+- Never allocate memory.
+- Never throw exceptions or set `errno`.
+- Keep all function arguments the size of the pointer.
+- Avoid returning from public interfaces, use out-arguments instead.
+- Don't over-optimize for old CPUs and single- and double-precision floating-point numbers.
+- Prioritize mixed-precision and integer operations, and new ISA extensions.
+
+Last, but not the least - don't build unless there is a demand for it.
+So if you have a specific use-case, please open an issue or a pull request, and ideally, bring in more users with similar needs.
+
+### Cosine Similarity, Reciprocal Square Root, and Newton-Raphson Iteration
+
+The cosine similarity is the most common and straightforward metric used in machine learning and information retrieval.
+Interestingly, there are multiple ways to shoot yourself in the foot when computing it.
+The cosine similarity is the inverse of the cosine distance, which is the cosine of the angle between two vectors.
+
+```math
+\text{CosineSimilarity}(a, b) = \frac{a \cdot b}{\|a\| \cdot \|b\|}
+```
+
+```math
+\text{CosineDistance}(a, b) = 1 - \frac{a \cdot b}{\|a\| \cdot \|b\|}
+```
+
+In NumPy terms, SimSIMD implementation is similar to:
+
+```python
+import numpy as np
+
+def cos_numpy(a: np.ndarray, b: np.ndarray) -> float:
+    ab, a2, b2 = np.dot(a, b), np.dot(a, a), np.dot(b, b) # Fused in SimSIMD
+    if a2 == 0 and b2 == 0: result = 0                    # Same in SciPy
+    elif ab == 0: result = 1                              # Division by zero error in SciPy
+    else: result = 1 - ab / (sqrt(a2) * sqrt(b2))         # Bigger rounding error in SciPy
+    return result
+```
+
+In SciPy, however, the cosine distance is computed as `1 - ab / np.sqrt(a2 * b2)`.
+It handles the edge case of a zero and non-zero argument pair differently, resulting in a division by zero error.
+It's not only less efficient, but also less accurate, given how the reciprocal square roots are computed.
+The C standard library provides the `sqrt` function, which is generally very accurate, but slow.
+The `rsqrt` in-hardware implementations are faster, but have different accuracy characteristics.
+
+- SSE `rsqrtps` and AVX `vrsqrtps`: $1.5 \times 2^{-12}$ maximal error.
+- AVX-512 `vrsqrt14pd` instruction: $2^{-14}$ maximal error.
+- NEON `frsqrte` instruction has no clear error bounds.
+
+To overcome the limitations of the `rsqrt` instruction, SimSIMD uses the Newton-Raphson iteration to refine the initial estimate for high-precision floating-point numbers.
+It can be defined as:
+
+```math
+x_{n+1} = x_n \cdot (3 - x_n \cdot x_n) / 2
+```
+
+On 1536-dimensional inputs on Intel Sapphire Rapids CPU a single such iteration can result in a 2-3 orders of magnitude relative error reduction:
+
+| Datatype   |         NumPy Error | SimSIMD w/out Iteration |             SimSIMD |
+| :--------- | ------------------: | ----------------------: | ------------------: |
+| `bfloat16` | 1.89e-08 ± 1.59e-08 |     3.07e-07 ± 3.09e-07 | 3.53e-09 ± 2.70e-09 |
+| `float16`  | 1.67e-02 ± 1.44e-02 |     2.68e-05 ± 1.95e-05 | 2.02e-05 ± 1.39e-05 |
+| `float32`  | 2.21e-08 ± 1.65e-08 |     3.47e-07 ± 3.49e-07 | 3.77e-09 ± 2.84e-09 |
+| `float64`  | 0.00e+00 ± 0.00e+00 |     3.80e-07 ± 4.50e-07 | 1.35e-11 ± 1.85e-11 |
+
+### Curved Spaces, Mahalanobis Distance, and Bilinear Quadratic Forms
+
+The Mahalanobis distance is a generalization of the Euclidean distance, which takes into account the covariance of the data.
+It's very similar in its form to the bilinear form, which is a generalization of the dot product.
+
+```math
+\text{BilinearForm}(a, b, M) = a^T M b
+```
+
+```math
+\text{Mahalanobis}(a, b, M) = \sqrt{(a - b)^T M^{-1} (a - b)}
+```
+
+Bilinear Forms can be seen as one of the most important linear algebraic operations, surprisingly missing in BLAS and LAPACK.
+They are versatile and appear in various domains:
+
+- In Quantum Mechanics, the expectation value of an observable $A$ in a state $\psi$ is given by $\langle \psi | A | \psi \rangle$, which is a bilinear form.
+- In Machine Learning, in Support Vector Machines (SVMs), bilinear forms define kernel functions that measure similarity between data points.
+- In Differential Geometry, the metric tensor, which defines distances and angles on a manifold, is a bilinear form on the tangent space.
+- In Economics, payoff functions in certain Game Theoretic problems can be modeled as bilinear forms of players' strategies.
+- In Physics, interactions between electric and magnetic fields can be expressed using bilinear forms.
+
+Broad applications aside, the lack of a specialized primitive for bilinear forms in BLAS and LAPACK means significant performance overhead.
+A $vector * matrix * vector$ product is a scalar, whereas its constituent parts ($vector * matrix$ and $matrix * vector$) are vectors:
+
+- They need memory to be stored in: $O(n)$ allocation.
+- The data will be written to memory and read back, wasting CPU cycles.
+
+SimSIMD doesn't produce intermediate vector results, like `a @ M @ b`, but computes the bilinear form directly.
+
+### Set Intersection, Galloping, and Binary Search
+
+The set intersection operation is generally defined as the number of elements that are common between two sets, represented as sorted arrays of integers.
+The most common way to compute it is a linear scan:
+
+```c
+size_t intersection_size(int *a, int *b, size_t n, size_t m) {
+    size_t i = 0, j = 0, count = 0;
+    while (i < n && j < m) {
+        if (a[i] < b[j]) i++;
+        else if (a[i] > b[j]) j++;
+        else i++, j++, count++;
+    }
+    return count;
+}
+```
+
+Alternatively, one can use the binary search to find the elements in the second array that are present in the first one.
+On every step the checked region of the second array is halved, which is called the _galloping search_.
+It's faster, but only when large arrays of very different sizes are intersected.
+Third approach is to use the SIMD instructions to compare multiple elements at once:
+
+- Using string-intersection instructions on x86, like `pcmpestrm`.
+- Using integer-intersection instructions in AVX-512, like `vp2intersectd`.
+- Using vanilla equality checks present in all SIMD instruction sets.
+
+After benchmarking, the last approach was chosen, as it's the most flexible and often the fastest.
+
+### Complex Dot Products, Conjugate Dot Products, and Complex Numbers
+
+Complex dot products are a generalization of the dot product to complex numbers.
+They are supported by most BLAS packages, but almost never in mixed precision.
+SimSIMD defines `dot` and `vdot` kernels as:
+
+```math
+\text{dot}(a, b) = \sum_{i=0}^{n-1} a_i \cdot b_i
+```
+
+```math
+\text{vdot}(a, b) = \sum_{i=0}^{n-1} a_i \cdot \bar{b_i}
+```
+
+Where $\bar{b_i}$ is the complex conjugate of $b_i$.
+Putting that into Python code for scalar arrays:
+    
+```python
+def dot(a: List[number], b: List[number]) -> number:
+    a_real, a_imaginary = a[0::2], a[1::2]
+    b_real, b_imaginary = b[0::2], b[1::2]
+    ab_real, ab_imaginary = 0, 0
+    for ar, ai, br, bi in zip(a_real, a_imaginary, b_real, b_imaginary):
+        ab_real += ar * br - ai * bi
+        ab_imaginary += ar * bi + ai * br
+    return ab_real, ab_imaginary
+
+def vdot(a: List[number], b: List[number]) -> number:
+    a_real, a_imaginary = a[0::2], a[1::2]
+    b_real, b_imaginary = b[0::2], b[1::2]
+    ab_real, ab_imaginary = 0, 0
+    for ar, ai, br, bi in zip(a_real, a_imaginary, b_real, b_imaginary):
+        ab_real += ar * br + ai * bi
+        ab_imaginary += ar * bi - ai * br
+    return ab_real, ab_imaginary
+```
+
+### Logarithms in Kullback-Leibler & Jensen–Shannon Divergences
+
+The Kullback-Leibler divergence is a measure of how one probability distribution diverges from a second, expected probability distribution.
+Jensen-Shannon divergence is a symmetrized and smoothed version of the Kullback-Leibler divergence, which can be used as a distance metric between probability distributions.
+
+```math
+\text{KL}(P || Q) = \sum_{i} P(i) \log \frac{P(i)}{Q(i)}
+```
+
+```math
+\text{JS}(P, Q) = \frac{1}{2} \text{KL}(P || M) + \frac{1}{2} \text{KL}(Q || M), M = \frac{P + Q}{2}
+```
+
+Both functions are defined for non-negative numbers, and the logarithm is a key part of their computation.
+
+### Dynamic Dispatch
+
+Most popular software is precompiled and distributed with fairly conservative CPU optimizations, to ensure compatibility with older hardware.
+Database Management platforms, like ClickHouse, and Web Browsers, like Google Chrome,need to run on billions of devices, and they can't afford to be picky about the CPU features.
+For such users SimSIMD provides a dynamic dispatch mechanism, which selects the most advanced micro-kernel for the current CPU at runtime.
+
+<table>
+  <tr>
+    <th>Subset</th>
+    <th>F</th>
+    <th>CD</th>
+    <th>ER</th>
+    <th>PF</th>
+    <th>4FMAPS</th>
+    <th>4VNNIW</th>
+    <th>VPOPCNTDQ</th>
+    <th>VL</th>
+    <th>DQ</th>
+    <th>BW</th>
+    <th>IFMA</th>
+    <th>VBMI</th>
+    <th>VNNI</th>
+    <th>BF16</th>
+    <th>VBMI2</th>
+    <th>BITALG</th>
+    <th>VPCLMULQDQ</th>
+    <th>GFNI</th>
+    <th>VAES</th>
+    <th>VP2INTERSECT</th>
+    <th>FP16</th>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Xeon_Phi#Knights_Landing">Knights Landing</a> (Xeon Phi x200, 2016)</td>
+    <td colspan="2" rowspan="9" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="2" rowspan="2" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="17" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Xeon_Phi#Knights_Mill">Knights Mill</a> (Xeon Phi x205, 2017)</td>
+    <td colspan="3" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="14" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://en.wikipedia.org/wiki/Skylake_(microarchitecture)#Skylake-SP_(14_nm)_Scalable_Performance">Skylake-SP</a>, 
+      <a href="https://en.wikipedia.org/wiki/Skylake_(microarchitecture)#Mainstream_desktop_processors">Skylake-X</a> (2017)
+    </td>
+    <td colspan="4" rowspan="11" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+    <td rowspan="4" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+    <td colspan="3" rowspan="4" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="11" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Cannon_Lake_(microarchitecture)">Cannon Lake</a> (2018)</td>
+    <td colspan="2" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="9" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Cascade_Lake_(microarchitecture)">Cascade Lake</a> (2019)</td>
+    <td colspan="2" rowspan="2" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+    <td rowspan="2" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="8" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Cooper_Lake_(microarchitecture)">Cooper Lake</a> (2020)</td>
+    <td style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="7" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Ice_Lake_(microarchitecture)">Ice Lake</a> (2019)</td>
+    <td colspan="7" rowspan="3" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td rowspan="3" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+    <td colspan="5" rowspan="3" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="2" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Tiger_Lake_(microarchitecture)">Tiger Lake</a> (2020)</td>
+    <td style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Rocket_Lake">Rocket Lake</a> (2021)</td>
+    <td colspan="2" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Alder_Lake">Alder Lake</a> (2021)</td>
+    <td colspan="2" style="background:#FFB;color:black;vertical-align:middle;text-align:center;">Partial</td>
+    <td colspan="15" style="background:#FFB;color:black;vertical-align:middle;text-align:center;">Partial</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Zen_4">Zen 4</a> (2022)</td>
+    <td colspan="2" rowspan="3" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="13" rowspan="3" style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td colspan="2" style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Sapphire_Rapids_(microprocessor)">Sapphire Rapids</a> (2023)</td>
+    <td style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+    <td style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+  </tr>
+  <tr>
+    <td><a href="https://en.wikipedia.org/wiki/Zen_5">Zen 5</a> (2024)</td>
+    <td style="background:#9EFF9E;color:black;vertical-align:middle;text-align:center;">Yes</td>
+    <td style="background:#FFC7C7;color:black;vertical-align:middle;text-align:center;">No</td>
+  </tr>
+</table>
+
+You can compile SimSIMD on an old CPU, like Intel Haswell, and run it on a new one, like AMD Genoa, and it will automatically use the most advanced instructions available.
+Reverse is also true, you can compile on a new CPU and run on an old one, and it will automatically fall back to the most basic instructions.
+Moreover, the very first time you prove for CPU capabilities with `simsimd_capabilities()`, it initializes the dynamic dispatch mechanism, and all subsequent calls will be faster and won't face race conditions in multi-threaded environments.
+
+## Target Specific Backends
 
 SimSIMD exposes all kernels for all backends, and you can select the most advanced one for the current CPU without relying on built-in dispatch mechanisms.
+That's handy for testing and benchmarking, but also in case you want to dispatch a very specific kernel for a very specific CPU, bypassing SimSIMD assignment logic.
 All of the function names follow the same pattern: `simsimd_{function}_{type}_{backend}`.
 
-- The backend can be `serial`, `haswell`, `skylake`, `ice`, `sapphire`, `neon`, or `sve`.
-- The type can be `f64`, `f32`, `f16`, `f64c`, `f32c`, `f16c`, `i8`, or `b8`.
-- The function can be `dot`, `vdot`, `cos`, `l2sq`, `hamming`, `jaccard`, `kl`, or `js`.
+- The backend can be `serial`, `haswell`, `skylake`, `ice`, `genoa`, `sapphire`, `neon`, or `sve`.
+- The type can be `f64`, `f32`, `f16`, `bf16`, `f64c`, `f32c`, `f16c`, `bf16c`, `i8`, or `b8`.
+- The function can be `dot`, `vdot`, `cos`, `l2sq`, `hamming`, `jaccard`, `kl`, `js`, or `intersect`.
 
 To avoid hard-coding the backend, you can use the `simsimd_metric_punned_t` to pun the function pointer and the `simsimd_capabilities` function to get the available backends at runtime.
+To match all the function names, consider a RegEx:
 
-```c
-simsimd_dot_f64_sve
-simsimd_cos_f64_sve
-simsimd_l2sq_f64_sve
-simsimd_dot_f64_skylake
-simsimd_cos_f64_skylake
-simsimd_l2sq_f64_skylake
-simsimd_dot_f64_serial
-simsimd_cos_f64_serial
-simsimd_l2sq_f64_serial
-simsimd_js_f64_serial
-simsimd_kl_f64_serial
-simsimd_dot_f32_sve
-simsimd_cos_f32_sve
-simsimd_l2sq_f32_sve
-simsimd_dot_f32_neon
-simsimd_cos_f32_neon
-simsimd_l2sq_f32_neon
-simsimd_js_f32_neon
-simsimd_kl_f32_neon
-simsimd_dot_f32_skylake
-simsimd_cos_f32_skylake
-simsimd_l2sq_f32_skylake
-simsimd_js_f32_skylake
-simsimd_kl_f32_skylake
-simsimd_dot_f32_serial
-simsimd_cos_f32_serial
-simsimd_l2sq_f32_serial
-simsimd_js_f32_serial
-simsimd_kl_f32_serial
-simsimd_dot_f16_sve
-simsimd_cos_f16_sve
-simsimd_l2sq_f16_sve
-simsimd_dot_f16_neon
-simsimd_cos_f16_neon
-simsimd_l2sq_f16_neon
-simsimd_js_f16_neon
-simsimd_kl_f16_neon
-simsimd_dot_f16_sapphire
-simsimd_cos_f16_sapphire
-simsimd_l2sq_f16_sapphire
-simsimd_js_f16_sapphire
-simsimd_kl_f16_sapphire
-simsimd_dot_f16_haswell
-simsimd_cos_f16_haswell
-simsimd_l2sq_f16_haswell
-simsimd_js_f16_haswell
-simsimd_kl_f16_haswell
-simsimd_dot_f16_serial
-simsimd_cos_f16_serial
-simsimd_l2sq_f16_serial
-simsimd_js_f16_serial
-simsimd_kl_f16_serial
-simsimd_cos_i8_neon
-simsimd_cos_i8_neon
-simsimd_l2sq_i8_neon
-simsimd_cos_i8_ice
-simsimd_cos_i8_ice
-simsimd_l2sq_i8_ice
-simsimd_cos_i8_haswell
-simsimd_cos_i8_haswell
-simsimd_l2sq_i8_haswell
-simsimd_cos_i8_serial
-simsimd_cos_i8_serial
-simsimd_l2sq_i8_serial
-simsimd_hamming_b8_sve
-simsimd_jaccard_b8_sve
-simsimd_hamming_b8_neon
-simsimd_jaccard_b8_neon
-simsimd_hamming_b8_ice
-simsimd_jaccard_b8_ice
-simsimd_hamming_b8_haswell
-simsimd_jaccard_b8_haswell
-simsimd_hamming_b8_serial
-simsimd_jaccard_b8_serial
-simsimd_dot_f32c_sve
-simsimd_vdot_f32c_sve
-simsimd_dot_f32c_neon
-simsimd_vdot_f32c_neon
-simsimd_dot_f32c_haswell
-simsimd_vdot_f32c_haswell
-simsimd_dot_f32c_skylake
-simsimd_vdot_f32c_skylake
-simsimd_dot_f32c_serial
-simsimd_vdot_f32c_serial
-simsimd_dot_f64c_sve
-simsimd_vdot_f64c_sve
-simsimd_dot_f64c_skylake
-simsimd_vdot_f64c_skylake
-simsimd_dot_f64c_serial
-simsimd_vdot_f64c_serial
-simsimd_dot_f16c_sve
-simsimd_vdot_f16c_sve
-simsimd_dot_f16c_neon
-simsimd_vdot_f16c_neon
-simsimd_dot_f16c_haswell
-simsimd_vdot_f16c_haswell
-simsimd_dot_f16c_sapphire
-simsimd_vdot_f16c_sapphire
-simsimd_dot_f16c_serial
-simsimd_vdot_f16c_serial
-```
+```regex
+SIMSIMD_PUBLIC void simsimd_\w+_\w+_\w+\(
+```
+
+On Linux, you can use the following command to list all unique functions:
+
+```sh
+$ grep -oP 'SIMSIMD_PUBLIC void simsimd_\w+_\w+_\w+\(' include/simsimd/*.h | sort | uniq
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_hamming_b8_haswell(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_hamming_b8_ice(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_hamming_b8_neon(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_hamming_b8_serial(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_hamming_b8_sve(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_jaccard_b8_haswell(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_jaccard_b8_ice(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_jaccard_b8_neon(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_jaccard_b8_serial(
+> include/simsimd/binary.h:SIMSIMD_PUBLIC void simsimd_jaccard_b8_sve(
+```