Skip to main content

Module random

numrs2

Module random 

Source
Expand description

Random Number Generation

This module provides a NumPy-like interface for generating random numbers from various probability distributions. It features both a modern, object-oriented approach and a legacy functional approach for backward compatibility.

§Quick Start

use numrs2::random::{default_rng, pcg64_seed_rng};

// Create a Generator with the default bit generator
let rng = default_rng();

// Generate uniform random numbers between 0 and 1
let uniform_array = rng.random::<f64>(&[3, 3]).expect("random should succeed");

// Generate random numbers from a normal distribution
let normal_array = rng.normal(0.0, 1.0, &[5]).expect("normal should succeed");

// Create a seeded generator for reproducible results
let seeded_rng = pcg64_seed_rng(42);
let random_array = seeded_rng.random::<f64>(&[3]).expect("seeded random should succeed");

§Module Structure

  • generator.rs: Modern Generator class and BitGenerator implementations
  • state.rs: RandomState class for legacy interface
  • distributions.rs: Common probability distributions
  • advanced_distributions.rs: Specialized distributions not in standard libraries

§Available Interfaces

Uses the Generator class with BitGenerator implementations. This is similar to NumPy’s Generator class introduced in NumPy 1.17.

use numrs2::random::default_rng;

// Create a Generator with the default bit generator
let rng = default_rng();

// Generate random numbers
let arr = rng.random::<f64>(&[3, 3]).expect("random should succeed");

§2. Legacy Interface

Uses the RandomState class and global functions. This is provided for backward compatibility with earlier NumPy versions.

use numrs2::random::{RandomState, normal, set_seed};

// Create a RandomState with a specific seed
let rng = RandomState::with_seed(42);

// Generate random numbers with the instance
let arr = rng.random::<f64>(&[3, 3]).expect("random should succeed");

// Or use global functions
set_seed(42);
let normal_array = normal(0.0, 1.0, &[5]).expect("normal should succeed");

§Bit Generators

The module provides two bit generator implementations:

  • StdBitGenerator: Based on the rand crate’s StdRng, which uses ChaCha algorithm
  • PCG64BitGenerator: Based on the PCG64 algorithm, providing high-quality randomness

§Advanced Usage

See the examples directory for comprehensive usage demonstrations:

  • random_distributions_example.rs: Shows all distribution functions
  • random_simple_test.rs: A simplified example for quick verification

Re-exports§

pub use advanced_distributions::maxwell;
pub use advanced_distributions::noncentral_chisquare;
pub use advanced_distributions::noncentral_f;
pub use advanced_distributions::vonmises;
pub use advanced_distributions::wald;
pub use generator::default_rng;
pub use generator::BitGenerator;
pub use generator::Generator;
pub use generator::PCG64BitGenerator;
pub use generator::StdBitGenerator;
pub use generator::pcg64_rng;
pub use generator::pcg64_seed_rng;
pub use state::RandomState;
pub use distributions_enhanced::copula;
pub use distributions_enhanced::latin_hypercube;
pub use distributions_enhanced::mixture_of_normals;
pub use distributions_enhanced::multivariate_normal_cholesky;
pub use distributions_enhanced::power;
pub use distributions_enhanced::random_correlation_matrix;
pub use distributions_enhanced::sobol_sequence;
pub use distributions_enhanced::truncated_normal;
pub use legacy::choice;
pub use legacy::rand;
pub use legacy::randn;
pub use legacy::seed;
pub use legacy::shuffle;
pub use legacy::uniform;
pub use legacy::Generator as LegacyGenerator;
pub use distributions::*;

Modules§

advanced_distributions
Advanced Random Distributions
distributions
Advanced random distributions
distributions_enhanced
Enhanced random distributions
generator
Generator for modern random number generation
legacy
Legacy random number generation interface
random_base
Legacy backward compatibility module (re-exports from random_base.rs)
state
Random state for compatibility with different random number generator states
state_distributions
Advanced and specialized distribution methods for RandomState

Functions§

seed_rng
Create a new RandomState with the given seed.