Random Number Generation (random)

The random module provides pseudo-random number generation capabilities.

Example

import numpycore as np

# Create a random generator
rng = np.random.default_rng(seed=42)

# Generate random numbers
uniform = rng.random(10)           # Uniform [0, 1)
integers = rng.integers(0, 100, 5)  # Random integers
normal = rng.normal(0, 1, 100)      # Standard normal

# Shuffle and permutation
arr = np.array([1, 2, 3, 4, 5])
rng.shuffle(arr)
perm = rng.permutation(arr)

Generator Class

The Generator class is the preferred interface for random number generation.

Function	Description	Example
random(size)	Random floats in [0.0, 1.0)	View
integers(low, high, size)	Random integers from low (inclusive) to high (exclusive)
choice(a, size, replace)	Random sample from array	View
shuffle(x)	Shuffle array in-place	View
permutation(x)	Random permutation	View

Distributions

Function	Description	Example
normal(loc, scale, size)	Normal (Gaussian) distribution	View
uniform(low, high, size)	Uniform distribution	View
exponential(scale, size)	Exponential distribution	View
poisson(lam, size)	Poisson distribution	View
binomial(n, p, size)	Binomial distribution	View
gamma(shape, scale, size)	Gamma distribution	View
beta(a, b, size)	Beta distribution	View
chisquare(df, size)	Chi-square distribution	View
standard_normal(size)	Standard normal distribution	View
standard_exponential(size)	Standard exponential distribution	View
lognormal(mean, sigma, size)	Log-normal distribution	View
weibull(a, size)	Weibull distribution	View
pareto(a, size)	Pareto distribution	View
multinomial(n, pvals, size)	Multinomial distribution	View
multivariate_normal(mean, cov, size)	Multivariate normal distribution	View

Legacy Functions

These functions use a global random state (legacy API):

Function	Description	Example
seed(seed)	Seed the random number generator	View
rand(*shape)	Random values in [0, 1)	View
randn(*shape)	Random standard normal values	View
randint(low, high, size)	Random integers	View
random_sample(size)	Random floats in [0.0, 1.0)	View

Code Examples

The following examples are extracted from the test suite.

random (test_phase4_random_complete.py:446)

    result = test_bind.numpycore.random.randn(3, 4)
    assert_shape_equal(result, (3, 4), "randn shape")
    # Should have mean ≈ 0 for large samples
    large = test_bind.numpycore.random.randn(1000)
    assert_approx_mean(large, 0.0, 0.3, "randn mean")


def test_random():
    """Test random() - random floats"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.random((3, 4))
    assert_shape_equal(result, (3, 4), "random shape")
    assert_range(result, 0.0, 1.0, "random range")


def test_random_integers():
    """Test random_integers() - deprecated but still supported"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.random_integers(10, None, (50,))
    assert_shape_equal(result, (50,), "random_integers shape")
    assert_range(result, 1, 10, "random_integers range", inclusive_max=True)

choice (test_choice_range_support.py:56)

        sys.exit(1)
    print(f"[OK] {test_name}: PASSED (dtype={actual_dtype})")

# ============================================================================
# Integer Input Tests
# ============================================================================

