roundamix 0.1.0

Roundabout-network stochastic stream shuffler

If you ever drove in Spain, you might notice their affinity for roundabouts. If you enter a system of 3 roundabouts in a village and take not of both the cars infront and behind you, by the last roundabout its highly probably you wont be between the same two neighbors.

Instead of a black-box shuffle, you get a tunable process with real controls: routing bias, merge randomness, recirculation depth, and injection strategy. The result is near-classic shuffle quality with more visibility and control.

• For data and systems teams: mix ordered streams before downstream processing without relying on one monolithic random shuffle step.
• For simulation and research: study queueing, congestion, and mixing quality in one model.
• For product and game systems: produce high-entropy but reproducible event ordering from seed-based runs.

Benchmark Snapshot

Our optimized roundabout shuffler is now close to standard random shuffling quality.

• Kendall-tau: 0.4907 (optimized) vs 0.5030 (Fisher-Yates) -> 97.5% of Fisher-Yates mixing.
• Chi-squared uniformity p-value: 0.5858 (optimized) vs 0.5546 (Fisher-Yates) -> both pass.
• Bit bias: +0.0051 (optimized) vs +0.0085 (Fisher-Yates) -> both near zero.
• Total variation distance: 0.0835 (optimized) vs 0.0824 (Fisher-Yates).

In short: this is not just a metaphor. It delivers near Fisher-Yates quality while staying interpretable, tunable, and simulation-friendly.

Package Usage

pip install -e .
roundamix --profile optimized --size 14 --seed 42
roundamix-benchmark --size 14 --trials 300

You can also run without installing:

python -m roundamix --profile optimized --size 14 --seed 42
python -m roundamix.benchmark --size 14 --trials 300