# DiffusionX
[](https://docs.rs/diffusionx/latest/diffusionx/)
[](https://crates.io/crates/diffusionx)
[](LICENSE-MIT)
## Features
- **High Performance**: Optimized for computational efficiency with multi-threading support via Rayon
- **Comprehensive**: Extensive collection of random distributions and stochastic processes for scientific computing
- **Extensible**: Trait-based architecture enabling easy extension with custom processes and distributions
- **Well-documented**: Detailed API documentation with mathematical background and usage examples
- **Type-safe**: Leverages Rust's type system for compile-time safety and correctness
- **Zero-cost abstractions**: Efficient abstractions with minimal runtime overhead
## Visualization
DiffusionX provides built-in visualization capabilities using the [plotters](https://crates.io/crates/plotters) crate:
- **Process Trajectories**: Easily visualize continuous process trajectories
- **Customizable Plots**: Configure plot appearance including colors, dimensions, and line styles
- **Multiple Backends**: Support for both BitMap and SVG output formats
- **Simple API**: Intuitive trait-based API for visualizing simulation results
## Implemented
### Random Number Generation
- [x] Normal distribution - Gaussian random variables with specified mean and variance
- [x] Uniform distribution - Uniform random variables in specified ranges
- [x] Exponential distribution - Exponential waiting times with specified rate
- [x] Poisson distribution - Discrete count distribution with specified mean
- [x] Alpha-stable distribution - Heavy-tailed distributions with specified stability, skewness, scale, and location
### Stochastic Processes
- [x] Brownian motion - Standard and generalized with drift and diffusion
- [x] Alpha-stable Lévy process - Non-Gaussian processes with heavy tails
- [x] Subordinator - Time-changed processes
- [x] Inverse subordinator - Processes for modeling waiting times
- [x] Poisson process - Counting processes with independent increments
- [x] Fractional Brownian motion - Long-range dependent processes
- [x] Continuous time random walk - Jump processes with random waiting times
- [x] Ornstein-Uhlenbeck process - Mean-reverting processes
- [x] Langevin equation - Physical models with friction and noise
- [x] Generalized Langevin equation - Extended models with memory effects
- [x] Subordinated Langevin equation - Time-changed Langevin processes
- [x] Levy walk - Superdiffusive processes with coupled jump lengths and waiting times
- [x] Birth-death process - Discrete-state processes with birth and death rates
## Installation
Add the following to your `Cargo.toml`:
```toml
[dependencies]
diffusionx = "0.1.9" # Replace with the latest version
```
Or use the following command to install:
```bash
cargo add diffusionx
```
## Usage
### Random Number Generation
```rust
use diffusionx::random::{normal, uniform, exponential, poisson, stable};
// Normal Distribution
let normal_sample = normal::rand(0.0, 1.0)?; // Generate a normal random number with mean 0.0 and std 1.0
let std_normal_samples = normal::standard_rands(1000); // Generate 1000 standard normal random numbers
// Uniform Distribution
let uniform_sample = uniform::range_rand(0..10)?; // Generate a uniform random number in range [0, 10)
let std_uniform_samples = uniform::standard_rands(1000); // Generate 1000 uniform random numbers in range [0, 1)
// Exponential Distribution
let exp_samples = exponential::rands(1.0, 1000)?; // Generate 1000 exponential random numbers with rate 1.0
// Poisson Distribution
let poisson_samples = poisson::rands(5.0, 1000)?; // Generate 1000 Poisson random numbers with mean 5.0
// α-Stable Distribution
// Standard α-stable distribution (σ=1, μ=0)
let stable_samples = stable::standard_rands(1.5, 0.5, 1000)?; // Generate 1000 standard stable random numbers
// Object-oriented interface for stable distributions
let stable = stable::Stable::new(1.5, 0.5, 1.0, 0.0)?; // Create a stable distribution object
let samples = stable.samples(1000)?; // Generate 1000 samples
```
### Stochastic Process Simulation
```rust
use diffusionx::simulation::{prelude::*, Bm};
// Brownian motion simulation
let bm = Bm::default(); // Create standard Brownian motion object
let traj = bm.duration(1.0)?; // Create trajectory with duration 1.0
let (times, positions) = traj.simulate(0.01)?; // Simulate Brownian motion trajectory with time step 0.01
// Monte Carlo simulation of Brownian motion statistics
let mean = traj.raw_moment(1, 1000, 0.01)?; // First-order raw moment with 1000 particles
let msd = traj.central_moment(2, 1000, 0.01)?; // Second-order central moment with 1000 particles
// First passage time of Brownian motion
let fpt = bm.fpt(0.01, (-1.0, 1.0), 1000)?; // Calculate FPT with boundaries at -1.0 and 1.0
```
## Architecture and Extensibility
DiffusionX is designed with a trait-based system for high extensibility and performance:
### Core Traits
- `ContinuousProcess`: Base trait for continuous stochastic processes
- `PointProcess`: Base trait for point processes
- `Moment`: Trait for statistical moments calculation, including raw and central moments
- `FirstPassageTime`: Trait for calculating first passage times of stochastic processes
- `OccupationTime`: Trait for calculating occupation times in specified regions
### Functional Analysis Tools
DiffusionX provides powerful functional analysis tools for stochastic processes:
1. **First Passage Time (FPT)**: Calculate when a process first reaches a specified boundary
```rust
let bm = Bm::default();
let fpt = bm.fpt(0.01, (-1.0, 1.0), 1000)?; ```
2. **Occupation Time**: Measure time spent by a process in a specified region
```rust
let bm = Bm::default();
let traj = bm.duration(10.0)?;
let occupation = traj.occupation_time(0.01, (0.0, 2.0))?; ```
### Extending with Custom Processes
1. Adding a New Continuous Process:
```rust
#[derive(Clone)]
struct MyProcess {
}
impl ContinuousProcess for MyProcess {
fn simulate(&self, duration: impl Into<f64>, time_step: f64) -> XResult<(Vec<f64>, Vec<f64>)> {
todo!()
}
}
```
2. Automatic Feature Acquisition:
- Implementing `ContinuousProcess` trait automatically provides `ContinuousTrajectoryTrait` functionality
- `ContinuousTrajectory` provides access to the `Moment` trait functionality
- Built-in support for moment statistics calculation
Example:
```rust
let myprocess = MyProcess::default();
let traj = myprocess.duration(10)?;
let mean = traj.raw_moment(1, 1000, 0.01)?; // Calculate mean with 1000 particles
```
3. Parallel Computing Support:
- Automatic parallel computation for moment calculations using Rayon
- Default parallel strategy for statistical calculations
- Configurable parallelism for optimal performance
4. Visualization Support:
- Easy trajectory visualization with minimal code
- Highly customizable plot configuration
Example:
```rust
// Visualize a Brownian motion trajectory
use diffusionx::visualize::PlotConfigBuilder;
let bm = Bm::default().duration(10)?;
let config = PlotConfigBuilder::default()
.title("Brownian Motion")
.output_path("brownian_motion.png")
.build()?;
bm.plot(&config)?; // Generates a plot with the specified configuration
```
## Benchmark
### Test Results
Generating random array of length `10_000_000`
| DiffusionX | 17.576 ms | 15.131 ms | 133.85 ms |
| Julia | 27.671 ms | 12.755 ms | 570.260 ms |
| NumPy / SciPy | 199 ms | 66.6 ms | 1.67 s |
| Numba | - | - | 1.15 s |
### Test Environment
#### Hardware Configuration
- Device Model: MacBook Air 13-inch (2024)
- Processor: Apple M3
- Memory: 16GB
#### Software Environment
- Operating System: macOS Sequoia 15.3
- Rust: 1.85.0
- Python: 3.12
- Julia: 1.11
- NumPy: 2
- SciPy: 1.15.1
## License
This project is dual-licensed under:
* [MIT License](https://opensource.org/licenses/MIT)
* [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
You can choose to use either license.