def test_choice_int_scalar():
    """Test choice(n) returns single value from [0, n)"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.choice(10)

    # NumPy parity
    test_bind.np.random.seed(42)
    expected = test_bind.np.random.choice(10)

    assert_values_in_range(result, 0, 10, 'choice_int_scalar_range')
    # Note: May not match NumPy exactly due to RNG differences
    print(f"[OK] choice_int_scalar_range: PASSED (numpyCore={result}, NumPy={expected})")

def test_choice_int_1d():

shuffle (test_phase4_random_complete.py:488)

    result = test_bind.numpycore.random.sample((3, 4))
    assert_shape_equal(result, (3, 4), "sample shape")
    assert_range(result, 0.0, 1.0, "sample range")


def test_shuffle():
    """Test shuffle() - shuffle array in-place"""
    test_bind.numpycore.random.seed(42)
    arr = test_bind.numpycore.arange(1.0, 6.0, 1.0)
    expected_sorted = test_bind.np.arange(1.0, 6.0, 1.0)
    test_bind.numpycore.random.shuffle(arr)
    # Check that all elements still present
    sorted_arr = test_bind.np.sort(arr)
    if not test_bind.np.allclose(sorted_arr, expected_sorted):
        print("[FAIL] shuffle: Elements not preserved")
        sys.exit(1)
    print("[OK] shuffle: elements preserved")


# ============================================================================
# Utility Functions (8 functions)

permutation (test_phase4_random_complete.py:361)

    test_bind.numpycore.random.seed(42)
    arr = test_bind.numpycore.arange(1.0, 11.0, 1.0)
    result = test_bind.numpycore.random.choice(arr, size=5, replace=False)
    assert_shape_equal(result, (5,), "choice shape")


def test_permutation():
    """Test random permutation"""
    test_bind.numpycore.random.seed(42)
    arr = test_bind.numpycore.arange(1.0, 11.0, 1.0)
    result = test_bind.numpycore.random.permutation(arr)
    assert_shape_equal(result, (10,), "permutation shape")


# ============================================================================
# Multivariate Distributions (3 functions - NEW in Phase 4)
# ============================================================================

def test_dirichlet():
    """Test Dirichlet distribution (NEW in Phase 4)"""
    test_bind.numpycore.random.seed(42)

normal (test_phase4_random_complete.py:131)

    result = test_bind.numpycore.random.geometric(0.5, (100,))
    assert_shape_equal(result, (100,), "geometric shape")
    assert_all_positive(result, "geometric positive")
    # Geometric(p) has mean = 1/p
    assert_approx_mean(result, 2.0, 0.5, "geometric mean")


def test_normal():
    """Test normal distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.normal(5.0, 2.0, (100,))
    assert_shape_equal(result, (100,), "normal shape")
    # Normal(mu, sigma) has mean = mu
    assert_approx_mean(result, 5.0, 0.5, "normal mean")


def test_poisson():
    """Test Poisson distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.poisson(5.0, (100,))
    assert_shape_equal(result, (100,), "poisson shape")

uniform (test_phase4_random_complete.py:149)

    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.poisson(5.0, (100,))
    assert_shape_equal(result, (100,), "poisson shape")
    # Poisson(lambda) has mean = lambda
    assert_approx_mean(result, 5.0, 1.0, "poisson mean")


def test_uniform():
    """Test uniform distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.uniform(2.0, 8.0, (100,))
    assert_shape_equal(result, (100,), "uniform shape")
    assert_range(result, 2.0, 8.0, "uniform range")
    # Uniform(a, b) has mean = (a+b)/2
    assert_approx_mean(result, 5.0, 0.5, "uniform mean")


def test_weibull():
    """Test Weibull distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.weibull(2.0, (100,))

exponential (test_phase4_random_complete.py:101)

    result = test_bind.numpycore.random.chisquare(5.0, (100,))
    assert_shape_equal(result, (100,), "chisquare shape")
    assert_all_positive(result, "chisquare positive")
    # Chi-square(k) has mean = k
    assert_approx_mean(result, 5.0, 1.0, "chisquare mean")


def test_exponential():
    """Test exponential distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.exponential(2.0, (100,))
    assert_shape_equal(result, (100,), "exponential shape")
    assert_all_positive(result, "exponential positive")
    # Exponential(scale) has mean = scale
    assert_approx_mean(result, 2.0, 0.5, "exponential mean")


def test_gamma():
    """Test gamma distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.gamma(2.0, 2.0, (100,))

poisson (test_phase4_random_complete.py:140)

    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.normal(5.0, 2.0, (100,))
    assert_shape_equal(result, (100,), "normal shape")
    # Normal(mu, sigma) has mean = mu
    assert_approx_mean(result, 5.0, 0.5, "normal mean")


def test_poisson():
    """Test Poisson distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.poisson(5.0, (100,))
    assert_shape_equal(result, (100,), "poisson shape")
    # Poisson(lambda) has mean = lambda
    assert_approx_mean(result, 5.0, 1.0, "poisson mean")


