0
# Random Number Generation
1

2
GPU-accelerated random number generation through cuRAND integration, supporting various probability distributions and random sampling operations with high performance on GPU. CuPy provides both legacy RandomState API and modern Generator API for comprehensive random number capabilities.
3

4
## Capabilities
5

6
### Random State Management
7

8
Control random number generation state and seeding for reproducible results.
9

10
```python { .api }
11
class RandomState:
12
    """Container for Mersenne Twister pseudo-random number generator.
13
    
14
    Provides legacy NumPy-compatible interface for random number generation
15
    with GPU acceleration through cuRAND.
16
    """
17
    
18
    def __init__(self, seed=None):
19
        """Initialize random state.
20
        
21
        Parameters:
22
        - seed: int, array-like, or None, random seed for initialization
23
        """
24

25
def get_random_state():
26
    """Get current global random state.
27
    
28
    Returns:
29
    RandomState: current global random number generator
30
    """
31

32
def set_random_state(rs):
33
    """Set global random state.
34
    
35
    Parameters:
36
    - rs: RandomState, random state to set as global
37
    """
38

39
def seed(seed=None):
40
    """Seed global random number generator.
41
    
42
    Parameters:
43
    - seed: int, array-like, or None, random seed
44
    """
45

46
def reset_states():
47
    """Reset all random states to default."""
48
```
49

50
### Modern Generator API
51

52
Advanced random number generation with improved statistical properties.
53

54
```python { .api }
55
class Generator:
56
    """Random number generator using modern algorithms.
57
    
58
    Provides improved random number generation with better statistical
59
    properties and performance compared to legacy RandomState.
60
    """
61

62
class BitGenerator:
63
    """Base class for bit generators.
64
    
65
    Provides low-level random bit generation for Generator classes.
66
    """
67

68
class XORWOW:
69
    """XORWOW bit generator.
70
    
71
    High-performance pseudo-random number generator optimized for GPU.
72
    """
73

74
class MRG32k3a:
75
    """MRG32k3a bit generator.
76
    
77
    Combined multiple recursive generator with excellent statistical properties.
78
    """
79

80
class Philox4x3210:
81
    """Philox bit generator.
82
    
83
    Counter-based random number generator with parallel generation capability.
84
    """
85

86
def default_rng(seed=None):
87
    """Construct new Generator with default BitGenerator.
88
    
89
    Parameters:
90
    - seed: int, array-like, or None, random seed
91
    
92
    Returns:
93
    Generator: new random number generator
94
    """
95
```
96

97
### Simple Random Data
98

99
Basic random number generation functions for common use cases.
100

101
```python { .api }
102
def random(size=None):
103
    """Random floats in half-open interval [0.0, 1.0).
104
    
105
    Parameters:
106
    - size: int or tuple of ints, output shape
107
    
108
    Returns:
109
    cupy.ndarray: array of random floats
110
    """
111

112
def rand(*size):
113
    """Random values in [0, 1) with given shape.
114
    
115
    Parameters:
116
    - size: int arguments, dimensions of output array
117
    
118
    Returns:
119
    cupy.ndarray: array of random values
120
    """
121

122
def randn(*size):
123
    """Standard normal distribution with given shape.
124
    
125
    Parameters:
126
    - size: int arguments, dimensions of output array
127
    
128
    Returns:
129
    cupy.ndarray: array of random values from N(0,1)
130
    """
131

132
def random_sample(size=None):
133
    """Random floats in [0.0, 1.0) (alias for random)."""
134

135
def ranf(size=None):
136
    """Random floats in [0.0, 1.0) (alias for random)."""
137

138
def sample(size=None):
139
    """Random floats in [0.0, 1.0) (alias for random)."""
140
```
141

142
### Integer Random Numbers
143

144
Generate random integers within specified ranges.
145

146
```python { .api }
147
def randint(low, high=None, size=None, dtype='l'):
148
    """Random integers from low (inclusive) to high (exclusive).
149
    
150
    Parameters:
151
    - low: int, lowest integer to draw (inclusive)
152
    - high: int, highest integer to draw (exclusive)
153
    - size: int or tuple of ints, output shape
154
    - dtype: str or dtype, data type of output
155
    
156
    Returns:
157
    cupy.ndarray: array of random integers
158
    """
159

160
def random_integers(low, high=None, size=None):
161
    """Random integers between low and high, inclusive.
162
    
163
    Parameters:
164
    - low: int, lowest integer (inclusive)
165
    - high: int, highest integer (inclusive)
166
    - size: int or tuple of ints, output shape
167
    
168
    Returns:
169
    cupy.ndarray: array of random integers
170
    """
171
```
172

