https://github.com/programmersd21/ordr
⚡ High-performance sorting library for Python, powered by Rust 🦀 - featuring parallel, adaptive, and radix-sort backends for blazing-fast performance.
https://github.com/programmersd21/ordr
benchmark data-structures fast high-performance introsort numpy parallel-sorting pdqsort performance pyo3 python python-sorting quicksort radix-sort rust rust-python sorting sorting-algorithms timsort
Last synced: 4 days ago
JSON representation
⚡ High-performance sorting library for Python, powered by Rust 🦀 - featuring parallel, adaptive, and radix-sort backends for blazing-fast performance.
- Host: GitHub
- URL: https://github.com/programmersd21/ordr
- Owner: programmersd21
- License: mit
- Created: 2026-05-29T13:45:02.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2026-05-29T15:10:17.000Z (11 days ago)
- Last Synced: 2026-06-02T00:24:46.036Z (8 days ago)
- Topics: benchmark, data-structures, fast, high-performance, introsort, numpy, parallel-sorting, pdqsort, performance, pyo3, python, python-sorting, quicksort, radix-sort, rust, rust-python, sorting, sorting-algorithms, timsort
- Language: Python
- Homepage: https://programmersd21.github.io/ordr/
- Size: 733 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# ordr
[](https://github.com/programmersd21/ordr/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://www.rust-lang.org/)
[](https://opensource.org/licenses/MIT)
> **High-performance adaptive sorting for Python, powered by Rust.**
`ordr` is a professional sorting library that bridges the gap between Python's ergonomics and Rust's raw performance. It features a suite of optimized sorting algorithms and an intelligent adaptive dispatch engine that selects the best strategy for your data.
## Key Features
- **Adaptive Dispatch (`ordr.smart`)**: Automatically chooses the best algorithm by inspecting data characteristics (size, presortedness, duplicate ratio, value range).
- **High Performance**: Core algorithms implemented in Rust with heavy optimizations (branchless partition, prefetching, LTO).
- **Parallel Sorting**: Leverages Rayon for multi-threaded sorting of massive datasets.
- **NumPy Integration**: Accepts numpy arrays directly with zero-copy in-place sorting.
- **Modern Algorithms**: Includes PDQSort (Pattern-Defeating Quicksort), TimSort, IntroSort, Radix Sort, and sorting networks for small arrays.
- **Developer Tools**: Built-in benchmarking suite, terminal-based sorting visualizer, and hyperfine benchmarking scripts.
## Installation
```bash
pip install ordr-python
```
*(Note: Requires a Rust compiler for source builds. Pre-built wheels are available from PyPI.)*
## Usage
### Basic Sorting
```python
import ordr
import random
data = [random.randint(0, 1000) for _ in range(10000)]
# Use the adaptive smart sort (recommended)
sorted_data = ordr.smart(data)
# Or choose a specific algorithm
sorted_data = ordr.pdq(data) # Pattern-Defeating Quicksort
sorted_data = ordr.tim(data) # TimSort (stable)
sorted_data = ordr.par_sort(data) # Parallel stable sort
sorted_data = ordr.par_sort_unstable(data) # Parallel unstable sort
sorted_data = ordr.radix(data) # Radix sort for integers
```
### NumPy Support
```python
import numpy as np
import ordr
arr = np.array([3, 1, 4, 1, 5], dtype=np.int64)
ordr.smart(arr) # Sorts in-place, zero-copy
print(arr) # [1, 1, 3, 4, 5]
```
### Development Scripts
The repository includes several utility scripts for common development tasks:
- **Build**: `python build_lib.py` builds the Rust extension and creates wheels in the `build/` directory.
- **Lint**: `python lint.py` runs Ruff (formatting and linting), Mypy, cargo fmt, cargo clippy, and pytest.
- **Benchmarks**: `make bench algo= size= pattern=` runs hyperfine for a single algorithm. Low-level: `python bench_hyperfine.py generate ` to prepare data, then `python bench_hyperfine.py run ` to time.
- **Examples**: `python run_examples.py` runs all scripts in the `examples/` directory.
### Benchmarking
`ordr` comes with a first-class benchmarking suite to compare performance against Python's built-in `sorted()`.
```python
from ordr.benchmark import compare, display_comparison
# Compare ordr.smart against Python's sorted()
results = compare(size=10000, pattern="random")
display_comparison(results)
```
Run `make bench-compare` to generate a hyperfine report in `benches/report.md`.
Performance on **1,000,000 random integers** (in-process timing):
| Algorithm | Time | vs builtin |
| :--- | :--- | :--- |
| `smart` | 63 ms | **4.2x faster** |
| `par_sort` | 66 ms | **4.0x faster** |
| `radix` | 100 ms | **2.7x faster** |
| `pdq` | 160 ms | **1.7x faster** |
| `builtin` | 267 ms | 1.0x (baseline) |
## Algorithm Complexity
| Algorithm | Best | Average | Worst | Space | Stable |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **`ordr.smart`** | O(n) | O(n log n) | O(n log n) | Varies | Varies* |
| **`ordr.pdq`** | O(n) | O(n log n) | O(n log n) | O(log n) | No |
| **`ordr.tim`** | O(n) | O(n log n) | O(n log n) | O(n) | Yes |
| **`ordr.intro`** | O(n log n) | O(n log n) | O(n log n) | O(log n) | No |
| **`ordr.radix`** | O(nk) | O(nk) | O(nk) | O(n+k) | Yes |
| **`ordr.par_sort`** | O(n log n) | O(n log n) | O(n log n) | O(n) | Yes |
| **`ordr.par_sort_unstable`** | O(n log n) | O(n log n) | O(n log n) | O(log n) | No |
*\*`ordr.smart` may choose a stable or unstable algorithm depending on the data.*
## Architecture
`ordr` is built with a modular architecture that separates the high-performance Rust core from the ergonomic Python API.
- **Rust Core**: Found in `src/`, containing the implementation of all sorting algorithms and the analysis engine.
- **Adaptive Engine**: Located in `src/adaptive/`, responsible for algorithmic dispatch with sampling-based analysis.
- **Python Bridge**: NumPy `PyArray1` bindings in `src/lib.rs` and the `python/ordr/` package. Data flows as `list → np.ndarray → Rust in-place sort → list`.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
## License
`ordr` is licensed under the MIT License. See [LICENSE](LICENSE) for details.