def test_uniform():
    """Test uniform distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.uniform(2.0, 8.0, (100,))
    assert_shape_equal(result, (100,), "uniform shape")

binomial (test_phase4_random_complete.py:81)

    result = test_bind.numpycore.random.beta(2.0, 5.0, (100,))
    assert_shape_equal(result, (100,), "beta shape")
    assert_range(result, 0.0, 1.0, "beta range")
    # Beta(2,5) has mean = a/(a+b) = 2/7 ≈ 0.286
    assert_approx_mean(result, 2.0/7.0, 0.1, "beta mean")


def test_binomial():
    """Test binomial distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.binomial(10, 0.5, (100,))
    assert_shape_equal(result, (100,), "binomial shape")
    assert_range(result, 0, 10, "binomial range", inclusive_max=True)
    # Binomial(10, 0.5) has mean = n*p = 5
    assert_approx_mean(result, 5.0, 1.0, "binomial mean")


def test_chisquare():
    """Test chi-square distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.chisquare(5.0, (100,))

gamma (test_phase4_random_complete.py:111)

    result = test_bind.numpycore.random.exponential(2.0, (100,))
    assert_shape_equal(result, (100,), "exponential shape")
    assert_all_positive(result, "exponential positive")
    # Exponential(scale) has mean = scale
    assert_approx_mean(result, 2.0, 0.5, "exponential mean")


def test_gamma():
    """Test gamma distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.gamma(2.0, 2.0, (100,))
    assert_shape_equal(result, (100,), "gamma shape")
    assert_all_positive(result, "gamma positive")
    # Gamma(shape, scale) has mean = shape * scale
    assert_approx_mean(result, 4.0, 1.0, "gamma mean")


def test_geometric():
    """Test geometric distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.geometric(0.5, (100,))

beta (test_phase4_random_complete.py:71)

    print(f"[OK] {test_name}: all positive")


# ============================================================================
# Basic Distributions (11 functions)
# ============================================================================

def test_beta():
    """Test beta distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.beta(2.0, 5.0, (100,))
    assert_shape_equal(result, (100,), "beta shape")
    assert_range(result, 0.0, 1.0, "beta range")
    # Beta(2,5) has mean = a/(a+b) = 2/7 ≈ 0.286
    assert_approx_mean(result, 2.0/7.0, 0.1, "beta mean")


def test_binomial():
    """Test binomial distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.binomial(10, 0.5, (100,))

chisquare (test_phase3_noncentral.py:30)

    mean_np = test_bind.np.mean(samples_np)
    expected_mean = 5.0 + 2.5  # df + nonc

    assert abs(mean_nc - expected_mean) < 0.5, f"Mean {mean_nc} far from expected {expected_mean}"
    print(f"[OK] noncentral_chisquare basic: mean={mean_nc:.3f}, expected={expected_mean:.3f}")

def test_noncentral_chisquare_edge_case():
    """Test noncentral_chisquare with nonc=0 (should match central)"""
    # When nonc=0, should match central chi-square
    samples_nc = test_bind.numpycore.random.noncentral_chisquare(5.0, 0.0, (1000,))
    samples_central = test_bind.numpycore.random.chisquare(5.0, (1000,))

    mean_nc = test_bind.np.mean(samples_nc)
    mean_c = test_bind.np.mean(samples_central)

    # Both should have mean close to df=5
    assert abs(mean_nc - 5.0) < 0.3, f"Noncentral mean {mean_nc} should be near 5.0"
    assert abs(mean_c - 5.0) < 0.3, f"Central mean {mean_c} should be near 5.0"
    print(f"[OK] noncentral_chisquare edge case: nonc=0 (mean_nc={mean_nc:.3f}, mean_c={mean_c:.3f})")

def test_noncentral_f_basic():

standard_normal (test_phase4_random_complete.py:270)

    """Test standard gamma distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_gamma(2.0, (100,))
    assert_shape_equal(result, (100,), "standard_gamma shape")
    assert_all_positive(result, "standard_gamma positive")


def test_standard_normal():
    """Test standard normal distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_normal((100,))
    assert_shape_equal(result, (100,), "standard_normal shape")
    # Standard normal has mean = 0
    assert_approx_mean(result, 0.0, 0.3, "standard_normal mean")


def test_standard_t():
    """Test standard Student's t distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_t(5.0, (100,))
    assert_shape_equal(result, (100,), "standard_t shape")

