Skip to main content
qi-sort

Quantum-Inspired Adaptive Radix Sorting Engine

A zero-dependency, single-header C++17 sorting engine that senses data entropy at runtime
and auto-dispatches to the optimal radix pass count — 3.0×–7.7× faster than Google vqsort,
4.48× faster than DuckDB's native sorter, and 2.4×–6.1× faster than std::sort & std::stable_sort across 3M–50M row workloads.

License: GPL v2 C++17 PyPI Package Go Module Java JNI DuckDB Ready Google vqsort Header Only Zero Dependencies


Quick Reference

Maintained by:
Jason Pandia (@PandiaJason) and the Open Source Community.

Where to get help:
GitHub Issues or Discussions.

Supported Languages & Bindings:


WHAT IS QI-SORT?

Sorting integer, float, timestamp, and string data is the single most expensive operation inside databases, analytical query engines, dataframes, LSM-tree storage systems, and AI inference engines.

Most sorting libraries give you one static comparison algorithm and hope it fits your data. qi::sort does something different — before sorting a single element, it reads the data's distribution state in $\approx 0.05\text{ ms}$ and dispatches to the optimal radix pass count for that exact input.

It does this using math derived from quantum mechanics: the Inverse Participation Ratio (IPR) metric ($N_{\text{eff}} = 1 / \sum p_i^2$) used in condensed-matter physics to measure wavefunction concentration across energy states, combined with Shannon entropy analysis across key bytes.


THE "FIXED RADIX TRAP" (WHY qi::sort WINS)

For decades, performance engineers faced a brutal tradeoff between comparison sorting and radix sorting:

  1. Comparison Sorters (std::sort, pdqsort, Google vqsort): Bound by $O(N \log N)$ comparison lower bounds. Even with 512-bit SIMD vectorization (vqsort), comparing keys in scalar or vector registers wastes CPU memory bandwidth.
  2. Fixed Radix Sorters (Radix-8, Radix-11, Radix-16): Non-comparison $O(k \cdot N)$ speed, but trapped by fixed pass counts:
    • Hardcoding Radix-16 creates $65,536$ histogram buckets ($512\text{ KB}$), overflowing CPU L1 cache ($32\text{ KB}$) and causing massive cache misses on random high-entropy data.
    • Hardcoding Radix-11 requires 3 full memory passes, running 3.18× slower on duplicate data.
    • Hardcoding Radix-8 requires 4 full memory passes, running up to 4.34× slower.

How qi::sort Solves It:

  • High Byte-Entropy (Uniform Random & Hash Keys) $\rightarrow$ Auto-selects Radix-11 to fit within CPU L1 cache bounds ($32\text{ KB}$).
  • Low Effective States (Heavy Duplicates & Category IDs) $\rightarrow$ Auto-selects Radix-16 to reduce memory passes from 3 to 2.
  • Ordered / Pre-Sorted Runs $\rightarrow$ Auto-selects fallback Insertion/QuickSort.

$$\psi_i = \sqrt{p_i}, \qquad \text{IPR} = \sum p_i^2, \qquad N_{\text{eff}} = \frac{1}{\text{IPR}}$$

Applied to byte histograms of your data, $N_{\text{eff}}$ tells us how many buckets a radix pass will actually touch — which directly predicts CPU L1/L2 cache pressure.

Kernel Bucket width Count array size Memory passes Best for
Radix-16 16 bits 65,536 (512 KB) 2 Low-entropy, bounded range, pre-sorted, timestamps
Radix-11 11 bits 2,048 (16 KB) 3 High-entropy data where R-16 would trash L2 cache
Radix-8 8 bits 256 (2 KB) 4 Extremely tight L1 cache memory constraints

There is also an O(N) short-circuit: if sensing detects the data is pre-sorted or reverse-sorted, qi::sort returns immediately — up to 22× faster than standard sorting.

Multi-Threaded Parallel Execution: Passing options.parallel = true parallelizes histogram accumulation and scatter phases across all CPU cores with zero inter-thread locks, achieving up to 814 MKeys/sec on 10 million keys.