173
### Continuous Distributions
174

175
Random sampling from continuous probability distributions.
176

177
```python { .api }
178
def normal(loc=0.0, scale=1.0, size=None):
179
    """Draw samples from normal (Gaussian) distribution.
180
    
181
    Parameters:
182
    - loc: float or array-like, mean of distribution
183
    - scale: float or array-like, standard deviation
184
    - size: int or tuple of ints, output shape
185
    
186
    Returns:
187
    cupy.ndarray: drawn samples
188
    """
189

190
def uniform(low=0.0, high=1.0, size=None):
191
    """Draw samples from uniform distribution.
192
    
193
    Parameters:
194
    - low: float or array-like, lower boundary
195
    - high: float or array-like, upper boundary
196
    - size: int or tuple of ints, output shape
197
    
198
    Returns:
199
    cupy.ndarray: drawn samples
200
    """
201

202
def exponential(scale=1.0, size=None):
203
    """Draw samples from exponential distribution.
204
    
205
    Parameters:
206
    - scale: float or array-like, scale parameter (1/rate)
207
    - size: int or tuple of ints, output shape
208
    
209
    Returns:
210
    cupy.ndarray: drawn samples
211
    """
212

213
def gamma(shape, scale=1.0, size=None):
214
    """Draw samples from Gamma distribution.
215
    
216
    Parameters:
217
    - shape: float or array-like, shape parameter
218
    - scale: float or array-like, scale parameter
219
    - size: int or tuple of ints, output shape
220
    
221
    Returns:
222
    cupy.ndarray: drawn samples
223
    """
224

225
def beta(a, b, size=None):
226
    """Draw samples from Beta distribution.
227
    
228
    Parameters:
229
    - a: float or array-like, alpha parameter
230
    - b: float or array-like, beta parameter
231
    - size: int or tuple of ints, output shape
232
    
233
    Returns:
234
    cupy.ndarray: drawn samples
235
    """
236

237
def chisquare(df, size=None):
238
    """Draw samples from chi-square distribution.
239
    
240
    Parameters:
241
    - df: float or array-like, degrees of freedom
242
    - size: int or tuple of ints, output shape
243
    
244
    Returns:
245
    cupy.ndarray: drawn samples
246
    """
247

248
def f(dfnum, dfden, size=None):
249
    """Draw samples from F distribution.
250
    
251
    Parameters:
252
    - dfnum: float or array-like, degrees of freedom in numerator
253
    - dfden: float or array-like, degrees of freedom in denominator
254
    - size: int or tuple of ints, output shape
255
    
256
    Returns:
257
    cupy.ndarray: drawn samples
258
    """
259

260
def lognormal(mean=0.0, sigma=1.0, size=None):
261
    """Draw samples from log-normal distribution."""
262

263
def standard_normal(size=None):
264
    """Draw samples from standard normal distribution N(0,1)."""
265

266
def standard_exponential(size=None):
267
    """Draw samples from standard exponential distribution."""
268

269
def standard_gamma(shape, size=None):
270
    """Draw samples from standard Gamma distribution."""
271

272
def standard_cauchy(size=None):
273
    """Draw samples from standard Cauchy distribution."""
274

275
def standard_t(df, size=None):
276
    """Draw samples from Student's t-distribution."""
277

278
def laplace(loc=0.0, scale=1.0, size=None):
279
    """Draw samples from Laplace distribution."""
280

281
def logistic(loc=0.0, scale=1.0, size=None):
282
    """Draw samples from logistic distribution."""
283

284
def gumbel(loc=0.0, scale=1.0, size=None):
285
    """Draw samples from Gumbel distribution."""
286

287
def weibull(a, size=None):
288
    """Draw samples from Weibull distribution."""
289

290
def pareto(a, size=None):
291
    """Draw samples from Pareto II distribution."""
292

293
def power(a, size=None):
294
    """Draw samples from power distribution."""
295

296
def rayleigh(scale=1.0, size=None):
297
    """Draw samples from Rayleigh distribution."""
298

299
def triangular(left, mode, right, size=None):
300
    """Draw samples from triangular distribution."""
301

302
def vonmises(mu, kappa, size=None):
303
    """Draw samples from von Mises distribution."""
304

305
def wald(mean, scale, size=None):
306
    """Draw samples from Wald distribution."""
307
```
308

309
### Multivariate Distributions
310

311
Sample from multivariate probability distributions.
312

