EDS 217 Cheatsheet

NumPy Generator-based Random Number Generation Cheatsheet

For information on the previous np.random API and its use cases, please refer to the NumPy documentation on legacy random generation: NumPy Legacy Random Generation

This cheatsheet focuses on the modern Generator-based approach to random number generation in NumPy.

Importing NumPy

Code

import numpy as np

Creating a Generator

Code

# Create a Generator with the default BitGenerator
rng = np.random.default_rng()

# Create a Generator with a specific seed
rng_seeded = np.random.default_rng(seed=42)

Basic Random Number Generation

Uniform Distribution (0 to 1)

Code

# Single random float
print(rng.random())

# Array of random floats
print(rng.random(5))

0.7427454615476556
[0.28657665 0.13592003 0.15248858 0.51122135 0.63067255]

Integers

Code

# Single random integer from 0 to 10 (inclusive)
print(rng.integers(11))

# Array of random integers from 1 to 100 (inclusive)
print(rng.integers(1, 101, size=5))

9
[11 69 90 28 33]

Normal (Gaussian) Distribution

Code

# Single value from standard normal distribution
print(rng.standard_normal())

# Array from normal distribution with mean=0, std=1
print(rng.normal(loc=0, scale=1, size=5))

0.4065258315622663
[ 0.66897889 -2.37220424  0.48820054 -1.23680926  0.66654761]

Sampling

Code

# Random choice from an array
arr = np.array([1, 2, 3, 4, 5])
print(rng.choice(arr))

# Random sample without replacement
print(rng.choice(arr, size=3, replace=False))

2
[3 5 2]

Shuffling

Code

arr = np.arange(10)
rng.shuffle(arr)
print(arr)

[1 4 9 7 0 6 8 3 5 2]

Other Distributions

Generators provide methods for many other distributions:

Code

# Poisson distribution
print(rng.poisson(lam=5, size=3))

# Exponential distribution
print(rng.exponential(scale=1.0, size=3))

# Binomial distribution
print(rng.binomial(n=10, p=0.5, size=3))

[5 7 5]
[1.56966533 1.822129   1.11704804]
[7 6 3]

Generating on Existing Arrays

Generators can fill existing arrays, which can be more efficient:

Code

arr = np.empty(5)
rng.random(out=arr)
print(arr)

[0.92370283 0.64791244 0.11436306 0.02661616 0.07770542]

Bit Generators

You can use different Bit Generators with varying statistical qualities:

Code

from numpy.random import PCG64, MT19937

rng_pcg = np.random.Generator(PCG64())
rng_mt = np.random.Generator(MT19937())

print("PCG64:", rng_pcg.random())
print("MT19937:", rng_mt.random())

PCG64: 0.8308951521858111
MT19937: 0.5119522991104684

Saving and Restoring State

Code

# Save state
state = rng.bit_generator.state

# Generate some numbers
print("Original:", rng.random(3))

# Restore state and regenerate
rng.bit_generator.state = state
print("Restored:", rng.random(3))

Original: [0.81235135 0.4789965  0.46888424]
Restored: [0.81235135 0.4789965  0.46888424]

Spawning New Generators

You can create independent generators from an existing one:

Code

child1, child2 = rng.spawn(2)
print("Child 1:", child1.random())
print("Child 2:", child2.random())

Child 1: 0.15044240799598052
Child 2: 0.7822084327162355

Thread Safety and Jumping

Generators are designed to be thread-safe and support “jumping” ahead in the sequence:

Code

rng = np.random.Generator(PCG64())
rng.bit_generator.advance(1000)  # Jump ahead 1000 steps

<numpy.random._pcg64.PCG64 at 0x10f6b4040>

Best Practices

Use default_rng() to create a Generator unless you have specific requirements for a different Bit Generator.
Set a seed for reproducibility in scientific computations and testing.
Use the spawn() method to create independent generators for parallel processing.
When performance is critical, consider using the out parameter to fill existing arrays.
For very long periods or when security is important, consider using the PCG64DXSM Bit Generator.

Remember, Generators provide a more robust, flexible, and future-proof approach to random number generation in NumPy. They offer better statistical properties and are designed to work well in both single-threaded and multi-threaded environments.