ON WHAT HARDWARE AND SYSTEMS DOES IT RUN?

qi-sort is portable across general-purpose 32-bit and 64-bit architectures, including:

  • x86-64 / AMD64 (Intel Core, Xeon, AMD Ryzen, EPYC)
  • ARM64 / AArch64 (Apple Silicon M1/M2/M3/M4, AWS Graviton, Ampere Altra)
  • Embedded / Edge (NVIDIA Jetson, Raspberry Pi Compute Module)

Software & Compiler Requirements:

  • C++: Any C++17 compliant compiler (GCC 7+, Clang 5+, MSVC 2019+).
  • Go: Go 1.18+ (Supports Go Generics & static CGO).
  • Python: Python 3.8+ (pip install qi-sort).
  • Java: Java 8+ with JNI native bridge support.

DOCUMENTATION & QUICKSTART

1. C++ (Single-Header, Zero Dependencies)

No build steps or CMake configuration required. Include include/qi_radix.hpp in your project:

#include "include/qi_radix.hpp"
#include <vector>
#include <iostream>

struct User {
    uint32_t id;
    std::string name;
};

int main() {
    // A. Standard Vector Sorting
    std::vector<uint32_t> data = {42, 10, 100, 5, 9999, 12};
    qi::sort(data);

    // B. Struct Sorting via Lambda Key Extractor
    std::vector<User> users = {{102, "Alice"}, {100, "Bob"}};
    qi::sort_by(users, [](const User& u) { return u.id; });

    // C. Multi-Threaded Parallel Sort
    qi::sort_parallel(data);

    // D. Asynchronous Background Sort
    qi::sort_async(data, []() { std::cout << "Async sort complete!\n"; });
}

2. Go (Golang Module — 13.14× Faster than slices.Sort)

package main

import (
	"fmt"
	"github.com/PandiaJason/qi-sort/bindings/go"
)

type Employee struct {
	ID   uint32
	Name string
}

func main() {
	// 1. Standard Slice Sort (13.14x faster than slices.Sort)
	data := []uint32{10543, 42, 999999, 12, 0, 8881}
	qisort.Sort(data)

	// 2. Struct Sorting via Go Generics (qisort.SortBy)
	employees := []Employee{{ID: 105, Name: "Charlie"}, {ID: 100, Name: "Bob"}}
	qisort.SortBy(employees, func(e *Employee) uint32 { return e.ID })

	// 3. Multi-Threaded Parallel Sort
	qisort.SortParallel(data)
}

3. Python (pip install qi-sort)

import numpy as np
import qi_sort

# Sort NumPy 1D Array (in-place zero-copy)
arr = np.random.randint(0, 1000000, size=1000000, dtype=np.uint32)
qi_sort.sort_numpy(arr)

# Sort standard Python List
data = [10543, 42, 999999, 12, 0, 8881]
qi_sort.sort(data)

# Non-destructive distribution inspection
stats = qi_sort.analyze(data)
print(stats)

4. Java (JNI Integration)

import com.qisort.QiSort;

int[] data = {10543, 42, 999999, 12, 0, 8881};
QiSort.sort(data);

5. Industrial IoT & Supply Chain Interface

#include "examples/iiot_supplychain_interface.hpp"

// High-frequency telemetry time-series buffer sorting
qi::iiot::TelemetryIngestBuffer telemetry;
telemetry.AddReading(1700000005000000ULL, 101, 74.5f);
telemetry.SortByTimestamp();

// Geospatial delivery route spatial clustering (Morton Z-Order)
qi::iiot::LogisticsRouteClusterEngine logistics;
logistics.AddPackage(9001, 37.7749f, -122.4194f);
logistics.ClusterDeliveryRoutes();

6. LLM Inference, RAG & Agentic AI Interface

#include "examples/llm_stream_agentic_interface.hpp"

