vector-qsort 0.1.0__tar.gz

vector_qsort-0.1.0/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

vector_qsort-0.1.0/CMakeLists.txt

@@ -0,0 +1,45 @@
+cmake_minimum_required(VERSION 3.15)
+project(vector_qsort LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+set(HWY_ENABLE_TESTS OFF CACHE BOOL "" FORCE)
+set(HWY_ENABLE_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(HWY_ENABLE_CONTRIB ON CACHE BOOL "" FORCE)
+
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../vendor/highway/CMakeLists.txt")
+  add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/../vendor/highway" "${CMAKE_CURRENT_BINARY_DIR}/highway_build" EXCLUDE_FROM_ALL)
+elseif(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/vendor/highway/CMakeLists.txt")
+  add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/vendor/highway" "${CMAKE_CURRENT_BINARY_DIR}/highway_build" EXCLUDE_FROM_ALL)
+else()
+  include(FetchContent)
+  FetchContent_Declare(
+    highway
+    GIT_REPOSITORY https://github.com/google/highway.git
+    GIT_TAG master
+    GIT_SHALLOW TRUE
+  )
+  FetchContent_MakeAvailable(highway)
+endif()
+
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../core/vqsort.h")
+  include_directories("${CMAKE_CURRENT_SOURCE_DIR}/../core")
+endif()
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/include")
+  include_directories("${CMAKE_CURRENT_SOURCE_DIR}/include")
+endif()
+
+find_package(Python 3.9 COMPONENTS Interpreter Development.Module REQUIRED)
+find_package(nanobind CONFIG REQUIRED)
+
+nanobind_add_module(_vector_qsort
+  binding.cc
+)
+
+target_link_libraries(_vector_qsort PRIVATE
+  hwy
+  hwy_contrib
+)
+
+install(TARGETS _vector_qsort LIBRARY DESTINATION vector_qsort)

vector_qsort-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth HM (https://h3manth.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vector_qsort-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.2
+Name: vector-qsort
+Version: 0.1.0
+Summary: Vectorized quicksort for NumPy arrays using Google Highway SIMD.
+Author-Email: Hemanth HM <hemanth@h3manth.com>
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# vector-qsort
+
+Vectorized quicksort for NumPy arrays using Google Highway SIMD.
+
+```bash
+pip install vector-qsort
+```
+
+## Quick start
+
+```python
+import numpy as np
+import vector_qsort
+
+data = np.array([3.14, -1.5, 42.0, 0.0, -100.5, 2.71], dtype=np.float32)
+
+# In-place SIMD sort
+vector_qsort.sort(data)
+# array([-100.5, -1.5, 0.0, 2.71, 3.14, 42.0], dtype=float32)
+
+# Descending
+vector_qsort.sort(data, desc=True)
+
+# Non-mutating copy
+sorted_data = vector_qsort.sorted(data)
+```
+
+`sort()` sorts 1D contiguous arrays in place with zero copies. `sorted()` returns a sorted copy. Supports `float32`, `float64`, `int32`, `uint32`, `int64`, `uint64`, `int16`, and `uint16`.
+
+## Benchmarks
+
+Measured on Apple Silicon (ARM NEON) vs NumPy's native in-place `np.sort()`:
+
+```bash
+python bench/bench_sort.py
+```
+
+| Dtype | Size | Distribution | NumPy (median) | vector-qsort | Speedup |
+|---|---|---|---|---|---|
+| `float32` | 100,000 | Random | 1.14 ms | **0.73 ms** | **1.57x** |
+| `float32` | 5,000,000 | Random | 81.97 ms | **50.39 ms** | **1.63x** |
+| `float64` | 100,000 | Random | 2.25 ms | **1.33 ms** | **1.70x** |
+| `float64` | 5,000,000 | Plateau | 39.40 ms | **18.04 ms** | **2.18x** |
+
+## Note on scalar sorts
+
+Modern scalar sorts like `driftsort` and `ipnsort` excel at generic types and presorted run-detection. `vector-qsort` is designed specifically for raw numeric throughput on contiguous buffers by saturating SIMD vector lanes.
+
+## License
+
+MIT © [Hemanth.HM](https://h3manth.com)

vector_qsort-0.1.0/README.md

@@ -0,0 +1,51 @@
+# vector-qsort
+
+Vectorized quicksort for NumPy arrays using Google Highway SIMD.
+
+```bash
+pip install vector-qsort
+```
+
+## Quick start
+
+```python
+import numpy as np
+import vector_qsort
+
+data = np.array([3.14, -1.5, 42.0, 0.0, -100.5, 2.71], dtype=np.float32)
+
+# In-place SIMD sort
+vector_qsort.sort(data)
+# array([-100.5, -1.5, 0.0, 2.71, 3.14, 42.0], dtype=float32)
+
+# Descending
+vector_qsort.sort(data, desc=True)
+
+# Non-mutating copy
+sorted_data = vector_qsort.sorted(data)
+```
+
+`sort()` sorts 1D contiguous arrays in place with zero copies. `sorted()` returns a sorted copy. Supports `float32`, `float64`, `int32`, `uint32`, `int64`, `uint64`, `int16`, and `uint16`.
+
+## Benchmarks
+
+Measured on Apple Silicon (ARM NEON) vs NumPy's native in-place `np.sort()`:
+
+```bash
+python bench/bench_sort.py
+```
+
+| Dtype | Size | Distribution | NumPy (median) | vector-qsort | Speedup |
+|---|---|---|---|---|---|
+| `float32` | 100,000 | Random | 1.14 ms | **0.73 ms** | **1.57x** |
+| `float32` | 5,000,000 | Random | 81.97 ms | **50.39 ms** | **1.63x** |
+| `float64` | 100,000 | Random | 2.25 ms | **1.33 ms** | **1.70x** |
+| `float64` | 5,000,000 | Plateau | 39.40 ms | **18.04 ms** | **2.18x** |
+
+## Note on scalar sorts
+
+Modern scalar sorts like `driftsort` and `ipnsort` excel at generic types and presorted run-detection. `vector-qsort` is designed specifically for raw numeric throughput on contiguous buffers by saturating SIMD vector lanes.
+
+## License
+
+MIT © [Hemanth.HM](https://h3manth.com)

vector_qsort-0.1.0/bench/bench_sort.py

@@ -0,0 +1,94 @@
+import time
+import numpy as np
+import vector_qsort
+
+def generate_data(dtype, size, distribution):
+    rng = np.random.default_rng(42)
+    if distribution == "random":
+        if np.issubdtype(dtype, np.floating):
+            return rng.standard_normal(size).astype(dtype)
+        else:
+            return rng.integers(-1_000_000, 1_000_000, size=size, dtype=dtype)
+    elif distribution == "sorted":
+        return np.arange(size, dtype=dtype)
+    elif distribution == "reverse":
+        return np.arange(size, 0, -1, dtype=dtype)
+    elif distribution == "plateau":
+        return (np.arange(size) % 10).astype(dtype)
+    raise ValueError(f"Unknown distribution: {distribution}")
+
+def run_benchmark(sort_fn, master_array, iterations, warmup=5):
+    total = warmup + iterations
+    copies = [master_array.copy() for _ in range(total)]
+
+    # Warmup
+    for i in range(warmup):
+        sort_fn(copies[i])
+
+    # Measure
+    times = []
+    for i in range(warmup, total):
+        target = copies[i]
+        t0 = time.perf_counter_ns()
+        sort_fn(target)
+        t1 = time.perf_counter_ns()
+        times.append((t1 - t0) / 1e6)  # ms
+
+    times.sort()
+    median = times[len(times) // 2]
+    min_time = times[0]
+    p95 = times[int(len(times) * 0.95)]
+    return median, min_time, p95
+
+def main():
+    print("=" * 80)
+    print("  vector-qsort vs NumPy np.sort() In-Place Benchmark")
+    print(f"  NumPy: {np.__version__} | Python: 3.14 | Platform: Apple Silicon (NEON)")
+    print("=" * 80)
+    print("")
+
+    sizes = [1_000, 10_000, 100_000, 1_000_000, 5_000_000]
+    dtypes = [np.float32, np.int32, np.float64]
+    distributions = ["random", "plateau"]
+
+    header = (
+        f"| {'Dtype':<12}"
+        f"| {'Size':<12}"
+        f"| {'Distribution':<14}"
+        f"| {'NumPy (median)':<16}"
+        f"| {'vqsort (median)':<17}"
+        f"| {'Speedup':<10}"
+        f"| {'M elem/s':<10} |"
+    )
+    print(header)
+    print("|" + "-" * 13 + "|" + "-" * 12 + "|" + "-" * 15 + "|" + "-" * 17 + "|" + "-" * 18 + "|" + "-" * 11 + "|" + "-" * 11 + "|")
+
+    for dt in dtypes:
+        dt_name = dt.__name__
+        for size in sizes:
+            for dist in distributions:
+                master = generate_data(dt, size, dist)
+                iters = 10 if size >= 1_000_000 else (25 if size >= 100_000 else 50)
+
+                # arr.sort() is NumPy's in-place sort
+                np_med, _, _ = run_benchmark(lambda a: a.sort(), master, iters)
+                vq_med, _, _ = run_benchmark(lambda a: vector_qsort.sort(a), master, iters)
+
+                speedup = np_med / vq_med
+                throughput = (size / 1e6) / (vq_med / 1000)
+
+                print(
+                    f"| {dt_name:<12}"
+                    f"| {size:<12,}"
+                    f"| {dist:<14}"
+                    f"| {np_med:>8.3f} ms     "
+                    f"| {vq_med:>8.3f} ms      "
+                    f"| {speedup:>6.2f}x   "
+                    f"| {throughput:>7.1f} M/s |"
+                )
+
+    print("")
+    print("Done.")
+
+if __name__ == "__main__":
+    main()

vector_qsort-0.1.0/binding.cc

@@ -0,0 +1,50 @@
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include "vqsort.h"
+
+namespace nb = nanobind;
+
+template <typename T>
+void sort_data(nb::ndarray<nb::c_contig> array, bool desc) {
+  T* ptr = static_cast<T*>(array.data());
+  size_t n = array.shape(0);
+  vector_qsort::Sort(ptr, n, desc);
+}
+
+void sort_in_place(nb::ndarray<nb::c_contig> array, bool desc = false) {
+  if (array.ndim() != 1) {
+    throw nb::value_error("vector_qsort only supports 1-dimensional arrays");
+  }
+
+  using dl_code = nanobind::dlpack::dtype_code;
+  auto dt = array.dtype();
+  if (dt.lanes != 1) {
+    throw nb::type_error("Only scalar element types are supported");
+  }
+
+  if (dt.code == static_cast<uint8_t>(dl_code::Float) && dt.bits == 32) {
+    sort_data<float>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::Float) && dt.bits == 64) {
+    sort_data<double>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::Int) && dt.bits == 32) {
+    sort_data<int32_t>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::UInt) && dt.bits == 32) {
+    sort_data<uint32_t>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::Int) && dt.bits == 64) {
+    sort_data<int64_t>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::UInt) && dt.bits == 64) {
+    sort_data<uint64_t>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::Int) && dt.bits == 16) {
+    sort_data<int16_t>(array, desc);
+  } else if (dt.code == static_cast<uint8_t>(dl_code::UInt) && dt.bits == 16) {
+    sort_data<uint16_t>(array, desc);
+  } else {
+    throw nb::type_error("Unsupported dtype for vector_qsort (supported: float32, float64, int32, uint32, int64, uint64, int16, uint16)");
+  }
+}
+
+NB_MODULE(_vector_qsort, m) {
+  m.doc() = "Google Highway SIMD Vectorized QuickSort";
+  m.def("sort_in_place", &sort_in_place, nb::arg("array"), nb::arg("desc") = false,
+        "Sort a 1D contiguous array in-place using Google Highway SIMD.");
+}

vector_qsort-0.1.0/include/vqsort.h

@@ -0,0 +1,45 @@
+#ifndef VECTOR_QSORT_CORE_H_
+#define VECTOR_QSORT_CORE_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <algorithm>
+#include <functional>
+
+#include "hwy/base.h"
+#include "hwy/contrib/sort/vqsort.h"
+
+namespace vector_qsort {
+
+template <typename T>
+inline void Sort(T* data, size_t n, bool desc = false) {
+  if (n <= 1) return;
+  if (desc) {
+    hwy::VQSort(data, n, hwy::SortDescending());
+  } else {
+    hwy::VQSort(data, n, hwy::SortAscending());
+  }
+}
+
+// Specialization for double in case VQSortHaveFloat64 is not supported on rare targets
+template <>
+inline void Sort<double>(double* data, size_t n, bool desc) {
+  if (n <= 1) return;
+  if (hwy::VQSortHaveFloat64()) {
+    if (desc) {
+      hwy::VQSort(data, n, hwy::SortDescending());
+    } else {
+      hwy::VQSort(data, n, hwy::SortAscending());
+    }
+  } else {
+    if (desc) {
+      std::sort(data, data + n, std::greater<double>());
+    } else {
+      std::sort(data, data + n);
+    }
+  }
+}
+
+}  // namespace vector_qsort
+
+#endif  // VECTOR_QSORT_CORE_H_

vector_qsort-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["scikit-build-core>=0.10", "nanobind>=2.0.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "vector-qsort"
+version = "0.1.0"
+description = "Vectorized quicksort for NumPy arrays using Google Highway SIMD."
+readme = "README.md"
+authors = [{ name = "Hemanth HM", email = "hemanth@h3manth.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+]
+
+[tool.scikit-build]
+cmake.build-type = "Release"
+wheel.packages = ["vector_qsort"]
+cmake.args = [
+    "-DHWY_ENABLE_TESTS=OFF",
+    "-DHWY_ENABLE_EXAMPLES=OFF",
+    "-DHWY_ENABLE_CONTRIB=ON"
+]
+sdist.include = [
+    "binding.cc",
+    "vector_qsort",
+    "CMakeLists.txt",
+    "README.md",
+    "LICENSE",
+    "include",
+]

vector_qsort-0.1.0/test/test_sort.py

@@ -0,0 +1,78 @@
+import pytest
+import numpy as np
+import vector_qsort
+
+def test_all_dtypes_and_orders():
+    dtypes = [
+        np.float32, np.float64,
+        np.int32, np.uint32,
+        np.int64, np.uint64,
+        np.int16, np.uint16,
+    ]
+    for dt in dtypes:
+        if np.issubdtype(dt, np.unsignedinteger):
+            raw = np.array([42, 5, 100, 0, 999, 500], dtype=dt)
+        else:
+            raw = np.array([42, -5, 100, 0, 999, -500], dtype=dt)
+        asc = raw.copy()
+        vector_qsort.sort(asc)
+        assert np.all(asc[:-1] <= asc[1:]), f"Ascending sort failed for {dt}"
+
+        desc = raw.copy()
+        vector_qsort.sort(desc, desc=True)
+        assert np.all(desc[:-1] >= desc[1:]), f"Descending sort failed for {dt}"
+
+def test_edge_cases():
+    # Empty
+    empty = np.array([], dtype=np.float32)
+    vector_qsort.sort(empty)
+    assert len(empty) == 0
+
+    # Single element
+    single = np.array([42], dtype=np.int32)
+    vector_qsort.sort(single)
+    assert single[0] == 42
+
+    # All duplicates
+    dupes = np.array([7, 7, 7, 7, 7], dtype=np.float64)
+    vector_qsort.sort(dupes)
+    assert np.array_equal(dupes, [7, 7, 7, 7, 7])
+
+    # Already sorted
+    sorted_arr = np.arange(10, dtype=np.int32)
+    vector_qsort.sort(sorted_arr)
+    assert np.array_equal(sorted_arr, np.arange(10))
+
+    # Reverse sorted
+    rev = np.arange(10, 0, -1, dtype=np.int32)
+    vector_qsort.sort(rev)
+    assert np.array_equal(rev, np.arange(1, 11))
+
+def test_sorted_copy():
+    orig = np.array([5, 3, 1, 4, 2], dtype=np.float32)
+    res = vector_qsort.sorted(orig)
+    assert res is not orig
+    assert np.array_equal(orig, [5, 3, 1, 4, 2])
+    assert np.array_equal(res, [1, 2, 3, 4, 5])
+
+    desc = vector_qsort.sorted(orig, desc=True)
+    assert np.array_equal(desc, [5, 4, 3, 2, 1])
+
+def test_large_array():
+    rng = np.random.default_rng(42)
+    data = rng.standard_normal(100_000).astype(np.float32)
+    expected = np.sort(data)
+
+    vector_qsort.sort(data)
+    assert np.allclose(data, expected)
+
+def test_error_handling():
+    # 2D array
+    mat = np.zeros((3, 3), dtype=np.float32)
+    with pytest.raises(ValueError, match="1-dimensional"):
+        vector_qsort.sort(mat)
+
+    # Unsupported dtype
+    unsupported = np.array(["a", "b", "c"])
+    with pytest.raises(TypeError):
+        vector_qsort.sort(unsupported)

vector_qsort-0.1.0/vector_qsort/__init__.py

@@ -0,0 +1,37 @@
+"""
+vector-qsort: Vectorized quicksort for NumPy arrays using Google Highway SIMD.
+"""
+from typing import Any
+import numpy as np
+
+try:
+    from ._vector_qsort import sort_in_place
+except ImportError:
+    try:
+        from _vector_qsort import sort_in_place
+    except ImportError as exc:
+        raise ImportError(
+            "Could not load native _vector_qsort extension. Run `pip install -e .`"
+        ) from exc
+
+def sort(arr: Any, desc: bool = False) -> Any:
+    """
+    Sort a 1D contiguous array in-place using Google Highway SIMD.
+    """
+    if isinstance(arr, np.ndarray):
+        if not arr.flags.c_contiguous:
+            raise ValueError("Array must be C-contiguous. Use np.ascontiguousarray() if needed.")
+    sort_in_place(arr, desc=desc)
+    return arr
+
+def sorted(arr: Any, desc: bool = False) -> Any:
+    """
+    Return a sorted copy of the array without mutating the original.
+    """
+    if isinstance(arr, np.ndarray):
+        copy = arr.copy()
+        sort_in_place(copy, desc=desc)
+        return copy
+    raise TypeError(f"sorted() expects numpy.ndarray, got {type(arr).__name__}")
+
+__all__ = ["sort", "sorted"]

vector_qsort-0.1.0/vector_qsort/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561