Docs: Inconsistencies & typos

Author: ashvardanian

CONTRIBUTING.md

@@ -49,7 +49,7 @@ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100
 sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100
 ```
 
-To compile with the default Apple Clang on MacOS, use:
+To compile with the default Apple Clang on macOS, use:
 
 ```sh
 brew install openblas
@@ -63,8 +63,8 @@ cmake -D CMAKE_BUILD_TYPE=Release \
 cmake --build build_release --config Release
 ```
 
-On MacOS it's recommended to use Homebrew and install Clang, as opposed to "Apple Clang".
-Replacing the default compiler across the entire system is not recommended on MacOS, as it may break the system, but you can pass it as an environment variable:
+On macOS it's recommended to use Homebrew and install Clang, as opposed to "Apple Clang".
+Replacing the default compiler across the entire system is not recommended on macOS, as it may break the system, but you can pass it as an environment variable:
 
 ```sh
 brew install llvm openblas
@@ -124,7 +124,7 @@ Here, `-s` will output the logs.
 The `-x` will stop on the first failure.
 The `-Wd` will silence overflows and runtime warnings.
 
-When building on MacOS, same as with C/C++, use non-Apple Clang version:
+When building on macOS, same as with C/C++, use non-Apple Clang version:
 
 ```sh
 brew install llvm
@@ -174,7 +174,7 @@ $ python scripts/bench_vectors.py --help
 
 
 Before merging your changes you may want to test your changes against the entire matrix of Python versions USearch supports.
-For that you need the `cibuildwheel`, which is tricky to use on MacOS and Windows, as it would target just the local environment.
+For that you need the `cibuildwheel`, which is tricky to use on macOS and Windows, as it would target just the local environment.
 Still, if you have Docker running on any desktop OS, you can use it to build and test the Python bindings for all Python versions for Linux:
 
 ```sh
@@ -184,7 +184,7 @@ cibuildwheel --platform linux                   # works on any OS and builds all
 cibuildwheel --platform linux --archs x86_64    # 64-bit x86, the most common on desktop and servers
 cibuildwheel --platform linux --archs aarch64   # 64-bit Arm for mobile devices, Apple M-series, and AWS Graviton
 cibuildwheel --platform linux --archs i686      # 32-bit Linux
-cibuildwheel --platform macos                   # works only on MacOS
+cibuildwheel --platform macos                   # works only on macOS
 cibuildwheel --platform windows                 # works only on Windows
 ```
 
@@ -194,7 +194,7 @@ You may need root privileges for multi-architecture builds:
 sudo $(which cibuildwheel) --platform linux
 ```
 
-On Windows and MacOS, to avoid frequent path resolution issues, you may want to use:
+On Windows and macOS, to avoid frequent path resolution issues, you may want to use:
 
 ```sh
 python -m cibuildwheel --platform windows
@@ -217,7 +217,7 @@ If you don't have the environment configured, here are the [installation options
 
 ```sh
 wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # Linux
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash  # MacOS
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash  # macOS
 ```
 
 Install dependencies:
@@ -242,7 +242,7 @@ If you don't have the environment configured, here are [installation options](ht
 
 ```sh
 wget -qO- https://deno.land/x/install/install.sh | sh # Linux
