distrand

🎲 Generate random numbers with spacing constraints — no collisions, no clutter.

📦 What is this?

distrand lets you generate random numbers (integers or floats) between two bounds, ensuring that all values are at least min_dist apart.

Perfect for:

• Spaced-out sampling
• Visualization
• Simulation
• Teaching randomness with constraints

🔧 Features

• 🧠 Smart spacing — every pair of values ≥ min_dist
• 🧮 Supports int and float generation
• 🚫 Automatically raises ValueError if impossible
• ⚡ Fast and NumPy-powered
• 📜 Apache 2.0 licensed

🚀 Installation

From PyPI:

pip install distrand

From source (for development):

git clone https://github.com/Eggman5800/distrand.git
cd distrand
pip install .

📚 Usage

from distrand import distrand

# Integer mode
nums = distrand(low=0, high=100, size=5, min_dist=10, dtype=int)

# Float mode
floats = distrand(low=0.0, high=5.0, size=4, min_dist=1.2, dtype=float)

🧪 It guarantees that:

• len(nums) == size
• abs(a - b) >= min_dist for all a, b pairs

🧪 Testing

Run the tests using pytest:

# Windows (PowerShell)
$env:PYTHONPATH = "src"
pytest

# Unix/macOS
PYTHONPATH=src pytest

Tests cover:

• Integer & float mode
• Invalid inputs (e.g. not enough space)
• Type conversions

🧑‍💻 Example Run

python usage_demo.py

Output:

🎲 Integer Mode Example:
Generated integers: [10 40 20 60 0]

🌊 Float Mode Example:
Generated floats: [0.   3.6 1.2 2.4]

🚫 Invalid Parameters Example:
Caught expected error: Cannot select 10 values from range [0, 10] with min_dist=5

🛡️ License

Licensed under the Apache License 2.0.

💡 Credits

Developed by Syed Talha.
Feedback, issues, and pull requests welcome!

🌠 Roadmap

• Publish to PyPI
• Add optional seed parameter (for reproducible results)
• Support output sorting (sort=True)
• Vectorized float optimization

---

🙌 Support

If you find this useful, give the repo a ⭐ or share it.
Feel free to open issues.