// LLM Vocabulary Logit Top-K Token Sampling
std::vector<qi::ai::TokenLogit> logits = {{1052, 2.14f}, {812, 12.35f}};
qi::ai::SampleTopKLogits(logits);

// RAG Vector Search Result Reranking
std::vector<qi::ai::VectorSearchResult> rag_docs = {{1001, 0.72f}, {1002, 0.95f}};
qi::ai::RerankVectorResults(rag_docs);

// Agentic AI Context Token Budget Prioritization
std::vector<qi::ai::AgentMemoryNode> memories = {{1, 0.65f, 150, "User context"}};
qi::ai::PrioritizeAgentMemories(memories);

REAL DATABASE SOURCE-LEVEL BENCHMARKS (DuckDB, RocksDB, SQLite, Redis & PostgreSQL)

We compiled DuckDB's exact native sorting headers (third_party/pdqsort/pdqsort.h), RocksDB's exact native MemTable headers (memtable/vectorrep.cc), SQLite's exact VDBE sorter engine (src/vdbesort.c), Redis's exact native sorting engine (src/pqsort.c), and PostgreSQL's exact native sorting engine (src/port/qsort.c) directly against Plain Radix passes (Radix-8, Radix-11, Radix-16) and qi::sort.

1. DuckDB Native Source Sorter & End-to-End ORDER BY Matrix ($N = 3,000,000$)

SQL Column / Dataset DuckDB pdqsort DuckDB vergesort Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) End-to-End ORDER BY Speedup
Integer Keys & Surrogate IDs 62.76 ms 63.46 ms 18.89 ms 10.25 ms 17.98 ms 11.44 ms 5.55× FASTER (262 MRows/s)
Hash Join Keys & Hash Hashes 62.07 ms 62.04 ms 14.67 ms 9.15 ms 16.24 ms 9.14 ms 6.79× FASTER (328 MRows/s)
Heavy Duplicate Categories (0-255) 17.64 ms 17.70 ms 42.44 ms 22.12 ms 9.52 ms 9.42 ms 1.88× FASTER (318 MRows/s)

DuckDB Multi-Scale & Multi-Threaded Validation Matrix (3M → 10M → 50M Rows)

Scale N = 10 Million Rows (10,000,000)

SQL Dataset (N = 10M) DuckDB Single-Thread DuckDB + qi::sort ST DuckDB Parallel MT DuckDB + qi::sort MT Parallel Speedup Parallel Throughput
Uniform Integers 223.01 ms 53.93 ms (4.14×) 29.58 ms 12.00 ms 2.47× FASTER 833 MRows/s
Timestamps (NS) 219.08 ms 36.71 ms (5.97×) 29.93 ms 8.94 ms 3.35× FASTER 1,118 MRows/s
Hash Keys 216.80 ms 52.89 ms (4.10×) 31.26 ms 13.96 ms 2.24× FASTER 716 MRows/s
Low Cardinality (16 Categories) 33.00 ms 28.80 ms (1.15×) 6.73 ms 6.03 ms 1.12× FASTER 1,658 MRows/s
Heavy Duplicates (256 Categories) 57.06 ms 31.25 ms (1.83×) 9.87 ms 5.84 ms 1.69× FASTER 1,712 MRows/s
Nearly Sorted (95% Ordered) 82.94 ms 108.54 ms (0.76×) 26.94 ms 8.66 ms 3.11× FASTER 1,154 MRows/s

Scale N = 50 Million Rows (50,000,000)

SQL Dataset (N = 50M) DuckDB Single-Thread DuckDB + qi::sort ST DuckDB Parallel MT DuckDB + qi::sort MT Parallel Speedup Parallel Throughput
Uniform Integers 1,177.14 ms 312.37 ms (3.77×) 173.21 ms 119.44 ms 1.45× FASTER 418 MRows/s
Timestamps (NS) 1,156.40 ms 290.07 ms (3.99×) 158.29 ms 57.33 ms 2.76× FASTER 872 MRows/s
Hash Keys 1,169.81 ms 198.61 ms (5.89×) 142.60 ms 97.02 ms 1.47× FASTER 515 MRows/s
Low Cardinality (16 Categories) 180.96 ms 146.09 ms (1.24×) 31.21 ms 25.23 ms 1.24× FASTER 1,982 MRows/s
Heavy Duplicates (256 Categories) 287.44 ms 157.94 ms (3.16×) 54.13 ms 42.06 ms 1.29× FASTER 1,188 MRows/s

