ringkernel_montecarlo/
lib.rs

1//! GPU-accelerated Monte Carlo primitives for variance reduction.
2//!
3//! This crate provides variance reduction techniques for Monte Carlo simulation
4//! that can be accelerated on GPU via RingKernel.
5//!
6//! # Features
7//!
8//! - **Counter-based PRNGs**: Philox and other stateless generators suitable for GPU
9//! - **Variance Reduction**: Antithetic variates, control variates, importance sampling
10//! - **GPU Compatibility**: All types are designed for zero-copy GPU transfer
11//!
12//! # Example
13//!
14//! ```ignore
15//! use ringkernel_montecarlo::prelude::*;
16//!
17//! // Create a Philox-based RNG
18//! let mut rng = PhiloxRng::new(0, 42);
19//!
20//! // Generate uniform random numbers
21//! let u: f32 = rng.next_uniform();
22//!
23//! // Generate normal variates
24//! let z: f32 = rng.next_normal();
25//!
26//! // Antithetic variates for variance reduction
27//! let (u1, u2) = antithetic_pair(&mut rng);
28//! // u1 and u2 are negatively correlated
29//! ```
30
31#![warn(missing_docs)]
32#![warn(clippy::all)]
33
34pub mod rng;
35pub mod variance;
36
37/// GPU-accelerated implementations (requires `cuda` feature).
38#[cfg(feature = "cuda")]
39pub mod gpu;
40
41/// Error types for Monte Carlo operations.
42#[derive(Debug, thiserror::Error)]
43pub enum MonteCarloError {
44    /// Invalid parameter error.
45    #[error("Invalid parameter: {0}")]
46    InvalidParameter(String),
47    /// Numerical error (e.g., division by zero, overflow).
48    #[error("Numerical error: {0}")]
49    NumericalError(String),
50    /// RNG state error.
51    #[error("RNG error: {0}")]
52    RngError(String),
53}
54
55/// Result type for Monte Carlo operations.
56pub type Result<T> = std::result::Result<T, MonteCarloError>;
57
58/// Prelude for convenient imports.
59pub mod prelude {
60    pub use crate::rng::{GpuRng, PhiloxRng, PhiloxState};
61    pub use crate::variance::{
62        antithetic_pair, control_variate_estimate, importance_sample, AntitheticVariates,
63        ControlVariates, ImportanceSampling,
64    };
65    pub use crate::{MonteCarloError, Result};
66
67    // GPU types (when cuda feature is enabled)
68    #[cfg(feature = "cuda")]
69    pub use crate::gpu::{
70        GpuAntitheticVariates, GpuImportanceSampling, GpuMonteCarloError, GpuPhiloxRng,
71    };
72}
73
74// Re-exports
75pub use rng::{GpuRng, PhiloxRng, PhiloxState};
76pub use variance::{AntitheticVariates, ControlVariates, ImportanceSampling};
ringkernel_montecarlo/lib.rs

ringkernel_montecarlo/
lib.rs
