Merge pull request #2 from dancixx/feat/documentation

feat: add diffusion process descriptions

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "stochastic-rs"
-version = "0.4.2"
+version = "0.5.0"
 edition = "2021"
 license = "MIT"
 description = "A Rust library for stochastic processes"

src/diffusions/cir.rs

@@ -4,6 +4,33 @@ use crate::{
 };
 use ndarray::Array1;
 
+/// Generates a path of the Cox-Ingersoll-Ross (CIR) process.
+///
+/// The CIR process is commonly used in financial mathematics to model interest rates.
+///
+/// # Parameters
+///
+/// - `theta`: Speed of mean reversion.
+/// - `mu`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+/// - `use_sym`: Whether to use symmetric noise (optional, defaults to false).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated CIR process path.
+///
+/// # Panics
+///
+/// Panics if `2 * theta * mu < sigma^2`.
+///
+/// # Example
+///
+/// ```
+/// let cir_path = cir(0.5, 0.02, 0.1, 1000, Some(0.01), Some(1.0), Some(false));
+/// ```
 pub fn cir(
   theta: f64,
   mu: f64,
@@ -34,6 +61,35 @@ pub fn cir(
   cir.to_vec()
 }
 
+/// Generates a path of the fractional Cox-Ingersoll-Ross (fCIR) process.
+///
+/// The fCIR process incorporates fractional Brownian motion, which introduces long-range dependence.
+///
+/// # Parameters
+///
+/// - `hurst`: Hurst parameter for fractional Brownian motion, must be in (0, 1).
+/// - `theta`: Speed of mean reversion.
+/// - `mu`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+/// - `use_sym`: Whether to use symmetric noise (optional, defaults to false).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated fCIR process path.
+///
+/// # Panics
+///
+/// Panics if `hurst` is not in (0, 1).
+/// Panics if `2 * theta * mu < sigma^2`.
+///
+/// # Example
+///
+/// ```
+/// let fcir_path = fcir(0.75, 0.5, 0.02, 0.1, 1000, Some(0.01), Some(1.0), Some(false));
+/// ```
 #[allow(clippy::too_many_arguments)]
 pub fn fcir(
   hurst: f64,

src/diffusions/gbm.rs

@@ -4,6 +4,27 @@ use crate::{
 };
 use ndarray::Array1;
 
+/// Generates a path of the Geometric Brownian Motion (GBM) process.
+///
+/// The GBM process is commonly used in financial mathematics to model stock prices.
+///
+/// # Parameters
+///
+/// - `mu`: Drift parameter.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 100.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated GBM process path.
+///
+/// # Example
+///
+/// ```
+/// let gbm_path = gbm(0.05, 0.2, 1000, Some(100.0), Some(1.0));
+/// ```
 pub fn gbm(mu: f64, sigma: f64, n: usize, x0: Option<f64>, t: Option<f64>) -> Vec<f64> {
   let gn = gn(n - 1, Some(t.unwrap_or(1.0)));
   let dt = t.unwrap_or(1.0) / n as f64;
@@ -18,6 +39,32 @@ pub fn gbm(mu: f64, sigma: f64, n: usize, x0: Option<f64>, t: Option<f64>) -> Ve
   gbm.to_vec()
 }
 
+/// Generates a path of the fractional Geometric Brownian Motion (fGBM) process.
+///
+/// The fGBM process incorporates fractional Brownian motion, which introduces long-range dependence.
+///
+/// # Parameters
+///
+/// - `hurst`: Hurst parameter for fractional Brownian motion, must be in (0, 1).
+/// - `mu`: Drift parameter.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 100.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated fGBM process path.
+///
+/// # Panics
+///
+/// Panics if `hurst` is not in (0, 1).
+///
+/// # Example
+///
+/// ```
+/// let fgbm_path = fgbm(0.75, 0.05, 0.2, 1000, Some(100.0), Some(1.0));
+/// ```
 pub fn fgbm(
   hurst: f64,
   mu: f64,

src/diffusions/jacobi.rs

@@ -5,6 +5,33 @@ use crate::{
   utils::Generator,
 };
 
+/// Generates a path of the Jacobi process.
+///
+/// The Jacobi process is a mean-reverting process used in various fields such as finance and biology.
+///
+/// # Parameters
+///
+/// - `alpha`: Speed of mean reversion.
+/// - `beta`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated Jacobi process path.
+///
+/// # Panics
+///
+/// Panics if `alpha`, `beta`, or `sigma` are not positive.
+/// Panics if `alpha` is greater than `beta`.
+///
+/// # Example
+///
+/// ```
+/// let jacobi_path = jacobi(0.5, 1.0, 0.2, 1000, Some(0.5), Some(1.0));
+/// ```
 pub fn jacobi(
   alpha: f64,
   beta: f64,
@@ -42,6 +69,35 @@ pub fn jacobi(
   jacobi.to_vec()
 }
 
+/// Generates a path of the fractional Jacobi (fJacobi) process.
+///
+/// The fJacobi process incorporates fractional Brownian motion, which introduces long-range dependence.
+///
+/// # Parameters
+///
+/// - `hurst`: Hurst parameter for fractional Brownian motion, must be in (0, 1).
+/// - `alpha`: Speed of mean reversion.
+/// - `beta`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated fJacobi process path.
+///
+/// # Panics
+///
+/// Panics if `hurst` is not in (0, 1).
+/// Panics if `alpha`, `beta`, or `sigma` are not positive.
+/// Panics if `alpha` is greater than `beta`.
+///
+/// # Example
+///
+/// ```
+/// let fjacobi_path = fjacobi(0.75, 0.5, 1.0, 0.2, 1000, Some(0.5), Some(1.0));
+/// ```
 #[allow(clippy::too_many_arguments)]
 pub fn fjacobi(
   hurst: f64,

src/diffusions/mod.rs

@@ -1,3 +1,33 @@
+//! This module contains the implementations of various diffusion processes.
+//!
+//! The following diffusion processes are implemented:
+//!
+//! - **Cox-Ingersoll-Ross (CIR)**
+//!   - SDE: `dX(t) = theta(mu - X(t))dt + sigma sqrt(X(t))dW(t)`
+//!
+//! - **Fractional Cox-Ingersoll-Ross (fCIR)**
+//!   - SDE: `dX(t) = theta(mu - X(t))dt + sigma sqrt(X(t))dW^H(t)`
+//!
+//! - **Geometric Brownian Motion (GBM)**
+//!   - SDE: `dX(t) = mu X(t)dt + sigma X(t)dW(t)`
+//!
+//! - **Fractional Geometric Brownian Motion (fGBM)**
+//!   - SDE: `dX(t) = mu X(t)dt + sigma X(t)dW^H(t)`
+//!
+//! - **Jacobi Process**
+//!   - SDE: `dX(t) = (alpha - beta X(t))dt + sigma (X(t)(1 - X(t)))^(1/2)dW(t)`
+//!
+//! - **Fractional Jacobi Process**
+//!   - SDE: `dX(t) = (alpha - beta X(t))dt + sigma (X(t)(1 - X(t)))^(1/2)dW^H(t)`
+//!
+//! - **Ornstein-Uhlenbeck (OU)**
+//!   - SDE: `dX(t) = theta(mu - X(t))dt + sigma dW(t)`
+//!
+//! - **Fractional Ornstein-Uhlenbeck (fOU)**
+//!   - SDE: `dX(t) = theta(mu - X(t))dt + sigma dW^H(t)`
+//!
+//! Each process has its own module and functions to generate sample paths.
+
 pub mod cir;
 pub mod gbm;
 pub mod jacobi;

src/diffusions/ou.rs

@@ -4,6 +4,28 @@ use crate::{
 };
 use ndarray::Array1;
 
+/// Generates a path of the Ornstein-Uhlenbeck (OU) process.
+///
+/// The OU process is a mean-reverting stochastic process used in various fields such as finance and physics.
+///
+/// # Parameters
+///
+/// - `mu`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `theta`: Speed of mean reversion.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated OU process path.
+///
+/// # Example
+///
+/// ```
+/// let ou_path = ou(0.0, 0.1, 0.5, 1000, Some(0.0), Some(1.0));
+/// ```
 pub fn ou(mu: f64, sigma: f64, theta: f64, n: usize, x0: Option<f64>, t: Option<f64>) -> Vec<f64> {
   let gn = gn::gn(n - 1, Some(t.unwrap_or(1.0)));
   let dt = t.unwrap_or(1.0) / n as f64;
@@ -18,6 +40,33 @@ pub fn ou(mu: f64, sigma: f64, theta: f64, n: usize, x0: Option<f64>, t: Option<
   ou.to_vec()
 }
 
+/// Generates a path of the fractional Ornstein-Uhlenbeck (fOU) process.
+///
+/// The fOU process incorporates fractional Brownian motion, which introduces long-range dependence.
+///
+/// # Parameters
+///
+/// - `hurst`: Hurst parameter for fractional Brownian motion, must be in (0, 1).
+/// - `mu`: Long-term mean level.
+/// - `sigma`: Volatility parameter.
+/// - `theta`: Speed of mean reversion.
+/// - `n`: Number of time steps.
+/// - `x0`: Initial value of the process (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+///
+/// # Returns
+///
+/// A `Vec<f64>` representing the generated fOU process path.
+///
+/// # Panics
+///
+/// Panics if `hurst` is not in (0, 1).
+///
+/// # Example
+///
+/// ```
+/// let fou_path = fou(0.75, 0.0, 0.1, 0.5, 1000, Some(0.0), Some(1.0));
+/// ```
 #[allow(clippy::too_many_arguments)]
 pub fn fou(
   hurst: f64,

src/jumps/bates.rs

@@ -2,7 +2,39 @@ use ndarray::Array1;
 
 use crate::prelude::{correlated::correlated_bms, poisson::compound_poisson};
 
-/// Bates (1996) model
+/// Generates paths for the Bates (1996) model.
+///
+/// The Bates model combines a stochastic volatility model with jump diffusion, commonly used in financial mathematics to model asset prices.
+///
+/// # Parameters
+///
+/// - `mu`: Drift parameter of the asset price.
+/// - `kappa`: Rate of mean reversion of the volatility.
+/// - `theta`: Long-term mean level of the volatility.
+/// - `eta`: Volatility of the volatility (vol of vol).
+/// - `rho`: Correlation between the asset price and its volatility.
+/// - `lambda`: Jump intensity.
+/// - `n`: Number of time steps.
+/// - `s0`: Initial value of the asset price (optional, defaults to 0.0).
+/// - `v0`: Initial value of the volatility (optional, defaults to 0.0).
+/// - `t`: Total time (optional, defaults to 1.0).
+/// - `use_sym`: Whether to use symmetric noise for the volatility (optional, defaults to false).
+///
+/// # Returns
+///
+/// A `[Vec<f64>; 2]` where the first vector represents the asset price path and the second vector represents the volatility path.
+///
+/// # Example
+///
+/// ```
+/// let paths = bates_1996(0.05, 1.5, 0.04, 0.3, -0.7, 0.1, 1000, Some(100.0), Some(0.04), Some(1.0), Some(false));
+/// let asset_prices = paths[0];
+/// let volatilities = paths[1];
+/// ```
+///
+/// # Panics
+///
+/// This function will panic if the `correlated_bms` or `compound_poisson` functions return invalid lengths or if there are issues with array indexing.
 #[allow(clippy::too_many_arguments)]
 pub fn bates_1996(
   mu: f64,