tensorlogic_oxicuda_rng/
lib.rs

1//! # tensorlogic-oxicuda-rng
2//!
3//! GPU-accelerated random number generation for TensorLogic, with a pure-Rust
4//! CPU fallback.
5//!
6//! ## Features
7//!
8//! | Feature | Description |
9//! |---------|-------------|
10//! | `cpu` (default) | PCG-XSH-RR generator with Box-Muller transform, zero external dependencies |
11//! | `gpu`           | `oxicuda-rand` GPU backend (requires an NVIDIA GPU + CUDA driver at runtime) |
12//!
13//! ## Quick start
14//!
15//! ```rust
16//! use tensorlogic_oxicuda_rng::{RngEngine, RngEngineKind};
17//!
18//! let mut rng = RngEngine::new(RngEngineKind::Philox, 42).unwrap();
19//!
20//! // f32 variants
21//! let mut out = vec![0f32; 1024];
22//! rng.uniform_f32(&mut out).unwrap();
23//!
24//! let mut normal_out = vec![0f32; 1024];
25//! rng.normal_f32(&mut normal_out, 0.0, 1.0).unwrap();
26//!
27//! // f64 variants (52-bit mantissa precision)
28//! let mut out64 = vec![0f64; 1024];
29//! rng.uniform_f64(&mut out64).unwrap();
30//!
31//! let mut normal_out64 = vec![0f64; 1024];
32//! rng.normal_f64(&mut normal_out64, 0.0, 1.0).unwrap();
33//!
34//! // Streaming API — large buffers without single allocation
35//! rng.fill_uniform_chunked(1_000_000, 4096, &mut |chunk: &[f32]| {
36//!     let _ = chunk; // process chunk
37//! }).unwrap();
38//!
39//! let mut bernoulli_out = vec![0u8; 1024];
40//! rng.bernoulli(&mut bernoulli_out, 0.3).unwrap();
41//! ```
42//!
43//! ## Thread safety
44//!
45//! On the **CPU path** (`default`), [`RngEngine`] is `Send + Sync`.
46//! On the **GPU path** (`feature = "gpu"`), [`RngEngine`] is `Send` but not `Sync`.
47//!
48//! ## Policy notes
49//!
50//! * No `rand`, `rand_distr`, or `ndarray` imports — the PCG generator and
51//!   Box-Muller transform are implemented from scratch in [`engine`].
52//! * `scirs2-core` is listed as an optional dependency under the `cpu` feature
53//!   to satisfy workspace policy; the actual random primitives live in
54//!   `engine::CpuRngState` for zero-dependency builds.
55
56#![deny(missing_docs)]
57#![forbid(unsafe_op_in_unsafe_fn)]
58
59pub mod engine;
60pub mod error;
61
62pub use engine::{RngEngine, RngEngineKind};
63pub use error::RngError;
tensorlogic_oxicuda_rng/lib.rs

tensorlogic_oxicuda_rng/
lib.rs
