# Tsotchke Quantum Random Number Generator (QRNG)
[Tsotchke Quantum RNG](https://github.com/tsotchke/quantum_rng)
A high-quality quantum random number generator library for Rust applications requiring cryptographically secure randomness. This library provides quantum-enhanced random number generation with specialized modules for cryptography, finance, games, and statistical analysis based on Tsotchke QRNG.
## 🚀 Quick Start
Add this to your `Cargo.toml`:
```toml
[dependencies]
rust_qrng = "0.1"
```
### Basic Usage
```rust
use rust_qrng::quantum_rng;
fn main() {
// Create a new quantum RNG instance
let mut rng = quantum_rng::new();
// Generate random numbers
let random_u64 = rng.generate_u64();
let random_f64 = rng.generate_f64();
println!("Random u64: {}", random_u64);
println!("Random f64: {}", random_f64);
}
```
## 🔧 Features
- **🔒 Cryptographic Security**: High-entropy random number generation suitable for cryptographic applications
- **💰 Financial Modeling**: Monte Carlo simulations and options pricing with quantum randomness
- **🎲 Gaming**: Quantum dice and fair random number generation for games
- **📊 Statistical Analysis**: Built-in statistical tests and validation functions
- **⚡ Performance**: Optimized for both quality and speed
## 📚 Usage Examples
### Cryptography
```rust
use rust_qrng::crypto::{key_exchange, key_derivation};
// Generate cryptographic keys
let key_pair = key_exchange::generate_keypair();
let derived_key = key_derivation::derive_key(&key_pair.private, b"salt");
```
### Finance
```rust
use rust_qrng::finance::monte_carlo;
// Run Monte Carlo simulation
let simulation = monte_carlo::SimulationBuilder::new()
.iterations(10000)
.initial_value(100.0)
.volatility(0.2)
.build();
let results = simulation.run();
println!("Expected value: {}", results.mean());
```
### Games
```rust
use rust_qrng::games::quantum_dice;
// Roll quantum dice
let dice = quantum_dice::QuantumDice::new(6); // 6-sided die
let roll = dice.roll();
println!("Rolled: {}", roll);
```
### Statistical Testing
```rust
use rust_qrng::statistical::tests;
// Test randomness quality
let mut rng = rust_qrng::quantum_rng::new();
println!("Chi-square test p-value: {}", chi_square_result.p_value);
```
## 🎯 Use Cases
### For Cryptographic Applications
- **Key Generation**: Generate secure cryptographic keys for encryption
- **Salt Generation**: Create unpredictable salts for password hashing
- **Nonce Generation**: Generate unique numbers for cryptographic protocols
- **Session Tokens**: Create secure session identifiers
### For Financial Modeling
- **Monte Carlo Simulations**: Risk assessment and portfolio optimization
- **Options Pricing**: Calculate fair values for financial derivatives
- **Market Risk Models**: Stress testing and scenario analysis
- **Portfolio Backtesting**: Historical performance simulation
### For Gaming
- **Fair Dice Rolling**: Provably fair random number generation
- **Card Shuffling**: Secure deck randomization
- **Lottery Systems**: Transparent and verifiable random selection
- **Procedural Generation**: Random world/level generation
### For Scientific Computing
- **Statistical Sampling**: Generate samples from various distributions
- **Hypothesis Testing**: Statistical significance testing
- **Randomized Algorithms**: Algorithm performance optimization
- **Simulation Studies**: Scientific modeling and analysis
## 🔍 API Reference
### Core Module
```rust
use rust_qrng::quantum_rng;
// Create a new quantum RNG instance
let mut rng = quantum_rng::new();
// Generate different types of random numbers
let u64_value = rng.generate_u64(); // 64-bit unsigned integer
let f64_value = rng.generate_f64(); // 64-bit floating point (0.0 to 1.0)
let bool_value = rng.generate_bool(); // Boolean value
let range_value = rng.generate_range(1, 100); // Integer in range [1, 100)
```
### Cryptography Module
```rust
use rust_qrng::crypto::{key_exchange, key_derivation};
// Generate RSA key pair
let keypair = key_exchange::generate_keypair();
// Derive key from master key
let derived_key = key_derivation::derive_key(
&keypair.private,
b"application_salt",
);
```
### Finance Module
```rust
use rust_qrng::finance::{monte_carlo, options_pricing};
// Monte Carlo simulation
let simulation = monte_carlo::SimulationBuilder::new()
.iterations(100_000)
.initial_value(100.0)
.volatility(0.25)
.drift(0.05)
.time_horizon(1.0)
.build();
let results = simulation.run();
println!("Mean: {:.2}", results.mean());
println!("Std Dev: {:.2}", results.std_dev());
println!("VaR (95%): {:.2}", results.var_95());
// Options pricing
let option_price = options_pricing::black_scholes(
100.0, // Spot price
110.0, // Strike price
0.25, // Time to expiration (years)
0.05, // Risk-free rate
0.2, // Volatility
);
```
### Games Module
```rust
use rust_qrng::games::quantum_dice;
// Create quantum dice
let d6 = quantum_dice::QuantumDice::new(6);
let d20 = quantum_dice::QuantumDice::new(20);
// Roll dice
let roll = d6.roll();
println!("D6 roll: {}", roll);
// Multiple rolls
let rolls = d20.roll_multiple(5);
println!("D20 rolls: {:?}", rolls);
```
### Statistical Module
```rust
use rust_qrng::statistical::tests;
// Generate test data
let mut rng = rust_qrng::quantum_rng::new();
let samples: Vec<f64> = (0..10000)
.map(|_| rng.generate_f64())
.collect();
// Perform statistical tests
let chi_square = tests::chi_square_test(&samples);
let kolmogorov_smirnov = tests::ks_test(&samples);
let runs_test = tests::runs_test(&samples);
println!("Chi-square p-value: {:.4}", chi_square.p_value);
println!("K-S p-value: {:.4}", kolmogorov_smirnov.p_value);
println!("Runs test p-value: {:.4}", runs_test.p_value);
```
## 🛡️ Security Considerations
- **Cryptographic Quality**: The quantum RNG provides cryptographically secure random numbers suitable for security-sensitive applications
- **Entropy Source**: Uses multiple entropy sources to ensure high-quality randomness
- **Regular Testing**: Built-in statistical tests verify the quality of generated random numbers
- **Side-Channel Resistance**: Designed to resist timing and other side-channel attacks
## 📊 Performance
The library is optimized for both quality and performance:
- **Generation Speed**: ~100M random numbers per second on modern hardware
- **Memory Efficiency**: Minimal memory footprint with efficient buffering
- **Thread Safety**: Safe for concurrent use across multiple threads
- **Zero Allocation**: Core operations avoid heap allocations
## 🧪 Testing
Run the test suite to verify functionality:
```bash
# Run all tests
cargo test
# Run specific test module
cargo test statistical
# Run with output
cargo test -- --nocapture
```
Run benchmarks to measure performance:
```bash
cargo bench
```
## 📖 Examples
Complete examples are available in the `examples/` directory:
```bash
# Basic usage
cargo run --example quantum_rng_demo
# Cryptographic key generation
cargo run --example key_exchange_demo
# Monte Carlo simulation
cargo run --example monte_carlo_demo
# Quantum dice game
cargo run --example quantum_dice_demo
# Quantum blockchain
cargo run --example quantum_chain_demo
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue for any suggestions or improvements.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [Documentation](https://docs.rs/rust_qrng)
- [Repository](https://github.com/ingen0s/quantum_rng_rust_lib)
- [Crates.io](https://crates.io/crates/rust_qrng)