313
```python { .api }
314
def multivariate_normal(mean, cov, size=None, check_valid='warn', tol=1e-8):
315
    """Draw samples from multivariate normal distribution.
316
    
317
    Parameters:
318
    - mean: 1-D array-like, mean of distribution
319
    - cov: 2-D array-like, covariance matrix
320
    - size: int or tuple of ints, output shape
321
    - check_valid: str, behavior when covariance is not valid
322
    - tol: float, tolerance for eigenvalue check
323
    
324
    Returns:
325
    cupy.ndarray: drawn samples
326
    """
327

328
def dirichlet(alpha, size=None):
329
    """Draw samples from Dirichlet distribution.
330
    
331
    Parameters:
332
    - alpha: sequence of floats, concentration parameters
333
    - size: int or tuple of ints, output shape
334
    
335
    Returns:
336
    cupy.ndarray: drawn samples
337
    """
338

339
def multinomial(n, pvals, size=None):
340
    """Draw samples from multinomial distribution.
341
    
342
    Parameters:
343
    - n: int, number of trials
344
    - pvals: sequence of floats, probabilities of each outcome
345
    - size: int or tuple of ints, output shape
346
    
347
    Returns:
348
    cupy.ndarray: drawn samples
349
    """
350
```
351

352
### Discrete Distributions
353

354
Random sampling from discrete probability distributions.
355

356
```python { .api }
357
def binomial(n, p, size=None):
358
    """Draw samples from binomial distribution.
359
    
360
    Parameters:
361
    - n: int or array-like, number of trials
362
    - p: float or array-like, probability of success
363
    - size: int or tuple of ints, output shape
364
    
365
    Returns:
366
    cupy.ndarray: drawn samples
367
    """
368

369
def poisson(lam=1.0, size=None):
370
    """Draw samples from Poisson distribution.
371
    
372
    Parameters:
373
    - lam: float or array-like, expected number of events
374
    - size: int or tuple of ints, output shape
375
    
376
    Returns:
377
    cupy.ndarray: drawn samples
378
    """
379

380
def geometric(p, size=None):
381
    """Draw samples from geometric distribution.
382
    
383
    Parameters:
384
    - p: float or array-like, probability of success
385
    - size: int or tuple of ints, output shape
386
    
387
    Returns:
388
    cupy.ndarray: drawn samples
389
    """
390

391
def negative_binomial(n, p, size=None):
392
    """Draw samples from negative binomial distribution."""
393

394
def hypergeometric(ngood, nbad, nsample, size=None):
395
    """Draw samples from hypergeometric distribution."""
396

397
def logseries(p, size=None):
398
    """Draw samples from logarithmic series distribution."""
399

400
def zipf(a, size=None):
401
    """Draw samples from Zipf distribution."""
402
```
403

404
### Advanced Distributions
405

406
Specialized and advanced probability distributions.
407

408
```python { .api }
409
def noncentral_chisquare(df, nonc, size=None):
410
    """Draw samples from noncentral chi-square distribution.
411
    
412
    Parameters:
413
    - df: float or array-like, degrees of freedom
414
    - nonc: float or array-like, non-centrality parameter
415
    - size: int or tuple of ints, output shape
416
    
417
    Returns:
418
    cupy.ndarray: drawn samples
419
    """
420

421
def noncentral_f(dfnum, dfden, nonc, size=None):
422
    """Draw samples from noncentral F distribution.
423
    
424
    Parameters:
425
    - dfnum: float or array-like, degrees of freedom in numerator
426
    - dfden: float or array-like, degrees of freedom in denominator  
427
    - nonc: float or array-like, non-centrality parameter
428
    - size: int or tuple of ints, output shape
429
    
430
    Returns:
431
    cupy.ndarray: drawn samples
432
    """
433
```
434

435
### Permutations and Sampling
436

437
Functions for shuffling and sampling from arrays.
438

439
```python { .api }
440
def shuffle(x):
441
    """Modify sequence in-place by shuffling contents.
442
    
443
    Parameters:
444
    - x: array-like, sequence to shuffle
445
    """
446

447
def permutation(x):
448
    """Randomly permute sequence or return permuted range.
449
    
450
    Parameters:
451
    - x: int or array-like, sequence to permute or length of range
452
    
453
    Returns:
454
    cupy.ndarray: permuted sequence
455
    """
456

457
def choice(a, size=None, replace=True, p=None):
458
    """Generate random sample from given 1-D array.
459
    
460
    Parameters:
461
    - a: 1-D array-like or int, array to sample from or sample size
462
    - size: int or tuple of ints, output shape
463
    - replace: bool, whether sampling is with replacement
464
    - p: 1-D array-like, probabilities associated with entries in a
465
    
466
    Returns:
467
    cupy.ndarray: generated random samples
468
    """
469
```
470

471
### Host-side Functions
472