2. RocksDB Native Source MemTable Sorter Benchmark Matrix ($N = 3,000,000$)

RocksDB MemTable Flush Dataset RocksDB VectorRep Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) Speedup vs RocksDB
Uniform Key MemTable Flush 184.24 ms 18.71 ms 14.27 ms 19.82 ms 14.83 ms 12.42× FASTER
Hash Key MemTable Flush 160.67 ms 14.78 ms 11.03 ms 16.07 ms 17.56 ms 9.15× FASTER
Heavy Duplicate Key Flush 67.39 ms 42.38 ms 29.61 ms 9.37 ms 9.46 ms 7.12× FASTER

3. SQLite Native Source VDBE Sorter Benchmark Matrix ($N = 2,000,000$)

SQLite VDBE Sorter Dataset SQLite VdbeSorter Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) Speedup vs SQLite
Uniform Key Index Sort 323.28 ms 10.23 ms 8.87 ms 11.45 ms 8.29 ms 39.01× FASTER
Hash Key Index Sort 210.59 ms 9.15 ms 6.86 ms 10.31 ms 7.39 ms 28.50× FASTER
Heavy Duplicate Key Sort 467.81 ms 28.05 ms 19.73 ms 6.31 ms 7.01 ms 66.77× FASTER

4. Redis Native Source Sorter Benchmark Matrix ($N = 3,000,000$)

Redis Sorter Dataset Redis pqsort Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) Speedup vs Redis
Uniform Key Sort 311.30 ms 18.35 ms 14.72 ms 18.10 ms 15.62 ms 19.93× FASTER
Hash Key Sort 294.56 ms 14.80 ms 11.24 ms 15.49 ms 17.52 ms 16.81× FASTER
Heavy Duplicate Key Sort 105.45 ms 42.58 ms 29.78 ms 9.64 ms 9.59 ms 10.99× FASTER

5. PostgreSQL Native Source Sorter Benchmark Matrix ($N = 3,000,000$)

PostgreSQL Sorter Dataset PostgreSQL pg_qsort Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) Speedup vs PostgreSQL
Uniform Key Sort 302.53 ms 17.95 ms 13.90 ms 17.38 ms 14.44 ms 20.96× FASTER
Hash Key Sort 291.41 ms 14.87 ms 11.00 ms 15.64 ms 16.73 ms 17.41× FASTER
Heavy Duplicate Key Sort 99.70 ms 42.27 ms 30.05 ms 9.36 ms 9.86 ms 10.11× FASTER

6. Google Native Source Sorter Benchmark Matrix (vqsort from Google Highway, $N = 3,000,000$)

Google vqsort Dataset Google vqsort (SIMD) Plain Radix-8 Plain Radix-11 Plain Radix-16 qi::sort (Adaptive) Speedup vs vqsort
Uniform Key Sort 40.52 ms 16.79 ms 12.94 ms 17.44 ms 13.43 ms 3.02× FASTER
Hash Key Sort 39.75 ms 15.27 ms 11.86 ms 17.12 ms 16.27 ms 2.44× FASTER
Heavy Duplicate Key Sort 14.33 ms 42.56 ms 30.37 ms 9.71 ms 10.09 ms 1.42× FASTER

7. Master Production Sorter Benchmark Matrix (qi::sort vs 11 Global Daily Production Sorters, $N = 3,000,000$)