standard_exponential (test_phase4_random_complete.py:252)

def test_standard_cauchy():
    """Test standard Cauchy distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_cauchy((100,))
    assert_shape_equal(result, (100,), "standard_cauchy shape")


def test_standard_exponential():
    """Test standard exponential distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_exponential((100,))
    assert_shape_equal(result, (100,), "standard_exponential shape")
    assert_all_positive(result, "standard_exponential positive")
    # Standard exponential has mean = 1
    assert_approx_mean(result, 1.0, 0.3, "standard_exponential mean")


def test_standard_gamma():
    """Test standard gamma distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_gamma(2.0, (100,))

lognormal (test_phase4_random_complete.py:214)

    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.logistic(0.0, 1.0, (100,))
    assert_shape_equal(result, (100,), "logistic shape")
    # Logistic(mu, s) has mean = mu
    assert_approx_mean(result, 0.0, 0.5, "logistic mean")


def test_lognormal():
    """Test log-normal distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.lognormal(0.0, 1.0, (100,))
    assert_shape_equal(result, (100,), "lognormal shape")
    assert_all_positive(result, "lognormal positive")


def test_logseries():
    """Test logarithmic series distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.logseries(0.5, (100,))
    assert_shape_equal(result, (100,), "logseries shape")
    assert_all_positive(result, "logseries positive")

weibull (test_phase4_random_complete.py:159)

    result = test_bind.numpycore.random.uniform(2.0, 8.0, (100,))
    assert_shape_equal(result, (100,), "uniform shape")
    assert_range(result, 2.0, 8.0, "uniform range")
    # Uniform(a, b) has mean = (a+b)/2
    assert_approx_mean(result, 5.0, 0.5, "uniform mean")


def test_weibull():
    """Test Weibull distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.weibull(2.0, (100,))
    assert_shape_equal(result, (100,), "weibull shape")
    assert_all_positive(result, "weibull positive")


def test_zipf():
    """Test Zipf distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.zipf(2.0, (100,))
    assert_shape_equal(result, (100,), "zipf shape")
    assert_all_positive(result, "zipf positive")

pareto (test_phase4_random_complete.py:237)

def test_negative_binomial():
    """Test negative binomial distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.negative_binomial(10, 0.5, (100,))
    assert_shape_equal(result, (100,), "negative_binomial shape")


def test_pareto():
    """Test Pareto distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.pareto(3.0, (100,))
    assert_shape_equal(result, (100,), "pareto shape")
    assert_all_positive(result, "pareto positive")


def test_standard_cauchy():
    """Test standard Cauchy distribution"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.standard_cauchy((100,))
    assert_shape_equal(result, (100,), "standard_cauchy shape")

multinomial (test_phase4_random_complete.py:389)

            print(f"[FAIL] dirichlet: Sample {i} sums to {s}, not 1.0")
            sys.exit(1)
    print("[OK] dirichlet: all samples sum to 1.0")


def test_multinomial():
    """Test multinomial distribution (NEW in Phase 4)"""
    test_bind.numpycore.random.seed(42)
    n = 20
    pvals = [1/6.0] * 6  # Fair dice
    result = test_bind.numpycore.random.multinomial(n, pvals, 5)
    assert_shape_equal(result, (5, 6), "multinomial shape")
    # Each sample should sum to n
    sums = test_bind.np.sum(result, axis=1)
    for i, s in enumerate(sums):
        if s != n:
            print(f"[FAIL] multinomial: Sample {i} sums to {s}, not {n}")
            sys.exit(1)
    print("[OK] multinomial: all samples sum to n")

multivariate_normal (test_phase4_random_complete.py:405)

            print(f"[FAIL] multinomial: Sample {i} sums to {s}, not {n}")
            sys.exit(1)
    print("[OK] multinomial: all samples sum to n")