-curl -fsSL https://deno.land/install.sh | sh          # MacOS
+curl -fsSL https://deno.land/install.sh | sh          # macOS
 irm https://deno.land/install.ps1 | iex               # Windows
 ```
 

README.md

@@ -1,6 +1,6 @@
 ![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.
+Computing dot-products, similarity measures, and distances between low- and high-dimensional vectors is ubiquitous in Machine Learning, Scientific Computing, Geospatial Analysis, and Information Retrieval.
 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.
@@ -32,7 +32,7 @@ SimSIMD provides an alternative.
     <img alt="GitHub Actions Windows" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=Windows&logo=windows&color=blue">
 </a>
 <a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
-    <img alt="GitHub Actions MacOS" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=MacOS&logo=apple&color=blue">
+    <img alt="GitHub Actions macOS" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=macOS&logo=apple&color=blue">
 </a>
 <a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
     <img alt="GitHub Actions CentOS Linux" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=CentOS&logo=centos&color=blue">
@@ -43,7 +43,7 @@ SimSIMD provides an alternative.
 ## Features
 
 __SimSIMD__ (Arabic: "سيمسيم دي") is a mixed-precision math library of __over 350 SIMD-optimized kernels__ extensively used in AI, Search, and DBMS workloads.
-Named after the iconic ["Open Sesame"](https://en.wikipedia.org/wiki/Open_sesame) command that opened doors to treasure in _Ali Baba and the Forty Thieves_, SimSimd can help you 10x the cost-efficiency of your computational pipelines.
+Named after the iconic ["Open Sesame"](https://en.wikipedia.org/wiki/Open_sesame) command that opened doors to treasure in _Ali Baba and the Forty Thieves_, SimSIMD can help you 10x the cost-efficiency of your computational pipelines.
 Implemented distance functions include:
 
 - Euclidean (L2) and Cosine (Angular) spatial distances for Vector Search. _[docs][docs-spatial]_
@@ -85,7 +85,7 @@ You can learn more about the technical implementation details in the following b
 
 - [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).
-- [Substitutes LibC's `sqrt` with Newton Raphson iterations](https://github.com/ashvardanian/SimSIMD/releases/tag/v5.4.0).
+- [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/).
@@ -625,13 +625,13 @@ fn main() {
     let vector_a: Vec<f32> = vec![1.0, 2.0, 3.0];
     let vector_b: Vec<f32> = vec![4.0, 5.0, 6.0];
 
-    // Compute the cosine similarity between vector_a and vector_b
-    let cosine_similarity = f32::cosine(&vector_a, &vector_b)
+    // Compute the cosine distance between vectors
+    let cosine_distance = f32::cosine(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
-    println!("Cosine Similarity: {}", cosine_similarity);
+    println!("Cosine Distance: {}", cosine_distance);
 
-    // Compute the squared Euclidean distance between vector_a and vector_b
+    // Compute the squared Euclidean distance between vectors
     let sq_euclidean_distance = f32::sqeuclidean(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
@@ -648,16 +648,17 @@ use simsimd::SpatialSimilarity;
 use simsimd::ComplexProducts;
 
 fn main() {
+    // Complex vectors have interleaved real & imaginary components
     let vector_a: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0];
     let vector_b: Vec<f32> = vec![5.0, 6.0, 7.0, 8.0];
 
-    // Compute the inner product between vector_a and vector_b
+    // Compute the inner product between vectors
     let inner_product = SpatialSimilarity::dot(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
     println!("Inner Product: {}", inner_product);
 
-    // Compute the complex inner product between complex_vector_a and complex_vector_b
+    // Compute the complex inner product between vectors
     let complex_inner_product = ComplexProducts::dot(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
@@ -705,13 +706,13 @@ fn main() {
     let vector_a = &[0b11110000, 0b00001111, 0b10101010];
     let vector_b = &[0b11110000, 0b00001111, 0b01010101];
 
-    // Compute the Hamming distance between vector_a and vector_b
+    // Compute the Hamming distance between vectors
     let hamming_distance = u8::hamming(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
     println!("Hamming Distance: {}", hamming_distance);
 
-    // Compute the Jaccard distance between vector_a and vector_b
+    // Compute the Jaccard distance between vectors
     let jaccard_distance = u8::jaccard(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
@@ -734,11 +735,11 @@ fn main() {
     let vector_a: Vec<f16> = vec![1.0, 2.0, 3.0].iter().map(|&x| f16::from_f32(x)).collect();
     let vector_b: Vec<f16> = vec![4.0, 5.0, 6.0].iter().map(|&x| f16::from_f32(x)).collect();
 
-    // Compute the cosine similarity
-    let cosine_similarity = f16::cosine(&vector_a, &vector_b)
+    // Compute the cosine distance
+    let cosine_distance = f16::cosine(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
-    println!("Cosine Similarity: {}", cosine_similarity);
+    println!("Cosine Distance: {}", cosine_distance);
 
     // Direct bit manipulation
     let half = f16::from_f32(3.14159);
@@ -764,10 +765,10 @@ fn main() {
     let buffer_a: &[SimF16] = unsafe { std::slice::from_raw_parts(vector_a.as_ptr() as *const SimF16, vector_a.len()) };
     let buffer_b: &[SimF16] = unsafe { std::slice::from_raw_parts(vector_b.as_ptr() as *const SimF16, vector_b.len()) };
 
-    let cosine_similarity = SimF16::cosine(buffer_a, buffer_b)
+    let cosine_distance = SimF16::cosine(buffer_a, buffer_b)
         .expect("Vectors must be of the same length");
 
-    println!("Cosine Similarity: {}", cosine_similarity);
+    println!("Cosine Distance: {}", cosine_distance);
 }
 ```
 