473
Random functions that execute on CPU for compatibility.
474

475
```python { .api }
476
def bytes(length):
477
    """Return random bytes (NumPy-based, runs on host).
478
    
479
    Parameters:
480
    - length: int, number of random bytes to generate
481
    
482
    Returns:
483
    bytes: random byte string
484
    """
485
```
486

487
## Usage Examples
488

489
### Basic Random Generation
490

491
```python
492
import cupy as cp
493

494
# Set seed for reproducibility
495
cp.random.seed(42)
496

497
# Generate basic random data
498
random_floats = cp.random.random((1000, 1000))  # Uniform [0,1)
499
random_ints = cp.random.randint(0, 100, size=(500, 500))  # Integers [0,100)
500
normal_data = cp.random.randn(10000)  # Standard normal N(0,1)
501

502
# Check statistics
503
print(f"Mean: {cp.mean(random_floats):.4f}")  # Should be ~0.5
504
print(f"Std: {cp.std(normal_data):.4f}")      # Should be ~1.0
505
```
506

507
### Distribution Sampling
508

509
```python
510
import cupy as cp
511
import matplotlib.pyplot as plt
512

513
# Sample from various distributions
514
normal_samples = cp.random.normal(loc=5.0, scale=2.0, size=10000)
515
exponential_samples = cp.random.exponential(scale=2.0, size=10000)
516
gamma_samples = cp.random.gamma(shape=2.0, scale=1.5, size=10000)
517

518
# Generate synthetic dataset with multiple features
519
n_samples = 5000
520
features = cp.random.multivariate_normal(
521
    mean=[0, 0, 0],
522
    cov=[[1, 0.5, 0.2], [0.5, 1, 0.3], [0.2, 0.3, 1]],
523
    size=n_samples
524
)
525

526
print(f"Feature correlation: {cp.corrcoef(features.T)}")
527
```
528

529
### Random State Management
530

531
```python
532
import cupy as cp
533

534
# Create independent random states
535
rng1 = cp.random.RandomState(seed=123)
536
rng2 = cp.random.RandomState(seed=456)
537

538
# Generate different sequences
539
seq1 = rng1.random(10)
540
seq2 = rng2.random(10)
541

542
# Reset and regenerate - should be identical
543
rng1 = cp.random.RandomState(seed=123)
544
seq1_repeat = rng1.random(10)
545

546
print(f"Sequences identical: {cp.allclose(seq1, seq1_repeat)}")  # True
547

548
# Use modern Generator API for better performance
549
gen = cp.random.default_rng(seed=789)
550
modern_samples = gen.random((1000, 1000))
551
```
552

553
### Monte Carlo Simulation
554

555
```python
556
import cupy as cp
557

558
def estimate_pi_monte_carlo(n_samples):
559
    """Estimate π using Monte Carlo method."""
560
    # Generate random points in unit square
561
    x = cp.random.uniform(-1, 1, n_samples)
562
    y = cp.random.uniform(-1, 1, n_samples)
563
    
564
    # Count points inside unit circle
565
    inside_circle = (x**2 + y**2) <= 1
566
    pi_estimate = 4 * cp.mean(inside_circle)
567
    
568
    return float(pi_estimate)
569

570
# Estimate π with increasing precision  
571
for n in [1000, 10000, 100000, 1000000]:
572
    pi_est = estimate_pi_monte_carlo(n)
573
    error = abs(pi_est - cp.pi)
574
    print(f"n={n:7d}: π ≈ {pi_est:.6f}, error = {error:.6f}")
575
```
576

577
### Advanced Sampling
578

579
```python
580
import cupy as cp
581

582
# Choice sampling with probabilities
583
outcomes = cp.array([1, 2, 3, 4, 5, 6])  # Dice outcomes
584
probabilities = cp.array([0.1, 0.1, 0.1, 0.1, 0.3, 0.3])  # Biased die
585
rolls = cp.random.choice(outcomes, size=10000, p=probabilities)
586

587
# Shuffle operations
588
deck = cp.arange(52)  # Card deck
589
cp.random.shuffle(deck)  # Shuffle in-place
590
random_permutation = cp.random.permutation(52)  # Return new permutation
591

592
# Bootstrap sampling
593
original_data = cp.random.normal(10, 2, 1000)
594
bootstrap_samples = cp.random.choice(
595
    original_data, 
596
    size=(1000, 1000),  # 1000 bootstrap samples of size 1000
597
    replace=True
598
)
599
bootstrap_means = cp.mean(bootstrap_samples, axis=1)
600
confidence_interval = cp.percentile(bootstrap_means, [2.5, 97.5])
601
```