butrand 0.0.1

Fast and chaotic random number generator based on butterfly effect

🦋 butrand

butrand là một thư viện Python nhỏ gọn giúp sinh số ngẫu nhiên (PRNG) với tính hỗn loạn cao, dựa trên hiệu ứng cánh bướm (butterfly effect) và logistic map, kết hợp SHA‑256 để tăng cường entropy.

---

🚀 Giới thiệu

Trình sinh số ngẫu nhiên tiêu chuẩn của Python (random) đã rất mạnh mẽ, nhưng đôi khi ta muốn một PRNG:

• Độ nhạy cao với seed (một thay đổi rất nhỏ của seed dẫn đến chuỗi kết quả hoàn toàn khác biệt).
• Phân phối xấp xỉ đều nhưng dựa trên lý thuyết hỗn loạn.
• Dễ tái hiện (deterministic nếu đặt seed) để phục vụ mô phỏng.

butrand đáp ứng các yêu cầu này bằng cách:

1. Sinh hai chuỗi hỗn loạn x và y song song qua logistic map.
2. Trộn hai giá trị (x + y + x*y) để mở rộng dãy.
3. Băm kết quả bằng SHA‑256 và lấy 64 bit đầu (16 hex digit) thành số nguyên.
4. Quy đổi về float hoặc integer tùy hàm random() hoặc randint(a,b).

---

🧠 Phân tích chi tiết thuật toán

1. Logistic map

Phương trình logistic map:

xₙ₊₁ = r · xₙ · (1 − xₙ)

• Với r≈3.99, hệ bước vào vùng hỗn loạn, cực kỳ nhạy với giá trị ban đầu x₀.
• Dòng tương tự cho yₙ.

2. Trộn và băm

• Tại mỗi bước:
  1. Cập nhật x, y qua _logistic_step().
  2. Tính mixed = (x + y + x*y) mod 1.
  3. Băm SHA‑256 của chuỗi f"{mixed:.16f}{counter}".
  4. Lấy 16 ký tự hex đầu → 64 bits → int_val.
  5. random() = int_val / 0xFFFFFFFFFFFFFFFF ∈ [0,1).

Điều này giúp:

• Giảm bias: trộn hai chuỗi.
• Tăng entropy: SHA‑256 phá vỡ mối quan hệ tuyến tính.
• Tái hiện: với cùng seed & counter, chuỗi giống hệt.

---

📦 Cài đặt

    pip install butrand

Lưu ý: butrand yêu cầu Python 3.7 trở lên.

git clone https://github.com/OmeraGod/butrand.git cd butrand pip install -e .

🧪 Hướng dẫn sử dụng

1. Import thư viện:

from butrand import BetterRand

# Với seed cố định, giúp kết quả luôn lặp lại
rng = BetterRand(seed=2025)

• Nếu không truyền seed, BetterRand() sẽ tự động lấy thời gian hiện tại (ms).

2. random()

# Trả về float trong [0,1)
for _ in range(5):
    print(rng.random())

Giải thích:

• Mỗi lần gọi, x và y được cập nhật qua logistic map, trộn & băm → giá trị mới cực kỳ hỗn loạn.

3. randint(a, b)

# Trả về integer trong [a,b]
print([rng.randint(10, 20) for _ in range(5)])

Giải thích:

• randint tận dụng random() để phân phối đồng đều trên khoảng [a, b].

4. Ví dụ đầy đủ

from butrand import BetterRand

rng = BetterRand(seed=12345)

print("Floats:", [f"{rng.random():.6f}" for _ in range(5)])
print("Ints 1–10:", [rng.randint(1, 10) for _ in range(5)])

Ví dụ đầu ra (mỗi lần seed=12345):

Floats: ['0.102632', '0.982467', '0.985985', '0.004041', '0.024338']
Ints 1–10: [2, 10, 10, 1, 2]

📈 Ứng dụng

• Mô phỏng: cần chuỗi ngẫu nhiên có tính hỗn loạn cao.
• Game: sinh vật, bản đồ, sự kiện bất ngờ.
• Nghiên cứu: thử nghiệm PRNG mới, phân tích hỗn loạn.

🔐 License

Phân phối theo giấy phép MIT. Xem chi tiết trong file LICENSE.

👨‍💻 Tác giả

Bùi Phong Phú — Developer
📧 [e-mail]
💻 GitHub – OmeraGod