aleam 1.0.3

📌 The Problem

Pseudo-random number generators (PRNGs) like Mersenne Twister and Python's random are recursive:

xₙ₊₁ = (a·xₙ + c) mod m

This creates:

• 🔁 Hidden correlations — each number depends on the one before
• 📅 Periodicity — sequences eventually repeat
• 🧱 Exploration boundaries — AI can't truly explore
• 🎭 False reproducibility — same seed = same path

AI deserves better.

🎯 The Solution: Aleam

import aleam as al

rng = al.Aleam()
x = rng.random()  # True randomness. No recursion. No state.

Aleam implements the proven equation:

Ψ(t) = BLAKE2s( (Φ × Ξ(t)) ⊕ τ(t) )

Properties:

🔬 How It Works

The Core Equation in Detail

⚡ Performance: CPU vs GPU

Benchmarks pending - will be updated after Colab testing

💡 Key Insight: The C++ migration delivers significant CPU speedup over pure Python, while GPU acceleration provides massive parallel performance.

📊 Statistical Validation

After 2.55 million samples, Aleam passed all 10 rigorous tests:

"True randomness is not a bug — it's a feature."

🚀 Quick Start

Install from PyPI (recommended)

pip install aleam

Install from source

git clone https://github.com/fardinsabid/aleam.git
cd aleam
pip install .

Basic Usage

import aleam as al

# Create a true random generator
rng = al.Aleam()

# Core randomness
x = rng.random()                    # 0.90324326
u64 = rng.random_uint64()           # 12345678901234567890
y = rng.randint(1, 100)             # 86
z = rng.choice(['AI', 'ML', 'Aleam'])  # 'ML'
u = rng.uniform(5.0, 10.0)          # 7.234
n = rng.gauss(0.0, 1.0)            # -0.432

# Sampling (requires list, not range)
population = list(range(10000))
batch = rng.sample(population, 64)  # Random 64 unique indices

# Shuffle list in-place
items = [1, 2, 3, 4, 5]
rng.shuffle(items)                  # [3, 1, 5, 2, 4]

# Random bytes for cryptography
key = rng.random_bytes(32)          # 32 cryptographically secure bytes

✨ Features

🎲 Core Randomness

📈 Statistical Distributions

🧠 AI/ML Features

🔢 Array Operations

🔌 Framework Integrations

PyTorch

import torch
import aleam as al

gen = al.TorchGenerator(device='cuda' if torch.cuda.is_available() else 'cpu')
tensor = gen.randn(100, 100)      # True random tensor on GPU
tensor = gen.rand(100, 100)       # Uniform [0, 1) tensor
tensor = gen.randint(0, 10, (100, 100))  # Integer tensor

TensorFlow

import tensorflow as tf
import aleam as al

gen = al.TFGenerator()
tensor = gen.normal((100, 100), mean=0, stddev=1)
tensor = gen.uniform((100, 100), minval=0, maxval=1)
tensor = gen.randint((100, 100), minval=0, maxval=10)

JAX

import jax
import aleam as al

gen = al.JAXGenerator()
key = gen.key()                   # True random key
tensor = jax.random.normal(key, (100, 100))

CuPy (Fastest GPU)

import cupy as cp
import aleam as al

gen = al.CuPyGenerator()
arr = gen.randn((10000, 10000))   # True random on GPU
arr = gen.random((10000, 10000))  # Uniform on GPU
arr = gen.randint((10000, 10000), 0, 10)

Pandas

import pandas as pd
import aleam as al

gen = al.PandasGenerator()
series = gen.series(1000, distribution="normal", params="mu=0,sigma=1")
df = gen.dataframe(1000, columns=['a', 'b', 'c'])
shuffled = gen.shuffle(df)

NumPy

import aleam as al
import numpy as np

# Direct array generation
arr = al.random_array((100, 100))      # Returns list, convert to numpy if needed
np_arr = np.array(arr)

# Or use module-level functions
arr = al.random_array((1000,))          # 1D array
matrix = al.random_array((10, 10))      # 2D matrix
norm_arr = al.randn_array(1000, 0, 1)   # Normal distribution
int_arr = al.randint_array((50,), 0, 10) # Integers

⚡ CUDA Acceleration

Aleam provides GPU acceleration through multiple backends:

import aleam as al

# Automatic GPU acceleration (auto-detects best backend)
cuda_gen = al.CUDAGenerator()

# Generate true random numbers on GPU
cupy_arr = cuda_gen.cupy_random((10000, 10000))

# Or use with specific frameworks
torch_tensor = cuda_gen.torch_randn(10000, 10000, device='cuda')
tf_tensor = cuda_gen.tf_random_normal((10000, 10000))

📦 Installation Details

From PyPI (recommended for users)

pip install aleam

With Framework Support

# PyTorch
pip install aleam[torch]

# TensorFlow
pip install aleam[tensorflow]

# JAX
pip install aleam[jax]

# CuPy (for maximum GPU speed)
pip install aleam[cupy]

# Data science
pip install aleam[pandas]

# All frameworks
pip install aleam[all]

From Source (for development)

git clone https://github.com/fardinsabid/aleam.git
cd aleam
pip install .

Development Installation

pip install -e .[dev]

📁 Project Structure