def test_multivariate_normal():
    """Test multivariate normal distribution (NEW in Phase 4)"""
    test_bind.numpycore.random.seed(42)
    mean = [0.0, 0.0]
    cov = [[1.0, 0.0], [0.0, 1.0]]
    result = test_bind.numpycore.random.multivariate_normal(mean, cov, 100)
    assert_shape_equal(result, (100, 2), "multivariate_normal shape")
    # Mean of each dimension should be close to 0
    mean_0 = test_bind.np.mean(result[:, 0])
    mean_1 = test_bind.np.mean(result[:, 1])
    print(f"[OK] multivariate_normal: means [{mean_0:.4f}, {mean_1:.4f}] ~= [0, 0]")


# ============================================================================
# Random Number Generators (9 functions)
# ============================================================================

seed (test_choice_range_support.py:55)

        print(f"  Actual: {actual_dtype}")
        sys.exit(1)
    print(f"[OK] {test_name}: PASSED (dtype={actual_dtype})")

# ============================================================================
# Integer Input Tests
# ============================================================================

def test_choice_int_scalar():
    """Test choice(n) returns single value from [0, n)"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.choice(10)

    # NumPy parity
    test_bind.np.random.seed(42)
    expected = test_bind.np.random.choice(10)

    assert_values_in_range(result, 0, 10, 'choice_int_scalar_range')
    # Note: May not match NumPy exactly due to RNG differences
    print(f"[OK] choice_int_scalar_range: PASSED (numpyCore={result}, NumPy={expected})")

rand (test_choice_range_support.py:128)

    result = test_bind.numpycore.random.choice(range(20), size=5)

    assert_values_in_range(result, 0, 20, 'choice_range_basic')

def test_choice_range_kmeans_pattern():
    """Test the exact K-Means pattern: X[np.random.choice(range(m))]"""
    test_bind.numpycore.random.seed(48)

    # Simulate K-Means initialization
    m = 300  # Number of data points
    X = test_bind.numpycore.random.rand(m, 2)  # 300 data points, 2 features

    # This is the failing line from K-Means test
    idx = test_bind.numpycore.random.choice(range(m))
    idx_int = int(test_bind.np.asarray(idx))

    # Access array element using integer index
    centroid = X[idx_int]

    if centroid.shape != (2,):
        print(f"[FAIL] test_choice_range_kmeans_pattern: Expected shape (2,), got {centroid.shape}")

randn (test_phase4_random_complete.py:436)

    """Test randint() - random integers"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.randint(0, 10, size=20)
    assert_shape_equal(result, (20,), "randint shape")
    assert_range(result, 0, 10, "randint range")


def test_randn():
    """Test randn() - standard normal samples"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.randn(3, 4)
    assert_shape_equal(result, (3, 4), "randn shape")
    # Should have mean ≈ 0 for large samples
    large = test_bind.numpycore.random.randn(1000)
    assert_approx_mean(large, 0.0, 0.3, "randn mean")


def test_random():
    """Test random() - random floats"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.random((3, 4))

randint (test_phase4_random_complete.py:428)

    """Test rand() - random floats in [0, 1)"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.rand(3, 4)
    assert_shape_equal(result, (3, 4), "rand shape")
    assert_range(result, 0.0, 1.0, "rand range")


def test_randint():
    """Test randint() - random integers"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.randint(0, 10, size=20)
    assert_shape_equal(result, (20,), "randint shape")
    assert_range(result, 0, 10, "randint range")


def test_randn():
    """Test randn() - standard normal samples"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.randn(3, 4)
    assert_shape_equal(result, (3, 4), "randn shape")
    # Should have mean ≈ 0 for large samples

random_sample (test_phase4_random_complete.py:462)

    """Test random_integers() - deprecated but still supported"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.random_integers(10, None, (50,))
    assert_shape_equal(result, (50,), "random_integers shape")
    assert_range(result, 1, 10, "random_integers range", inclusive_max=True)


def test_random_sample():
    """Test random_sample() - alias for random()"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.random_sample((3, 4))
    assert_shape_equal(result, (3, 4), "random_sample shape")
    assert_range(result, 0.0, 1.0, "random_sample range")


def test_ranf():
    """Test ranf() - alias for random()"""
    test_bind.numpycore.random.seed(42)
    result = test_bind.numpycore.random.ranf((3, 4))
    assert_shape_equal(result, (3, 4), "ranf shape")
    assert_range(result, 0.0, 1.0, "ranf range")