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.
Quick Reference
Maintained by:
Jason Pandia (@PandiaJason) and the Open Source Community.
Where to get help:
GitHub Issues or Discussions.
Supported Languages & Bindings:
- C++17 (Header-only:
include/qi_radix.hpp) - Go / Golang (Native Module:
github.com/PandiaJason/qi-sort/bindings/go) - Python (PyPI Package:
qi-sort) - Java / JNI (Native Bridge:
bindings/java) - C-ABI (Shared Library:
include/qi_c_api.h)
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:
- Comparison Sorters (
std::sort,pdqsort, Googlevqsort): 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. - 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-11to fit within CPU L1 cache bounds ($32\text{ KB}$). - Low Effective States (Heavy Duplicates & Category IDs) $\rightarrow$ Auto-selects
Radix-16to 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:
- Run
benchmarks/verify_implementation.cppto verify all 25 implementation invariants pass. - Include system CPU details (
cat /proc/cpuinfoorsysctl -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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.