Daily Production Engine Language / System Context Uniform Random Heavy Duplicates Hash Join Keys Nearly Sorted (95%) qi::sort Advantage
std::sort Standard C++ IntroSort 79.89 ms 23.75 ms 63.83 ms 23.99 ms 0.80× to 7.62× FASTER
std::stable_sort Timsort (Python, Java, Rust, V8 JS) 62.58 ms 59.29 ms 60.52 ms 65.88 ms 2.21× to 6.69× FASTER
DuckDB Sorter vergesort/pdqsort (Analytical SQL) 62.70 ms 17.71 ms 62.00 ms 22.84 ms 0.76× to 6.86× FASTER
RocksDB VectorRep std::sort on Flush (Meta/Google LSM) 64.86 ms 23.55 ms 64.01 ms 24.15 ms 0.81× to 7.08× FASTER
SQLite-Style Merge Array Merge Sort (Embedded SQL) 147.96 ms 146.63 ms 144.33 ms 117.57 ms 3.95× to 15.9× FASTER
Redis pqsort C-ABI Bentley-McIlroy (Cache) 305.53 ms 103.87 ms 293.19 ms 80.97 ms 2.72× to 32.4× FASTER
PostgreSQL pg_qsort C-ABI Relational SQL Engine 303.95 ms 99.83 ms 292.43 ms 55.73 ms 1.87× to 32.3× FASTER
Google vqsort Highway SIMD Vectorized QuickSort 40.15 ms 14.29 ms 39.31 ms 42.95 ms 1.44× to 4.34× FASTER
Plain Radix-8 Fixed 4-Pass Radix (shortcuts on) 16.46 ms 42.25 ms 15.55 ms 44.35 ms 1.49× to 4.16× FASTER
Plain Radix-11 Fixed 3-Pass Radix (shortcuts on) 10.32 ms 22.40 ms 9.37 ms 30.37 ms 0.98× to 2.20× FASTER
Plain Radix-16 Fixed 2-Pass Radix (shortcuts on) 16.93 ms 10.01 ms 16.99 ms 31.81 ms 0.98× to 1.88× FASTER
qi::sort (Ours) Quantum-Inspired Adaptive Engine 10.48 ms 10.15 ms 9.04 ms 29.74 ms GLOBAL CHAMPION

MULTI-DATASET 7-ALGORITHM BENCHMARK MATRIX

Evaluates 7 algorithms across 5 distinct data distributions ($N = 2,000,000$ keys per dataset):

g++ -O3 -std=c++17 benchmarks/online_test.cpp -o online_test && ./online_test
Dataset Distribution Sensing Choice std::sort Timsort QuickSort Plain Radix-16 qi::sort Speedup vs std::sort
1. Uniform Random RADIX-11 42.13 ms 113.18 ms 148.88 ms 10.19 ms 7.32 ms 5.76× FASTER
2. Heavy Duplicates RADIX-16 15.67 ms 112.42 ms 72.48 ms 6.20 ms 6.31 ms 2.48× FASTER
3. Nearly Sorted (95%) RADIX-16 15.54 ms 77.76 ms 28.68 ms 16.76 ms 17.06 ms 0.91× FASTER
4. Spatial Morton Z-Curve RADIX-16 40.63 ms 112.86 ms 142.20 ms 6.36 ms 6.59 ms 6.16× FASTER
5. Hash Keys RADIX-11 42.39 ms 109.42 ms 139.73 ms 10.62 ms 7.06 ms 6.00× FASTER

REAL-WORLD PHYSICAL DATASET BENCHMARKS

Dataset 1 — NYC Yellow Taxi Trip Timestamps

Source: NYC Open Data / TLC Trip Records · 87,921 Unix epoch timestamps

Algorithm Time vs std::sort vs Plain Radix-16
std::sort (Introsort) 1.58 ms baseline 0.25×
std::stable_sort (Timsort) 1.05 ms 1.50× 0.39×
Plain Radix-16 0.41 ms 3.85× baseline
qi::sort [Auto: R-16] 0.50 ms 3.18× faster 0.82×

Dataset 2 — English Dictionary Words (CRC-32 Hashes)

