ZADU 0.5.1 acceleration report¶
Executive result¶
ZADU 0.5.1 is materially faster, but there is no honest single multiplier for the entire library. On the maintained Apple M4 and the representative common eight-metric suite at 2,000 samples:
- The default exact NumPy path is 1.64x faster warm and 1.14x faster cold than v0.5.0, the release immediately before the acceleration work.
- The same default path is 1.52x faster warm and 1.09x faster cold than the 2023 v0.1.1 baseline, but some 2023 metric definitions were incorrect or different, so this is a runtime comparison rather than full semantic parity.
- Explicit MLX float32 is 7.30x faster warm and 1.85x faster cold than v0.5.0 on the same suite. Its warm time is 0.101 s rather than 0.734 s.
- Explicit Torch CPU float64 is 4.72x faster warm and 1.52x faster cold than v0.5.0. Its warm time is 0.156 s.
- Default-path process peak RSS for the suite fell from about 525 MiB to 398 MiB (24%). Focused pair and topology workloads reduced peak RSS by approximately 46% and 42%, respectively.
The resource mix determines the result. Pair-only and topology workloads gained
roughly 4–5x at 2,000 samples, while a full-rank-dominated core suite gained only
1.28x because exact O(n² log n) row ordering still dominates. Isolated metric
kernels improved by 4.21–77.82x, but those numbers must not be presented as
end-to-end library speedups.
Versions and test machine¶
| Role | Revision | Why selected |
|---|---|---|
| Early 2023 | v0.1.1 / 5bf6057 (2023-10-20) |
Last stable tag in ZADU's founding year; more useful than the May v0.1.0 tag while still representing the original scheduler and loop kernels |
| Pre-acceleration | v0.5.0 / c475be1 (2026-08-22) |
Release immediately before the 0.5.1 acceleration PR series |
| Candidate | 94e71a9 (2026-08-23) |
PR 7-C merge; all performance code complete before packaging/report-only PR 8 |
Measurements used a 16 GB Mac mini with a 10-core Apple M4 (4 performance and 6 efficiency cores), macOS 26.4, Python 3.12.13, NumPy 2.5.2, SciPy 1.18.1, scikit-learn 1.9.0, FAISS CPU 1.15.0, MLX 0.32.1, and PyTorch 2.13.0.
Every historical checkout ran in an isolated child process under the same
interpreter and installed dependency environment; only PYTHONPATH changed.
This controls the software environment but does not recreate a 2023 laptop,
old NumPy/SciPy/FAISS releases, or historical thermal state. It answers “how do
these source versions perform today on the same machine?”
Workloads and measurement¶
All workloads used seeded Gaussian data, 20 original dimensions, two projection
dimensions, and k=20. “Cold” is constructor plus the first collection
evaluation. “Warm” is the median of five subsequent evaluations on the same
runner. Construction matters because historical schedulers build original-space
resources in __init__. Unless stated otherwise, one projection was evaluated.
| Suite | Common metrics | Dominant work |
|---|---|---|
| Core | T&C, MRRE, LCMC, Neighborhood Hit | Dense full ranks and neighbor tables |
| Pair | Stress, Pearson | Exact unique-pair distances and reductions |
| Topology | Topographic Product, Procrustes | Stable neighbors, selected distances, local SVD |
| Representative | All eight metrics above | Mixed dense ranks, pair reductions, neighbors, topology |
Peak RSS is process-wide ru_maxrss, including imports and native allocator
pools; it is not an allocation delta. One cold observation per isolated process
is less stable than the five-sample warm median. Timing gates are therefore not
enforced on shared CI.
Default exact path versus v0.5.0 and 2023¶
Each speedup is baseline time divided by current time. Values above 1 are faster. The final columns show the candidate's absolute time and peak RSS.
Core rank/neighbor suite¶
| n | v0.5 cold | v0.5 warm | 2023 cold | 2023 warm | current cold | current warm | current RSS |
|---|---|---|---|---|---|---|---|
| 500 | 1.62x | 2.31x | 1.79x | 2.53x | 0.0277 s | 0.0127 s | 136.5 MiB |
| 1,000 | 1.30x | 1.61x | 1.33x | 1.67x | 0.1228 s | 0.0585 s | 169.9 MiB |
| 2,000 | 1.13x | 1.28x | 1.13x | 1.29x | 0.5501 s | 0.2647 s | 295.5 MiB |
The relative gain shrinks with n because full exact ranking remains the
asymptotic bottleneck. Vectorized metric reductions are much faster, but they
occupy a smaller share once sorting dominates.
Pair suite¶
| n | v0.5 cold | v0.5 warm | 2023 cold | 2023 warm | current cold | current warm | current RSS |
|---|---|---|---|---|---|---|---|
| 500 | 2.51x | 5.22x | 2.08x | 3.08x | 0.0015 s | 0.0004 s | 126.1 MiB |
| 1,000 | 3.21x | 5.36x | 2.51x | 3.98x | 0.0051 s | 0.0015 s | 141.7 MiB |
| 2,000 | 3.32x | 4.55x | 2.80x | 3.41x | 0.0184 s | 0.0072 s | 199.9 MiB |
At 2,000 samples, v0.5.0 used 371.9 MiB peak RSS and the candidate used 199.9 MiB. Condensed/streamed unique pairs and one fused stable statistics pass produce both the speed and memory improvements.
Topology suite¶
| n | v0.5 cold | v0.5 warm | 2023 cold | 2023 warm | current cold | current warm | current RSS |
|---|---|---|---|---|---|---|---|
| 500 | 3.56x | 10.47x | 2.51x | 8.12x | 0.0336 s | 0.0098 s | 144.1 MiB |
| 1,000 | 3.38x | 6.36x | 1.91x | 4.33x | 0.0909 s | 0.0378 s | 162.3 MiB |
| 2,000 | 2.73x | 4.07x | 1.05x | 2.09x | 0.3399 s | 0.1587 s | 197.8 MiB |
The 2023 comparison is not like-for-like: the current score differs by as much
as 0.176 because Topographic Product and related edge cases were corrected after
2023. v0.5.0 and the candidate agree within 6.11e-15, making their 4.07x warm
comparison the reliable acceleration result.
Representative eight-metric suite¶
| n | v0.5 cold | v0.5 warm | 2023 cold | 2023 warm | current cold | current warm | current RSS |
|---|---|---|---|---|---|---|---|
| 500 | 2.76x | 4.31x | 2.50x | 3.91x | 0.0519 s | 0.0287 s | 141.5 MiB |
| 1,000 | 1.68x | 2.57x | 1.60x | 2.40x | 0.2097 s | 0.1107 s | 191.5 MiB |
| 2,000 | 1.14x | 1.64x | 1.09x | 1.52x | 0.9040 s | 0.4578 s | 398.3 MiB |
At 2,000 samples the current/v0.5.0 maximum score delta is 6.11e-15.
The 2023 maximum delta is 0.176, primarily reflecting corrected definitions;
its 1.52x warm figure should not be interpreted as equal semantic work.
Eight repeated projections show essentially the same conclusion: v0.5.0 took 5.921 s warm versus 3.651 s current (1.62x), and cold collection time fell from 6.204 s to 4.099 s (1.51x). Peak RSS stayed 525.4 MiB versus 398.4 MiB because one dense full-ranking plan determines the peak rather than collection length.
Accelerator results¶
These are explicit backends, not the auto default. The table uses the
representative suite and compares against v0.5.0 NumPy on the same machine.
| Backend | n | Cold speedup | Warm speedup | Candidate cold | Candidate warm | Peak RSS | Max score delta |
|---|---|---|---|---|---|---|---|
| MLX GPU float32 | 500 | 0.95x | 5.79x | 0.1442 s | 0.0213 s | 154.2 MiB | 6.39e-7 |
| MLX GPU float32 | 1,000 | 0.96x | 5.30x | 0.3720 s | 0.0544 s | 185.9 MiB | 1.43e-7 |
| MLX GPU float32 | 2,000 | 1.85x | 7.30x | 0.5557 s | 0.1006 s | 383.0 MiB | 9.09e-6 |
| Torch CPU float64 | 500 | 0.23x | 7.47x | 0.6092 s | 0.0165 s | 290.5 MiB | 2.78e-15 |
| Torch CPU float64 | 1,000 | 0.77x | 6.27x | 0.4687 s | 0.0455 s | 344.0 MiB | 4.33e-15 |
| Torch CPU float64 | 2,000 | 1.52x | 4.72x | 0.6786 s | 0.1561 s | 506.2 MiB | 6.11e-15 |
Warm accelerator speedups are large even at 500 samples, but framework startup makes cold runs slower there. The 2,000-sample suite crosses over on this machine. MLX is the best tested Apple path overall. Torch CPU preserves float64 parity but carries a large framework/import RSS footprint.
Against the 2023 source, MLX at 2,000 samples measured 6.83x warm / 1.76x cold, and Torch CPU measured 4.43x warm / 1.47x cold. Again, corrected 2023 metric semantics prevent those from being strict equal-output comparisons.
Torch MPS is resource-dependent rather than universally faster:
- Pairwise distance materialization was no faster end to end than SciPy because output transfer/host construction dominated.
- Full ranking was 5.23x faster than NumPy and stable-kNN was 2.60x faster on
the isolated
n=2,000resource benchmark. - Native batch width four made the eight-projection Torch MPS suite 2.21x faster warm than sequential Torch MPS, with zero score delta.
- MPS
linalg_svdfell back to CPU in the tested PyTorch build and the Procrustes prototype was 2.8–6.8x slower, so it was not integrated.
CUDA follows the same cdist, stable argsort, and batching code, but no CUDA
hardware was available. 0.5.1 makes no CUDA parity or speed claim.
Isolated kernel results¶
The current exact kernels were compared with slow reference formulas on the
same generated resources at n=2,000, 50 dimensions, and k=20.
| Kernel | Speedup | Absolute score delta |
|---|---|---|
| T&C | 20.72x | 0 |
| Class-aware T&C | 21.67x | 0 |
| MRRE | 6.34x | 0 |
| LCMC | 10.30x | 0 |
| Neighborhood Hit | 14.57x | 0 |
| Topographic Product | 77.82x | 1.78e-15 |
| Procrustes | 4.21x | 0 |
These isolate metric math after resource construction. The representative end-to-end 1.64x default speedup is the appropriate expectation for a mixed run, not the 77.82x maximum kernel result.
What changed¶
The observed gains come from several independent layers:
- Python-loop metric kernels became chunked vector operations and batched SVD.
- Typed planning deduplicates maximum-
kdistances, ranks, densities, and neighbor statistics across metrics. - Pair-only metrics use condensed or streamed unique pairs and fused stable reductions instead of two persistent dense matrices.
- Topographic Product stores
O(nk)neighbors and gathers selected distances rather than retaining two dense matrices. - SNC uses sparse SNN graphs and batched cluster-pair reductions.
- Repeated projections share immutable original resources and can use bounded CPU workers or provider-native tensor batches.
- MLX and PyTorch provide exact explicit hardware paths with per-resource fallback, dtype controls, and cold/warm/transfer diagnostics.
Approximation, sampling, approximate neighbors, and silent precision downgrade remain out of scope.
Reproduction¶
Create detached worktrees for the two historical tags and run:
git worktree add --detach /tmp/zadu-v0.1.1 v0.1.1
git worktree add --detach /tmp/zadu-v0.5.0 v0.5.0
python benchmarks/benchmark_release_history.py \
--source 2023-v0.1.1=/tmp/zadu-v0.1.1 \
--source pre-acceleration-v0.5.0=/tmp/zadu-v0.5.0 \
--source current=. \
--samples 500 1000 2000 --dimension 20 --k 20 --repeat 5 \
--json benchmarks/results/0.5.1/history-default.json
Use --accelerated-label current --backend mlx --device gpu --dtype float32
for the explicit MLX comparison. The committed raw records are under
benchmarks/results/0.5.1/; the benchmark README documents the resource and
native-batch commands.
Release verdict¶
The 0.5.1 acceleration gate passes:
- exact default outputs match v0.5.0 within floating-point noise;
- the maintained warm accelerator full-ranking target exceeds 8x through MLX's previously measured 23.75x resource speedup;
- focused exact workloads exceed 3x and the tested MLX representative suite exceeds 3x end to end;
- package-managed memory is planned or rejected before oversized allocation;
- optional frameworks remain lazy and separately packaged;
- CPU, MLX, and MPS parity jobs pass; CUDA remains explicitly unvalidated.
The realistic user-facing summary is: expect about 1.3–1.6x on a large mixed default run, 4–5x on focused pair/topology work, and up to 7.3x on the tested large mixed Apple-MLX warm path—not a universal 20–78x library-wide speedup.