aleam/
│
├── .github/
│   └── workflows/
│       ├── tests.yml
│       ├── publish.yml
│       ├── security.yml
│       └── docs.yml
│
├── aleam/
│   │
│   ├── __init__.py
│   └── py.typed
│
├── src/
│   │
│   └── aleam/
│       │
│       ├── bindings/
│       │   ├── module.cpp
│       │   └── exports.h
│       │
│       ├── core/
│       │   ├── aleam_core.h
│       │   ├── aleam_core.cpp
│       │   ├── constants.h
│       │   └── utils.h
│       │
│       ├── entropy/
│       │   ├── entropy.h
│       │   ├── entropy_linux.h
│       │   ├── entropy_windows.h
│       │   └── entropy_darwin.h
│       │
│       ├── hash/
│       │   ├── blake2s.h
│       │   └── blake2s_config.h
│       │
│       ├── distributions/
│       │   ├── distributions.h
│       │   ├── distributions.cpp
│       │   ├── normal.h
│       │   ├── exponential.h
│       │   ├── beta.h
│       │   ├── gamma.h
│       │   ├── poisson.h
│       │   ├── laplace.h
│       │   ├── logistic.h
│       │   ├── lognormal.h
│       │   ├── weibull.h
│       │   ├── pareto.h
│       │   ├── chi_square.h
│       │   ├── student_t.h
│       │   ├── f_distribution.h
│       │   └── dirichlet.h
│       │
│       ├── arrays/
│       │   ├── arrays.h
│       │   ├── arrays.cpp
│       │   └── array_utils.h
│       │
│       ├── ai/
│       │   ├── ai.h
│       │   ├── ai.cpp
│       │   ├── gradient_noise.h
│       │   ├── latent_sampler.h
│       │   └── augmentation.h
│       │
│       ├── integrations/
│       │   ├── integrations.h
│       │   ├── integrations.cpp
│       │   ├── torch_integration.h
│       │   ├── torch_integration.cpp
│       │   ├── tensorflow_integration.h
│       │   ├── tensorflow_integration.cpp
│       │   ├── jax_integration.h
│       │   ├── jax_integration.cpp
│       │   ├── cupy_integration.h
│       │   ├── cupy_integration.cpp
│       │   ├── pandas_integration.h
│       │   ├── pandas_integration.cpp
│       │   ├── polars_integration.h
│       │   ├── polars_integration.cpp
│       │   ├── xarray_integration.h
│       │   ├── xarray_integration.cpp
│       │   ├── pymc_integration.h
│       │   ├── pymc_integration.cpp
│       │   ├── dask_integration.h
│       │   └── dask_integration.cpp
│       │
│       └── cuda/
│           ├── cuda_kernels.h
│           ├── cuda_kernels.cu
│           ├── cuda_uniform.cu
│           ├── cuda_normal.cu
│           └── cuda_utils.h
│
├── include/
│   └── aleam/
│       └── aleam.h
│
├── tests/
│   ├── test_core.py
│   ├── test_ai.py
│   └── test_statistical.py
│
├── benchmarks/
│   └── benchmark_core.py
│
├── assets/
│   └── images/
│       ├── benchmarks/
│       │   ├── aleam_gpu_vs_lavarand_hd.png
│       │   └── cpu_vs_gpu.png
│       └── diagrams/
│            └── algorithm.png
│
│           
├── examples/
│   ├── basic_usage.py
│   ├── ai_ml_features.py
│   ├── array_operations.py
│   ├── distributions.py
│   ├── monte_carlo_pi.py
│   ├── reinforcement_learning.py
│   ├── cuda_integration.py
│   ├── pytorch_integration.py
│   └── tensorflow_integration.py
│
├── docs/
│   ├── ALEAM_RESEARCH_PAPER.md
│   └── index.md
│
├── setup.py
├── pyproject.toml
├── MANIFEST.in
├── requirements.txt
├── requirements-dev.txt
├── LICENSE
├── README.md
├── CONTRIBUTING.md
└── .gitignore

🔧 Troubleshooting

Q: Why is Aleam slower than random.random on CPU?

A: True randomness is slower than pseudo-random with the C++ core — that's expected. You're trading speed for genuine entropy. On GPU, Aleam achieves massive parallel performance.

Q: Can I seed Aleam for reproducible results?

A: No. Aleam is stateless by design. Call al.seed_free() to see the explanation. Use Python's random module if you need reproducibility.

Q: Is Aleam cryptographically secure?

A: Yes. Each call consumes 64 bits of true entropy and passes through BLAKE2s, a cryptographic hash.

Q: Does Aleam support GPU?

A: Yes! PyTorch, TensorFlow, JAX, and CuPy integrations all support GPU acceleration. Use al.CUDAGenerator() for automatic backend detection.

Q: Why does sample() require a list?

A: The C++ bindings accept Python lists directly. Use list(range(10000)) instead of range(10000).

Q: Will Aleam work on my platform?

A: Yes! Linux (getrandom), Windows (BCrypt), and macOS (arc4random) are all supported.

🔒 Responsible Use

• ✅ Use for AI research, exploration, and creative projects
• ✅ Use for scientific simulations requiring true randomness
• ✅ Use for cryptographic applications
• ❌ Do not use for security-critical systems without additional entropy sources
• ❌ Do not use to generate deceptive or harmful content

📄 License

MIT License — see LICENSE for details.

🌐 Links

🙏 Acknowledgments

• BLAKE2 team for the cryptographic hash function
• Open-source community for entropy source implementations
• Python community for the amazing ecosystem

True randomness. No recursion. No state. Just entropy.