@@ -787,10 +788,10 @@ fn main() {
     let vector_b: Vec<bf16> = vec![4.0, 5.0, 6.0].iter().map(|&x| bf16::from_f32(x)).collect();
 
     // Compute the cosine similarity
-    let cosine_similarity = bf16::cosine(&vector_a, &vector_b)
+    let cosine_distance = bf16::cosine(&vector_a, &vector_b)
         .expect("Vectors must be of the same length");
 
-    println!("Cosine Similarity: {}", cosine_similarity);
+    println!("Cosine Distance: {}", cosine_distance);
 
     // Direct bit manipulation
     let brain_half = bf16::from_f32(3.14159);
@@ -899,8 +900,8 @@ import SimSIMD
 let vectorA: [Int8] = [1, 2, 3]
 let vectorB: [Int8] = [4, 5, 6]
 
-let cosineSimilarity = vectorA.cosine(vectorB)  // Computes the cosine similarity
 let dotProduct = vectorA.dot(vectorB)           // Computes the dot product
+let cosineDistance = vectorA.cosine(vectorB)    // Computes the cosine distance
 let sqEuclidean = vectorA.sqeuclidean(vectorB)  // Computes the squared Euclidean distance
 ```
 

c/lib.c

@@ -18,7 +18,7 @@
  *
  *  - Linux: everything is available in GCC 12+ and Clang 16+.
  *  - Windows - MSVC: everything except Sapphire Rapids and ARM SVE.
- *  - MacOS - Apple Clang: only Arm NEON and x86 AVX2 Haswell extensions are available.
+ *  - macOS - Apple Clang: only Arm NEON and x86 AVX2 Haswell extensions are available.
  */
 #if !defined(SIMSIMD_TARGET_NEON) && (defined(__APPLE__) || defined(__linux__))
 #define SIMSIMD_TARGET_NEON 1

golang/bench_test.go

@@ -6,15 +6,16 @@ import (
 	"testing"
 )
 
-func cosineSimilarity(a, b []float32) float32 {
+func cosineDistance(a, b []float32) float32 {
 	var dotProduct float32
 	var normA, normB float32
 	for i := range a {
 		dotProduct += a[i] * b[i]
 		normA += a[i] * a[i]
 		normB += b[i] * b[i]
 	}
-	return dotProduct / (float32(math.Sqrt(float64(normA))) * float32(math.Sqrt(float64(normB))))
+	sim := dotProduct / (float32(math.Sqrt(float64(normA))) * float32(math.Sqrt(float64(normB))))
+	return 1 - sim
 }
 
 func generateRandomVector(dim int) []float32 {
@@ -25,16 +26,16 @@ func generateRandomVector(dim int) []float32 {
 	return vec
 }
 
-func BenchmarkCosineSimilarityNative(b *testing.B) {
-    first, second := generateRandomVector(1536), generateRandomVector(1536)
-    for i := 0; i < b.N; i++ {
-        cosineSimilarity(first, second)
-    }
+func BenchmarkCosineDistanceNative(b *testing.B) {
+	first, second := generateRandomVector(1536), generateRandomVector(1536)
+	for i := 0; i < b.N; i++ {
+		cosineDistance(first, second)
+	}
 }
 
-func BenchmarkCosineSimilaritySIMD(b *testing.B) {
-    first, second := generateRandomVector(1536), generateRandomVector(1536)
-    for i := 0; i < b.N; i++ {
-        CosineF32(first, second)
-    }
-}
+func BenchmarkCosineDistanceSIMD(b *testing.B) {
+	first, second := generateRandomVector(1536), generateRandomVector(1536)
+	for i := 0; i < b.N; i++ {
+		CosineF32(first, second)
+	}
+}

golang/simsimd.go

@@ -53,7 +53,7 @@ func InnerF32(a, b []float32) float32 {
 	return float32(C.inner_f32((*C.simsimd_f32_t)(&a[0]), (*C.simsimd_f32_t)(&b[0]), C.simsimd_size_t(len(a))))
 }
 
-// SqEuclideanI8 computes the squared euclidean similarity between two i8 vectors using the most suitable SIMD instruction set available.
+// SqEuclideanI8 computes the squared Euclidean distance between two i8 vectors using the most suitable SIMD instruction set available.
 func SqEuclideanI8(a, b []int8) float32 {
 	if len(a) != len(b) {
 		panic("both vectors must have the same length")
@@ -62,7 +62,7 @@ func SqEuclideanI8(a, b []int8) float32 {
 	return float32(C.sqeuclidean_i8((*C.simsimd_i8_t)(&a[0]), (*C.simsimd_i8_t)(&b[0]), C.simsimd_size_t(len(a))))
 }
 
-// SqEuclideanF32 computes the squared euclidean similarity between two f32 vectors using the most suitable SIMD instruction set available.
+// SqEuclideanF32 computes the squared Euclidean distance between two f32 vectors using the most suitable SIMD instruction set available.
 func SqEuclideanF32(a, b []float32) float32 {
 	if len(a) != len(b) {
 		panic("both vectors must have the same length")

golang/unit_test.go

@@ -10,7 +10,7 @@ func TestCosineI8(t *testing.T) {
 	b := []int8{0, 1}
 
 	result := CosineI8(a, b)
-	expected := float32(1.0) // Cosine similarity of orthogonal vectors is 0
+    expected := float32(1.0) // Cosine distance of orthogonal vectors is 1
 	if math.Abs(float64(result-expected)) > 1e-3 {
 		t.Errorf("Expected %v, got %v", expected, result)
 	}
@@ -21,7 +21,7 @@ func TestCosineF32(t *testing.T) {
 	b := []float32{0, 1}
 
 	result := CosineF32(a, b)
-	expected := float32(1.0) // Cosine similarity of orthogonal vectors is 0
+    expected := float32(1.0) // Cosine distance of orthogonal vectors is 1
 	if math.Abs(float64(result-expected)) > 1e-3 {
 		t.Errorf("Expected %v, got %v", expected, result)
 	}

include/simsimd/binary.h

@@ -6,7 +6,7 @@
  *
  *  Contains:
  *  - Hamming distance
- *  - Jaccard similarity (Tanimoto coefficient)
+ *  - Jaccard distance (Tanimoto coefficient)
  *
  *  For hardware architectures:
  *  - Arm: NEON, SVE
@@ -19,7 +19,7 @@
  *  - Lookup tables, mostly using nibbles (4-bit lookups)
  *  - Harley-Seal population counts: https://arxiv.org/pdf/1611.07612
  *
- *  On binary vectors, when computing Jaccard similarity we can clearly see how the CPU struggles
+ *  On binary vectors, when computing Jaccard distance we can clearly see how the CPU struggles
  *  to compute that many population counts. There are several instructions we should keep in mind
  *  for future optimizations:
  *

include/simsimd/geospatial.h

@@ -1,6 +1,6 @@
 /**
  *  @file       geospatial.h
- *  @brief      SIMD-accelerated Geo-Spatial distance functions.
+ *  @brief      SIMD-accelerated Geospatial distance functions.
  *  @author     Ash Vardanian
  *  @date       July 1, 2023
  *

include/simsimd/mesh.h

@@ -15,7 +15,7 @@
  *  - 16-bit brain-floating point
  *
  *  For hardware architectures:
- *  - Arm: Neon
+ *  - Arm: NEON
  *  - x86: Genoa, Sapphire
  *
  *  x86 intrinsics: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/

include/simsimd/simsimd.h

@@ -26,7 +26,7 @@
  *
  *  Intel Palm Cove was an irrelevant intermediate release extending Skylake with IFMA and VBMI.
  *  Intel Willow Cove was an irrelevant intermediate release extending Sunny Cove with VP2INTERSECT,
- *  that aren't supported by any other CPU built to date... and those are only available in Tiger Lake laptops.
+ *  which are not supported by other CPUs to date and are only available in Tiger Lake laptops.
  *  Intel Cooper Lake was the only intermediary platform, that supported BF16, but not FP16.
  *  It's mostly used in 4-socket and 8-socket high-memory configurations.
  *
@@ -80,7 +80,7 @@
  *    The N2 core is very similar to V2 and is used by Microsoft @b Cobalt.
  *    https://developer.arm.com/Processors/Neoverse%20N2
  *
- *  On Consumer side, Apple is the biggest player with mobile @b A chips and desktop @b M chips.
+ *  On the consumer side, Apple is the biggest player with mobile @b A chips and desktop @b M chips.
  *  The M1 implements Armv8.5-A, both M2 and M3 implement Armv8.6-A, and M4 is expected to have Armv9.1-A.
  */