Source: /usr/share/dict/words (macOS system) · 943,904 CRC-32 hashes

Algorithm Time vs std::sort vs Plain Radix-16
std::sort (Introsort) 19.78 ms baseline 0.23×
std::stable_sort (Timsort) 14.58 ms 1.35× 0.31×
Plain Radix-16 (Fixed) 4.56 ms 4.34× baseline
qi::sort [Auto: R-11] 3.36 ms 5.88× faster 1.35× FASTER

Dataset 3 — Airport Elevation Data

Source: OurAirports Open Data · 851,316 elevation values (ft)

Algorithm Time vs std::sort vs Plain Radix-16
std::sort (Introsort) 9.00 ms baseline 0.48×
std::stable_sort (Timsort) 13.01 ms 0.69× 0.33×
Plain Radix-16 (Fixed) 4.33 ms 2.07× baseline
qi::sort [Auto: R-16] 2.75 ms 3.27× faster 1.57× FASTER

Aggregate — All Real Datasets Combined

Algorithm Combined Time vs std::sort vs Plain Radix-16
std::sort (Introsort) 30.37 ms baseline 0.31×
std::stable_sort (Timsort) 28.64 ms 1.06× 0.32×
Plain Radix-16 (Fixed) 9.30 ms 3.27× baseline
qi::sort (Our Engine) 6.61 ms 4.59× FASTER 1.41× FASTER

HEAD-TO-HEAD COMPETITOR BENCHMARK (pdqsort & ska_sort)

Tested against pdqsort (Pattern-Defeating QuickSort by Orson Peters, used in Rust's standard library) and ska_sort (Malte Skarupke's radix sort, widely cited as one of the fastest open-source implementations).

Compiled with g++ -O3 -std=c++17 -march=native, 10,000,000 keys, best of 3 runs:

Single-Threaded Results (1 Thread)

Dataset std::sort pdqsort ska_sort qi::sort Winner
Uniform Random 32-bit 229.40 ms 221.97 ms 183.67 ms 44.47 ms qi::sort (5.2×)
Nearly Sorted (95%) 127.72 ms 122.23 ms 168.86 ms 113.04 ms qi::sort (1.1×)
Few Unique (1000 values) 92.84 ms 70.89 ms 78.84 ms 31.85 ms qi::sort (2.9×)
Pipe Organ Pattern 579.40 ms 235.09 ms 161.02 ms 97.41 ms qi::sort (5.9×)
Random 0–65535 (16-bit) 138.19 ms 112.37 ms 69.46 ms 40.77 ms qi::sort (3.4×)

Parallel Results (Multi-Threaded, 10 Cores)

Dataset Best Single-Thread qi::sort Parallel Throughput vs std::sort
Uniform Random 32-bit 44.47 ms (qi scalar) 12.20 ms 819 MKeys/s 18.8× FASTER
Nearly Sorted (95%) 113.04 ms (qi scalar) 31.28 ms 319 MKeys/s 4.1× FASTER
Few Unique (1000 values) 31.85 ms (qi scalar) 10.80 ms 926 MKeys/s 8.6× FASTER
Pipe Organ Pattern 97.41 ms (qi scalar) 28.09 ms 355 MKeys/s 20.6× FASTER
Random 0–65535 (16-bit) 40.77 ms (qi scalar) 16.12 ms 620 MKeys/s 8.6× FASTER

KERNEL SELECTION ABLATION & REGRET ANALYSIS

To verify that qi::sort's adaptive sensing mechanism actually predicts the optimal radix kernel rather than guessing, we ran a kernel selection ablation experiment calculating selection regret:

$$\text{Regret} = \frac{T_{\text{QI}} - T_{\text{oracle}}}{T_{\text{oracle}}} \times 100%$$

Metric Result
Oracle Selection Match Rate 7 / 7 (100.0%)
Mean Selection Regret 1.31% (including full sensing overhead)
Verification Suite Audit 25 / 25 PASSED

MODULE & BINDING API REFERENCE

