Module volatility 

• volatility - Volatility modeling, forecasting, and analysis utilities.

Comprehensive tools for volatility analysis including historical volatility calculation, implied volatility determination, volatility forecasting models (GARCH, EWMA), and volatility skew/smile analysis.

Volatility Module

This module provides comprehensive volatility calculation and modeling tools for financial applications, including historical, implied, and stochastic volatility models.

Core Features

Volatility Calculation Methods

• Constant Volatility
• Historical Volatility (Moving Window)
• EWMA (Exponentially Weighted Moving Average)
• GARCH(1,1)
• Heston Stochastic Volatility
• Implied Volatility
• Uncertain Volatility Bounds
• Volatility Surface Interpolation

Usage Examples

Basic Volatility Calculations

use rust_decimal_macros::dec;
use positive::Positive;
use optionstratlib::volatility::constant_volatility;

let returns = [dec!(0.02), dec!(0.02), dec!(0.02), dec!(0.02)];
let vol = constant_volatility(&returns);

Implied Volatility Calculation

use rust_decimal_macros::dec;
use optionstratlib::{ExpirationDate, Options};
use optionstratlib::model::types::{ OptionStyle, OptionType, Side};
use optionstratlib::volatility::implied_volatility;
use positive::Positive;
use positive::pos_or_panic;

let mut option = Options::new(
    OptionType::European,
    Side::Long,
    "STOCK".to_string(),
    Positive::HUNDRED,   // Strike price
    ExpirationDate::Days(pos_or_panic!(30.0)),
    pos_or_panic!(0.2),   // Initial volatility guess
    Positive::ONE,   // Quantity
    Positive::HUNDRED,   // Current price
    dec!(0.05),   // Risk-free rate
    OptionStyle::Call,
    Positive::ZERO,   // Dividend yield
    None,   // Exotic parameters
);

let market_price = pos_or_panic!(30.0);
let iv = implied_volatility(market_price, &mut option, 100);

Historical Volatility with Moving Window

use rust_decimal_macros::dec;
use optionstratlib::volatility::historical_volatility;

let returns = [dec!(0.02), dec!(0.02), dec!(-0.02), dec!(0.02)];
let window_size = 3;
let hist_vol = historical_volatility(&returns, window_size);

EWMA Volatility

use rust_decimal_macros::dec;
use optionstratlib::volatility::ewma_volatility;

let returns = vec![dec!(0.01), dec!(-0.02), dec!(0.015), dec!(-0.01)];
let lambda = dec!(0.94); // Standard decay factor for daily data
let ewma_vol = ewma_volatility(&returns, lambda);

Mathematical Models

GARCH(1,1)

The GARCH(1,1) model is implemented as: σ²(t) = ω + α * r²(t-1) + β * σ²(t-1)

use rust_decimal_macros::dec;
use optionstratlib::volatility::garch_volatility;

let returns = vec![dec!(0.01), dec!(-0.02), dec!(0.015)];
let omega = dec!(0.1);  // Long-term variance weight
let alpha = dec!(0.2);  // Recent shock weight
let beta = dec!(0.7);   // Previous variance weight
let garch_vol = garch_volatility(&returns, omega, alpha, beta);

Heston Stochastic Volatility

Implements the Heston model: dv(t) = κ(θ - v(t))dt + ξ√v(t)dW(t)

use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use optionstratlib::assert_decimal_eq;
use optionstratlib::volatility::simulate_heston_volatility;

let kappa = dec!(2.0);      // Mean reversion speed
let theta = dec!(0.04);     // Long-term variance
let xi = dec!(0.3);         // Volatility of volatility
let v0 = dec!(0.04);        // Initial variance
let dt = Decimal::ONE / dec!(252.0);   // Daily time step
let steps = 252;      // Number of steps

let heston_vol = simulate_heston_volatility(kappa, theta, xi, v0, dt, steps);

Time Frame Handling

The module includes utilities for converting between different time frames:

use positive::pos_or_panic;
use optionstratlib::utils::time::TimeFrame;
use optionstratlib::volatility::{annualized_volatility, de_annualized_volatility};

let daily_vol = pos_or_panic!(0.01);
let annual_vol = annualized_volatility(daily_vol, TimeFrame::Day)?;
let daily_vol_again = de_annualized_volatility(annual_vol, TimeFrame::Day);

Performance Considerations

• Implied volatility calculation: O(n) where n is max_iterations
• Historical volatility: O(n*w) where n is returns length and w is window size
• EWMA: O(n) where n is returns length
• GARCH: O(n) where n is returns length
• Heston simulation: O(n) where n is number of steps

Implementation Notes

• All volatility calculations ensure non-negative results
• Implied volatility uses Newton-Raphson method with bounds
• Surface interpolation uses bilinear interpolation
• Time scaling follows the square root of time rule
• Numerical stability is ensured through bounds checking

References

The implementations are based on standard financial mathematics literature:

• Black-Scholes-Merton option pricing model
• RiskMetrics™ Technical Document for EWMA
• Heston (1993) stochastic volatility model
• GARCH by Bollerslev (1986)

Traits

AtmIvProvider

Trait for providing at-the-money implied volatility.

VolatilitySmile

A trait defining a volatility smile representation.

Functions

adjust_volatility

Adjusts volatility between different timeframes using the square root of time rule

annualized_volatility

Annualizes a volatility value from a specific timeframe.

calculate_iv

Calculates the implied volatility (IV) of an option given its parameters.

constant_volatility

Calculates the constant volatility from a series of returns.

de_annualized_volatility

De-annualizes a volatility value to a specific timeframe.

ewma_volatility

Calculates EWMA (Exponentially Weighted Moving Average) volatility.

garch_volatility

Calculates GARCH(1,1) volatility (simplified).

generate_ou_process

Generates a mean-reverting Ornstein-Uhlenbeck process time series

historical_volatility

Calculates historical volatility using a moving window approach.

implied_volatility

Calculates the implied volatility of an option given its market price.

simulate_heston_volatility

Simulates stochastic volatility using the Heston model (simplified).

uncertain_volatility_bounds

Calculates bounds for uncertain volatility.

volatility_for_dt

Adjusts annualized volatility for use in random walk simulations with a specific dt.