diffusionx 0.1.7

# DiffusionX

> Development is in progress. DiffusionX is a multi-threaded high-performance Rust library for random number generation and stochastic process simulation.

## Features

- **High Performance**: Optimized for speed with multi-threading support
- **Comprehensive**: Wide range of random distributions and stochastic processes
- **Extensible**: Trait-based design for easy extension
- **Well-documented**: Clear examples and API documentation
- **Type-safe**: Leverages Rust's type system for safety and correctness

## Installation

Add the following to your `Cargo.toml`:
```toml
[dependencies]
diffusionx = "*"
```

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 normal_samples = normal::rands(2.0, 3.0, 1000)?; // Generate 1000 normal random numbers with mean 2.0 and std 3.0
let std_normal_sample = normal::standard_rand(); // Generate a standard normal random number (mean 0, std 1)
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 uniform_samples = uniform::range_rands(0..10, 1000)?; // Generate 1000 uniform random numbers in range [0, 10)
let uniform_incl_sample = uniform::inclusive_range_rand(0..=10)?; // Generate a uniform random number in range [0, 10]
let uniform_incl_samples = uniform::inclusive_range_rands(0..=10, 1000)?; // Generate 1000 uniform random numbers in range [0, 10]
let std_uniform_sample = uniform::standard_rand(); // Generate a uniform random number in range [0, 1)
let std_uniform_samples = uniform::standard_rands(1000); // Generate 1000 uniform random numbers in range [0, 1)
let bool_sample = uniform::bool_rand(0.7)?; // Generate a boolean with probability 0.7
let bool_samples = uniform::bool_rands(0.7, 1000)?; // Generate 1000 booleans with probability 0.7

// Exponential Distribution
let exp_sample = exponential::rand(1.0)?; // Generate an exponential random number with rate 1.0
let exp_samples = exponential::rands(1.0, 1000)?; // Generate 1000 exponential random numbers with rate 1.0

// Poisson Distribution
let poisson_sample = poisson::rand(5.0)?; // Generate a Poisson random number with mean 5.0
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_sample = stable::standard_rand(1.5, 0.5)?; // Generate a standard stable random number with α=1.5, β=0.5
let stable_samples = stable::standard_rands(1.5, 0.5, 1000)?; // Generate 1000 standard stable random numbers

// General α-stable distribution
let stable_sample = stable::rand(1.5, 0.5, 1.0, 0.0)?; // Generate a stable random number with α=1.5, β=0.5, σ=1.0, μ=0.0
let stable_samples = stable::rands(1.5, 0.5, 1.0, 0.0, 1000)?; // Generate 1000 stable random numbers

// Special cases of α-stable distribution
let skew_sample = stable::skew_rand(1.5)?; // Generate a totally skewed stable random number with α=1.5
let skew_samples = stable::skew_rands(1.5, 1000)?; // Generate 1000 totally skewed stable random numbers
let sym_sample = stable::sym_standard_rand(1.5)?; // Generate a symmetric stable random number with α=1.5
let sym_samples = stable::sym_standard_rands(1.5, 1000)?; // Generate 1000 symmetric 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

let std_stable = stable::StandardStable::new(1.5, 0.5)?; // Create a standard stable distribution object
let samples = std_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 max_duration = 1000; // if over this duration, the simulation will be terminated and return None
let fpt = bm.fpt(0.01, (-1.0, 1.0), max_duration)?; 
// or
let fpt = FirstPassageTime::new(&bm, (-1.0, 1.0))?;
let fpt_result = fpt.simulate(max_duration, 0.01)?;
```

## Architecture and Extensibility

DiffusionX is designed with a trait-based system for high extensibility:

### 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

### Extending with Custom Processes

1. Adding a New Continuous Process:
   ```rust
   #[derive(Clone)]
   struct MyProcess {
       // Your parameters
       // Should be `Send + Sync`
   }
   
   impl ContinuousProcess for MyProcess {
       fn simulate(&self, duration: impl Into<f64>, time_step: f64) -> XResult<(Vec<f64>, Vec<f64>)> {
           // Implement your simulation logic
           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 (times, positions) = traj.simulate(0.01)?;
let mean = traj.raw_moment(1, 1000, 0.01)?;
let msd = traj.central_moment(2, 1000, 0.01)?;
```

3. Parallel Computing Support:
   - Automatic parallel computation for moment calculations
   - Default parallel strategy for statistical calculations

## Implemented Features

### Random Number Generation

- [x] Normal distribution
- [x] Uniform distribution
- [x] Exponential distribution
- [x] Poisson distribution
- [x] Alpha-stable distribution

### Stochastic Processes

- [x] Brownian motion
- [x] Alpha-stable Lévy process
- [x] Subordinator
- [x] Inverse subordinator
- [x] Poisson process
- [x] Fractional Brownian motion
- [x] Continuous time random walk
- [ ] Compound Poisson process
- [x] Langevin equation
- [x] Generalized Langevin equation
- [x] Subordinated Langevin equation
- [x] Fractional Brownian motion
- [x] Levy walk

## Benchmark

### Test Results

Generating random array of length `10_000_000`

|               | Standard Normal | Uniform [0, 1] |   Stable   |
| :-----------: | :-------------: | :------------: | :--------: |
|  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.