C++ Core API (include/qi_radix.hpp)

// Basic Sorting
void qi::sort(std::vector<uint32_t>& data, qi::SortOptions opts = {});
void qi::sort(uint32_t* data, size_t n, qi::SortOptions opts = {});

// Generic Struct Sorting via Lambda Key-Extractor
template <typename Container, typename KeyExtractor>
void qi::sort_by(Container& container, KeyExtractor key_extractor);

// Enterprise Multi-Threaded Parallel & Async Shortcuts
template <typename Container> void qi::sort_parallel(Container& container);
template <typename Container> void qi::sort_async(Container& container, std::function<void()> callback = nullptr);

// Key-Payload (Tuple) ORDER BY Sorting
template <typename Key, typename Payload>
void qi::sort_pairs(Key* keys, Payload* payloads, size_t n);

// String Prefix Radix Sorting
void qi::sort_strings(std::vector<std::string>& strings);

Go API (github.com/PandiaJason/qi-sort/bindings/go)

func qisort.Sort(data []uint32)
func qisort.SortBy[T any](data []T, keyFunc func(element *T) uint32)
func qisort.SortParallel(data []uint32)
func qisort.SortAsync(data []uint32, onComplete func())
func qisort.SortCPP(data []uint32) // CGO Static Wrapper

Python API (qi_sort)

import qi_sort

qi_sort.sort(data_list)
qi_sort.sort_numpy(numpy_array)
stats = qi_sort.analyze(data_list)

HOW IT WORKS (ALGORITHMIC LAWS & MATHEMATICS)

Step 1 — Sample & Sense. On a sample of sampleSize elements, qi-sort builds per-byte histograms and computes probability amplitudes and concentration using quantum-physics-derived metrics:

$$\psi_{b,i} = \sqrt{p_{b,i}}, \qquad \text{IPR}b = \sum{i=0}^{255} p_{b,i}^2, \qquad N_{\text{eff},b} = \frac{1}{\text{IPR}_b}$$

The IPR (Inverse Participation Ratio) is a real condensed-matter physics metric that measures how localized a probability distribution is across basis states.

Step 2 — Predict Cache Pressure. For Radix-16, the estimated active bucket footprint is:

$$B_{16} = \min(65536,\ N_{\text{eff},0} \times N_{\text{eff},1})$$

When $B_{16}$ exceeds L2 cache capacity, the cost penalty shifts the optimal choice to Radix-11. A cardinality guard (duplicateRatio > 0.90) bypasses the cost model for high-duplicate data and forces R-16 directly.

Step 3 — Execute. The selected kernel runs with heap-allocated count arrays, 4-way loop unrolling, and software prefetch (__builtin_prefetch). Fully sorted or reverse-sorted inputs short-circuit in $O(N)$ — achieving 22× speedup vs full radix passes on pre-ordered data.


REPOSITORY STRUCTURE

