ferray_random/lib.rs
1// ferray-random: NumPy-compatible random number generation for Rust
2//
3//! # ferray-random
4//!
5//! Implements `NumPy`'s modern `Generator`/`BitGenerator` model with pluggable
6//! pseudo-random number generators, 30+ continuous and discrete distributions,
7//! permutation/sampling operations, and deterministic parallel generation.
8//!
9//! ## Quick Start
10//!
11//! ```
12//! use ferray_random::{default_rng_seeded, Generator};
13//!
14//! let mut rng = default_rng_seeded(42);
15//!
16//! // Uniform [0, 1)
17//! let values = rng.random(100).unwrap();
18//!
19//! // Standard normal
20//! let normals = rng.standard_normal(100).unwrap();
21//!
22//! // Integers in [0, 10)
23//! let ints = rng.integers(0, 10, 100).unwrap();
24//! ```
25//!
26//! ## `BitGenerators`
27//!
28//! Three `BitGenerators` are provided:
29//! - [`Xoshiro256StarStar`](bitgen::Xoshiro256StarStar) — default, fast, supports jump-ahead
30//! - [`Pcg64`](bitgen::Pcg64) — PCG family, good statistical properties
31//! - [`Philox`](bitgen::Philox) — counter-based, supports stream IDs for parallel generation
32//!
33//! ## Determinism
34//!
35//! All generation is deterministic given the same seed and shape. Parallel
36//! generation via [`standard_normal_parallel`](Generator::standard_normal_parallel)
37//! produces output identical to sequential generation with the same seed.
38
39// RNG kernels lift `u64`/`usize` bit streams into `f32`/`f64` samples and
40// truncate `f64` results back into integer bins (Bernoulli/binomial,
41// Poisson tail, choice). Reproducibility tests assert exact float
42// equality against fixed seeded outputs. These int<->float crossings and
43// exact comparisons are the core of every distribution.
44#![allow(
45 clippy::cast_possible_truncation,
46 clippy::cast_possible_wrap,
47 clippy::cast_precision_loss,
48 clippy::cast_sign_loss,
49 clippy::cast_lossless,
50 clippy::float_cmp,
51 clippy::missing_errors_doc,
52 clippy::missing_panics_doc,
53 clippy::many_single_char_names,
54 clippy::similar_names,
55 clippy::items_after_statements,
56 clippy::option_if_let_else,
57 clippy::too_long_first_doc_paragraph,
58 clippy::needless_pass_by_value,
59 clippy::match_same_arms,
60 clippy::suboptimal_flops,
61 clippy::while_float
62)]
63
64pub mod bitgen;
65pub mod distributions;
66pub mod generator;
67pub mod parallel;
68pub mod permutations;
69pub mod shape;
70
71pub use bitgen::{
72 BitGenerator, MT19937, Pcg64, Pcg64Dxsm, Philox, SeedSequence, Sfc64, Xoshiro256StarStar,
73};
74pub use generator::{Generator, default_rng, default_rng_seeded};
75pub use shape::IntoShape;