Metadata-Version: 2.4
Name: roundamix
Version: 0.1.1
Summary: Roundabout-network stochastic stream shuffler
Author: Daniel Alves Rösel
Project-URL: Homepage, https://github.com/velocitatem/roundamix
Project-URL: Repository, https://github.com/velocitatem/roundamix
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: pillow>=10.0; extra == "viz"
Provides-Extra: benchmark
Requires-Dist: numpy>=1.26; extra == "benchmark"
Requires-Dist: scipy>=1.11; extra == "benchmark"
Requires-Dist: matplotlib>=3.8; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

![](./roundabout.gif)

> 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

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

You can also run without installing:

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