Struct Rng 

pub struct Rng { /* private fields */ }

The xoshiro256** generator (256 bits of state).

Implementations

impl Rng

pub fn new(seed: u64) -> Rng

A generator seeded from one u64 through SplitMix64.

pub fn state(&self) -> [u64; 4]

The 256 bits of the state, to save a generator and resume it with Rng::from_state (the pickling of the Python generator).

pub fn from_state(s: [u64; 4]) -> Result<Rng>

The generator of a state saved by Rng::state: it continues the draws of the saved generator.

Errors

crate::Error::Config for the all-zero state, a fixed point of xoshiro256** that no seed gives.

pub fn next_u64(&mut self) -> u64

Next 64 random bits.

pub fn uniform(&mut self) -> f64

Uniform on [0, 1) with 53 random bits.

pub fn below(&mut self, n: usize) -> usize

Uniform integer in 0..n (n ≥ 1).

Panics

In debug builds, for n = 0 (an empty range has no element: release builds return 0 rather than check it in the inner loops).

pub fn phase(&mut self) -> f64

A phase uniform on $[-\pi, \pi)$: $2\pi U - \pi$, $U$ of Rng::uniform (one draw; the initial phases of the fading generators).

Examples

use comnum_core::rng::Rng;
let mut r = Rng::new(1);
assert!((0..1000).map(|_| r.phase()).all(|p| (-std::f64::consts::PI..std::f64::consts::PI).contains(&p)));

pub fn bit(&mut self) -> u8

One fair random bit.

pub fn gaussian(&mut self) -> f64

Standard Gaussian N(0, 1).

pub fn complex_gaussian(&mut self) -> C64

Circular complex Gaussian with E|z|² = 1 (each component of variance ½).

pub fn gamma(&mut self, shape: f64) -> f64

A gamma variable of shape shape and unit scale (mean shape), by the method of Marsaglia & Tsang (2000): for a shape below 1, the draw of shape shape + 1 times $U^{1/\text{shape}}$. A non-positive or non-finite shape returns NaN.

Examples

use comnum_core::rng::Rng;
let mut r = Rng::new(1);
let n = 100_000;
let mean = (0..n).map(|_| r.gamma(2.5)).sum::<f64>() / n as f64;
assert!((mean - 2.5).abs() < 0.03);

pub fn shuffle<T>(&mut self, v: &mut [T])

A uniform random permutation of v in place (Fisher–Yates, Durstenfeld’s version): for $i = n - 1, \dots, 1$, swap $v_{i}$ and $v_{j}$ with $j$ uniform in $\{0, \dots, i\}$ (Rng::below), $n - 1$ draws in all.

Examples

use comnum_core::rng::Rng;
let mut v: Vec<usize> = (0..10).collect();
Rng::new(3).shuffle(&mut v);
let mut sorted = v.clone();
sorted.sort_unstable();
assert_eq!(sorted, (0..10).collect::<Vec<_>>());

pub fn complex_noise(&mut self, n: usize, noise_var: f64) -> Vec<C64>

n circular complex Gaussian samples of variance noise_var (E|z|² = σ²).

Trait Implementations

impl Clone for Rng

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rng

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.