pub trait RandomSampleFromF64: Sized + Clone {
// Required method
fn sample_from<D, R>(dist: &D, rng: &mut R) -> Self
where D: Distribution<f64>,
R: Rng + ?Sized;
// Provided method
fn sample_iter_from<D, R>(
dist: &D,
rng: &mut R,
n: usize,
) -> impl Iterator<Item = Self>
where D: Distribution<f64>,
R: Rng + ?Sized { ... }
}Expand description
A trait for types that can be randomly generated from a distribution over f64.
This trait provides a universal dispatch mechanism for generating random scalar values,
allowing a single generic API to work for primitive types like f64 and
Complex<f64>, as well as custom validated types like RealValidated and
ComplexValidated.
§Purpose
The primary goal of RandomSampleFromF64 is to abstract the process of creating a random
scalar. Many random number distributions in the rand crate are defined to produce
primitive types like f64. This trait acts as a bridge, allowing those same
distributions to be used to generate more complex or validated types.
§How It Works
The trait defines a single required method, RandomSampleFromF64::sample_from(), which takes a reference
to any distribution that implements rand::distr::Distribution<f64> and a
random number generator (RNG). Each implementing type provides its own logic for
this method:
- For
f64, it simply samples directly from the distribution. - For
Complex<f64>, it samples twice to create the real and imaginary parts. - For
RealValidated<K>, it samples anf64and then passes it through the validation and conversion logic ofRealValidated::try_from_f64. - For
ComplexValidated<K>, it reuses the logic forRealValidated<K>to sample the real and imaginary components.
§Example
Here is how you can write a generic function that creates a vector of random numbers
for any type that implements RandomSampleFromF64.
use num_valid::{RealNative64StrictFinite, RealScalar, new_random_vec};
use rand::{distr::Uniform, rngs::StdRng, Rng, SeedableRng};
use try_create::IntoInner;
let seed = [42; 32]; // Example seed for reproducibility
let mut rng = StdRng::from_seed(seed);
let uniform = Uniform::new(-10.0, 10.0).unwrap();
// Create a vector of random f64 values.
let f64_vec: Vec<f64> = new_random_vec(3, &uniform, &mut rng);
assert_eq!(f64_vec.len(), 3);
// Create a vector of random validated real numbers using the same function.
// Reset RNG to get same sequence
let mut rng = StdRng::from_seed(seed);
let validated_vec: Vec<RealNative64StrictFinite> = new_random_vec(3, &uniform, &mut rng);
assert_eq!(validated_vec.len(), 3);
// The underlying numerical values should be identical because the RNG was seeded the same.
assert_eq!(&f64_vec[0], validated_vec[0].as_ref());
assert_eq!(&f64_vec[1], validated_vec[1].as_ref());
assert_eq!(&f64_vec[2], validated_vec[2].as_ref());Required Methods§
Sourcefn sample_from<D, R>(dist: &D, rng: &mut R) -> Self
fn sample_from<D, R>(dist: &D, rng: &mut R) -> Self
Samples a single value of Self using the given f64 distribution.
Provided Methods§
Sourcefn sample_iter_from<D, R>(
dist: &D,
rng: &mut R,
n: usize,
) -> impl Iterator<Item = Self>
fn sample_iter_from<D, R>( dist: &D, rng: &mut R, n: usize, ) -> impl Iterator<Item = Self>
Creates an iterator that samples n values from the given distribution.
This is a convenience method that generates multiple random samples at once. It returns an iterator that lazily samples from the distribution.
§Arguments
dist- The probability distribution to sample from.rng- The random number generator to use.n- The number of samples to generate.
§Returns
An iterator that yields n samples of type Self.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.