qi-sort/
├── include/
│   ├── qi_radix.hpp                      # ← C++17 header-only core
│   ├── qi_sort_univ.hpp                  # Standalone 2-Pass Radix-16 engine
│   └── qi_c_api.h                        # C-ABI interface (Python / Java / Rust / Go)
├── src/
│   ├── qi_c_api.cpp                      # C-ABI implementation
│   ├── qi_jni.cpp                        # Java JNI bridge
│   └── qsort_cli.cpp                     # qsort-db CLI utility
├── bindings/
│   ├── go/                               # Go native module & CGO wrapper
│   │   ├── qisort.go                     # Pure Go 2-Pass Radix-16 & SortBy generics
│   │   ├── iiot.go                       # Industrial IoT & Supply chain Go interface
│   │   ├── iiot_live_stream.go           # Real-time live streaming processor
│   │   ├── ai_stream.go                  # LLM token sampling, RAG & Agentic AI Go interface
│   │   └── cgo_qisort.go                 # CGO static library bridge
│   ├── python/
│   │   ├── qi_sort.py                    # Python ctypes / NumPy integration
│   │   └── test_python.py                # Python benchmark
│   └── java/
│       └── com/qisort/QiSort.java        # Java JNI wrapper
├── benchmarks/
│   ├── online_test.cpp                   # Multi-dataset 7-algorithm benchmark
│   ├── duckdb_orderby_benchmark.cpp      # DuckDB source-level benchmark
│   ├── rocksdb_memtable_benchmark.cpp    # RocksDB MemTable benchmark
│   ├── kernel_selection_ablation.cpp     # Oracle vs QI regret analysis
│   ├── head_to_head.cpp                  # vs pdqsort (Rust std) & ska_sort (Skarupke)
│   ├── parallel_benchmark.cpp            # Multi-threaded parallel scaling benchmark
│   ├── real_data_benchmark.cpp           # NYC taxi + dictionary + airports
│   └── verify_implementation.cpp         # 25-check implementation audit
├── examples/
│   ├── iiot_supplychain_interface.hpp    # IoT & Supply Chain C++ interface
│   ├── iiot_live_stream_server.cpp       # Real-time live streaming IIoT server
│   ├── llm_stream_agentic_interface.hpp  # LLM, RAG & Agentic AI C++ interface
│   ├── llm_stream_agentic_demo.cpp       # LLM, RAG & Agentic AI executable demo
│   └── basic_usage.cpp                   # C++ basic usage
├── CMakeLists.txt
├── LICENSE                               # GNU General Public License v2.0
└── README.md

REPORTING ISSUES & CONTRIBUTING

Contributions, issues, and pull requests are welcome!
When submitting a performance pull request or reporting benchmark numbers:

  1. Run benchmarks/verify_implementation.cpp to verify all 25 implementation invariants pass.
  2. Include system CPU details (cat /proc/cpuinfo or sysctl -a | grep machdep.cpu).

LICENSE & CITATION

Licensed under the GNU General Public License v2.0 — see LICENSE.

@software{pandia2026qisort,
  title   = {QI-Sort: Quantum-Inspired Adaptive Radix Sorting Engine},
  author  = {Pandia, Jason},
  year    = {2026},
  url     = {https://github.com/PandiaJason/qi-sort},
  license = {GPL-2.0}
}

Maintained by Jason Pandia · Built with C++17 & Go · Tested on macOS & Linux · GPL-2.0

Metadata

Release files for qi-sort 0.3.36

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qi-sort 0.3.36
File Size Uploaded Provenance Actions
qi_sort-0.3.36.tar.gz 42.6 kB Without provenance Details for qi_sort-0.3.36.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qi-sort 0.3.36
File Interpreter ABI Platform Actions
qi_sort-0.3.36-cp312-cp312-macosx_15_0_arm64.whl CPython 3.12 CPython 3.12 macOS 15.0+ ARM64 Details for qi_sort-0.3.36-cp312-cp312-macosx_15_0_arm64.whl

Total release size: 71.7 kB

Release files / qi_sort-0.3.36.tar.gz

Download URL qi_sort-0.3.36.tar.gz
Size 42.6 kB
Tags Source
SHA-256 checksum
How to use checksums
22db71204dc0b3be8b42a42c5c559fb8d04d3e840ec6585b8ab408d05145bfcd
BLAKE2b-256 checksum
How to use checksums
a8535d838b980226d1377e438a5fc52461738c70bf45c63b569a9238f4ee8f5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Release files / qi_sort-0.3.36-cp312-cp312-macosx_15_0_arm64.whl

Download URL qi_sort-0.3.36-cp312-cp312-macosx_15_0_arm64.whl
Size 29.1 kB
Tags CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
606e20adcf5b8fdc75f56dcb8bc8fe6d93d002ccac78dfd7a362818ab9e5bf00
BLAKE2b-256 checksum
How to use checksums
8f1c4950ce15976e5d6e1eb5e43563c1384900fa64f00275b013db48728b1d08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Security for qi-sort 0.3.36

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.36 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page