optionstratlib-pricing 0.22.1

//! # Options Pricing Module
//!
//! This module provides implementations for various financial models and utilities
//! to calculate and simulate option pricing. The module includes support for several
//! well-known mathematical models such as the Binomial Tree Model, Black-Scholes Model,
//! Monte Carlo Simulations, and Telegraph Process.
//!
//! ## Core Models
//!
//! ### Binomial Model (`binomial_model`)
//! Contains the implementation of the Binomial Tree Model for option pricing. This model
//! supports both European and American style options and allows for customization of steps
//! and parameters like volatility, interest rates, and time increments.
//!
//! ### Black-Scholes Model (`black_scholes_model`)
//! Implements the Black-Scholes option pricing model, a widely used formula for pricing
//! European-style options. This module provides tools to calculate option prices and
//! associated Greek values.
//!
//! ### Black-76 Model (`black_76`)
//! Implements the Black (1976) closed-form for European options whose underlying is a
//! futures or forward price `F` rather than a spot price `S`. Standard model for:
//! - Options on commodity futures (e.g. oil, gold, agricultural)
//! - Options on equity index / interest rate futures
//! - Swaptions, caps and floors
//!
//! Structurally similar to Black–Scholes but the drift in `d1`/`d2` collapses to
//! `σ²/2` because the forward price already incorporates carry, and both legs share
//! a single discount factor `e^(-rT)`.
//!
//! ### Garman–Kohlhagen Model (`garman_kohlhagen`)
//! Implements the Garman–Kohlhagen (1983) closed-form for European FX options on a
//! spot exchange rate `S` quoted as domestic per unit of foreign. Uses two interest
//! rates: domestic `r_d` and foreign `r_f`. Structurally identical to
//! Black–Scholes–Merton with `q = r_f`, so the implementation delegates to the BSM
//! kernel after type validation. Field mapping in `Options`:
//! - `risk_free_rate`  -> `r_d` (domestic)
//! - `exotic_params.foreign_rate` -> `r_f` (foreign, signed, may be negative);
//!   when unset, `dividend_yield` -> `r_f` (non-negative)
//! - `underlying_price` -> `S` (spot FX)
//!
//! ### Monte Carlo Simulations (`monte_carlo`)
//! Provides Monte Carlo simulation capabilities for option pricing. This module
//! supports simulation of stock price paths and uses statistical methods to estimate
//! option values under various stochastic processes.
//!
//! ### Telegraph Process (`telegraph`)
//! Implements the Telegraph process, a two-state stochastic process for modeling price movements.
//! Key features include:
//! - State transitions between +1 and -1 based on transition rates
//! - Parameter estimation from historical data
//! - Support for asymmetric transition rates
//! - Applications in regime-switching scenarios
//! - Monte-Carlo pricing under regime-switching volatility: the discounted
//!   payoff averaged over a caller-chosen number of log-Euler paths whose
//!   volatility is `sigma_plus` in the +1 regime and `sigma_minus` in the -1
//!   regime, each step carrying its regime's risk-neutral drift
//!
//! The Telegraph Process is particularly useful for:
//! - Modeling regime changes in volatility
//! - Capturing market sentiment switches
//! - Simulating discrete state transitions
//!
//! ## Supporting Modules
//!
//! ### Profit Contracts (`payoff`)
//! The [`Profit`](crate::pricing::Profit) trait: the profit of a contract or position at a given
//! underlying price. The payoff contracts at expiry (`Payoff`, `PayoffInfo`)
//! are core's: `optionstratlib_core::model::payoff`.
//!
//! ### Utility Functions (`utils`)
//! Provides essential mathematical and financial utilities:
//! - Probability calculations
//! - Discount factor computations
//! - Statistical functions
//! - Parameter estimation tools
//!
//! ### Constants (`constants`)
//! Defines model parameters and limits used across the pricing implementations:
//! - Numerical bounds
//! - Default values
//! - Calculation constraints
//!
//! ## Usage Examples
//!
//! ### Using the Telegraph Process
//!
//! ```rust
//! use rust_decimal_macros::dec;
//! use optionstratlib_pricing::pricing::telegraph::{RegimeVolatility, TelegraphProcess, telegraph};
//! use optionstratlib_core::model::{ExpirationDate, Options};
//! use optionstratlib_core::model::types::{ OptionStyle, OptionType, Side};
//! use optionstratlib_core::model::Positive;
//! use optionstratlib_core::pos_or_panic;
//! use optionstratlib_core::utils::deterministic_rng;
//!
//! // Every draw comes from the caller's generator: a seeded one makes the
//! // result reproducible, `&mut rand::rng()` draws from the thread RNG.
//! let mut rng = deterministic_rng(42);
//!
//! // Create a Telegraph Process with transition rates
//! let process = TelegraphProcess::new(dec!(0.5), dec!(0.3), &mut rng);
//!
//! // Price an option whose volatility switches between 30% and 10%
//! let regimes = RegimeVolatility::new(pos_or_panic!(0.3), pos_or_panic!(0.1)).unwrap();
//! let option = Options {
//!             option_type: OptionType::European,
//!             side: Side::Long,
//!             underlying_symbol: "AAPL".to_string(),
//!             strike_price: Positive::HUNDRED,
//!             expiration_date: ExpirationDate::Days(pos_or_panic!(30.0)),
//!             implied_volatility: pos_or_panic!(0.2),
//!             quantity: Positive::ONE,
//!             contract_size: Positive::ONE,
//!             underlying_price: pos_or_panic!(105.0),
//!             risk_free_rate: dec!(0.05),
//!             option_style: OptionStyle::Call,
//!             dividend_yield: pos_or_panic!(0.01),
//!             exotic_params: None,
//!         };
//! let price = telegraph(
//!     &option,
//!     optionstratlib_core::nz!(1000),
//!     optionstratlib_core::nz!(1000),
//!     Some(dec!(0.5)),
//!     Some(dec!(0.3)),
//!     regimes,
//!     &mut rng,
//! );
//! ```
//!
//! ### Combined Model Analysis
//!
//! ```rust
//! use rust_decimal_macros::dec;
//! use optionstratlib_core::model::{ExpirationDate, Options};
//! use optionstratlib_core::model::types::{ OptionStyle, OptionType, Side};
//! use optionstratlib_core::model::Positive;
//! use optionstratlib_core::pos_or_panic;
//! use optionstratlib_pricing::pricing::{
//!     black_scholes_model::black_scholes,
//!     monte_carlo::monte_carlo_option_pricing,
//!     telegraph::{RegimeVolatility, telegraph}
//! };
//! use optionstratlib_core::utils::deterministic_rng;
//! let option = Options {
//!             option_type: OptionType::European,
//!             side: Side::Long,
//!             underlying_symbol: "AAPL".to_string(),
//!             strike_price: Positive::HUNDRED,
//!             expiration_date: ExpirationDate::Days(pos_or_panic!(30.0)),
//!             implied_volatility: pos_or_panic!(0.2),
//!             quantity: Positive::ONE,
//!             contract_size: Positive::ONE,
//!             underlying_price: pos_or_panic!(105.0),
//!             risk_free_rate: dec!(0.05),
//!             option_style: OptionStyle::Call,
//!             dividend_yield: pos_or_panic!(0.01),
//!             exotic_params: None,
//!         };
//! // Compare prices across different models
//! let bs_price = black_scholes(&option);
//! let mut rng = deterministic_rng(42);
//! let mc_price = monte_carlo_option_pricing(
//!     &option,
//!     optionstratlib_core::nz!(2),
//!     optionstratlib_core::nz!(2),
//!     &mut rng,
//! );
//! let regimes = RegimeVolatility::constant(option.implied_volatility).unwrap();
//! let tp_price = telegraph(
//!     &option,
//!     optionstratlib_core::nz!(1000),
//!     optionstratlib_core::nz!(1000),
//!     Some(dec!(0.5)),
//!     Some(dec!(0.3)),
//!     regimes,
//!     &mut rng,
//! );
//! ```
//!
//! ## Implementation Notes
//!
//! - All models support standard market conventions for option pricing
//! - Parameter validation and bounds checking are implemented
//! - Error handling follows Rust's Result pattern
//! - Performance optimizations are included for numerical calculations
//!
//! ## Model Selection Guidelines
//!
//! Choose the appropriate model based on your needs:
//! - Black-Scholes:    Quick pricing of European options on a spot underlying
//! - Black-76:         European options on futures/forwards, swaptions, caps/floors
//! - Garman-Kohlhagen: European FX options with domestic/foreign rates
//! - Binomial:         American options and early exercise
//! - Monte Carlo:      Complex path-dependent options
//! - Telegraph:        Regime-switching and discrete state transitions
//!
//! ## Performance Considerations
//!
//! - Telegraph Process: O(n) complexity where n is the number of steps
//! - Monte Carlo: O(m*n) where m is the number of simulations
//! - Binomial: O(n²) where n is the number of steps
//! - Black-Scholes: O(1) constant time calculation
//! - Black-76: O(1) constant time calculation
//! - Garman-Kohlhagen: O(1) constant time calculation
//!
//! For high-frequency calculations, consider using the Black-Scholes model
//! when applicable, as it provides the fastest computation times.

/// American option pricing using analytical approximations.
///
/// This module provides fast analytical methods for pricing American options,
/// including the Barone-Adesi-Whaley (BAW) approximation which offers O(1)
/// complexity compared to O(n²) for binomial tree methods.
///
/// American options can be exercised at any time before expiration, making them
/// more valuable than European options but also more complex to price.
pub mod american;

/// Binomial Tree model for option pricing.
pub mod binomial_model;

/// Barrier option pricing using analytical extensions.
pub mod barrier;

/// Asian option pricing with geometric and arithmetic averaging.
pub mod asian;

/// Binary option pricing (cash-or-nothing, asset-or-nothing, gap).
pub mod binary;

/// Lookback option pricing (floating and fixed strike).
pub mod lookback;

/// Compound option pricing (options on options).
pub mod compound;

/// Chooser option pricing (choice between call and put).
pub mod chooser;

/// Cliquet option pricing (periodic strike resets).
pub mod cliquet;

/// Rainbow option pricing (multi-asset options).
pub mod rainbow;

/// Spread option pricing (price differential options).
pub mod spread;

/// Quanto option pricing (currency-protected options).
pub mod quanto;

/// Exchange option pricing (Margrabe options).
pub mod exchange;

/// Power option pricing (non-linear payoffs).
pub mod power;

/// Black-Scholes model for option pricing and analysis.
///
/// This module implements the Black-Scholes-Merton model for European option pricing
/// and related calculations such as the Greeks (delta, gamma, theta, vega, rho).
///
/// The Black-Scholes model provides closed-form solutions for European option prices
/// under specific assumptions about market behavior and asset price dynamics.
pub mod black_scholes_model;

/// Black-76 (Black 1976) model for pricing options on futures and forwards.
///
/// This module implements the Black-76 closed-form model, the standard for pricing:
/// - Options on futures
/// - Options on forward contracts
/// - Swaptions
/// - Caps and floors
/// - Options on commodity futures
///
/// The Black-76 model is structurally similar to Black-Scholes but uses the forward/futures
/// price F as input instead of spot S, and has no carry term because F already incorporates carry.
pub mod black_76;

/// Garman–Kohlhagen (1983) model for pricing European FX options.
///
/// This module implements the Garman–Kohlhagen closed-form model, the standard for pricing:
/// - European options on FX spot rates
/// - Currency options with two interest rates (domestic and foreign)
///
/// Garman–Kohlhagen is structurally identical to Black–Scholes–Merton with `q = r_f`. It
/// reuses the existing `Options` schema with the FX field interpretation
/// `risk_free_rate = r_d`, `dividend_yield = r_f`, `underlying_price = S`. The
/// implementation delegates to `black_scholes` after validating the option type, which
/// guarantees a bit-exact equivalence to the BSM kernel.
pub mod garman_kohlhagen;

/// Solver and lattice defaults of the pricing models: binomial steps,
/// Monte-Carlo paths and steps, and the Newton iteration cap.
pub mod constants;

/// Monte Carlo simulation methods for financial modeling.
///
/// This module provides tools for pricing options and other derivatives using
/// Monte Carlo simulations, which generate random paths for underlying asset prices
/// to estimate expected payoffs.
///
/// Monte Carlo methods are particularly valuable for complex derivatives where
/// closed-form solutions don't exist.
pub mod monte_carlo;

/// Pricing capability of the core `Options` contract.
///
/// Defines the [`OptionPricing`] extension trait that carries the
/// model-based valuations of an `Options` contract (binomial, Black-Scholes,
/// Monte Carlo, telegraph, time value, implied volatility). `Options` has no
/// pricing methods of its own; import this trait to price one.
pub mod option_pricing;

/// The implied-volatility solver behind every implied-volatility entry
/// point (#859 P4).
pub(crate) mod iv_solver;

/// Profit contracts: [`Profit`](crate::pricing::Profit), the profit of a contract or position at a
/// given underlying price. The payoff contracts at expiry are core's
/// (`optionstratlib_core::model::payoff`).
pub(crate) mod payoff;

/// Telegraph process model for asset price movement.
///
/// Implements a telegraph process model which can be used as an alternative to
/// geometric Brownian motion for modeling asset price movements with specific
/// jump characteristics.
///
/// The telegraph model is particularly useful for capturing market regimes with
/// distinct volatility states.
pub mod telegraph;

/// Utility functions for financial calculations.
///
/// Provides helper functions and common utilities used across the library,
/// including numerical methods, date handling, and data transformation tools.
pub(crate) mod utils;

/// Unified pricing system for options.
///
/// This module provides a single, consistent API for pricing options using different models.
/// `GenericPricingEngine<M>` selects the method, `price_option_with` is the
/// entry point and `Priceable` is its trait form. The engine is generic over
/// its Monte Carlo pricer (`MonteCarloPricer`, with `NoMonteCarlo` for none),
/// so a caller that only needs the closed forms carries no simulator and
/// pricing does not depend on simulation: use the `ClosedFormEngine` alias
/// for that case, and `GenericPricingEngine::MonteCarlo { simulator }` with
/// any `MonteCarloPricer`, such as `simulation::Simulator`.
///
/// ## Features
/// - Black-Scholes closed-form pricing
/// - Monte Carlo simulation with various stochastic models
/// - Unified error handling via `PricingError`
/// - Extensible design for adding new pricing models
///
/// ## Example
/// ```rust
/// use optionstratlib_pricing::pricing::{ClosedFormEngine, Priceable};
/// use optionstratlib_core::model::{Options, ExpirationDate};
/// use optionstratlib_core::{model::Positive, pos_or_panic};
/// use optionstratlib_core::model::types::{OptionStyle, OptionType, Side};
/// use rust_decimal_macros::dec;
/// let option = Options {
///     option_type: OptionType::European,
///     side: Side::Long,
///     underlying_symbol: "AAPL".to_string(),
///     strike_price: Positive::HUNDRED,
///     expiration_date: ExpirationDate::Days(pos_or_panic!(30.0)),
///     implied_volatility: pos_or_panic!(0.2),
///     quantity: Positive::ONE,
///     contract_size: Positive::ONE,
///     underlying_price: pos_or_panic!(105.0),
///     risk_free_rate: dec!(0.05),
///     option_style: OptionStyle::Call,
///     dividend_yield: pos_or_panic!(0.01),
///     exotic_params: None,
/// };
///
/// let engine = ClosedFormEngine::ClosedFormBS;
/// let price = option.price(&engine)?;
/// # Ok::<(), optionstratlib_pricing::error::PricingError>(())
/// ```
pub mod unified;

pub use american::barone_adesi_whaley;
pub use asian::asian_black_scholes;
pub use barrier::barrier_black_scholes;
pub use binary::binary_black_scholes;
pub use binomial_model::{BinomialPricingParams, generate_binomial_tree, price_binomial};
pub use black_76::{Black76, black_76};
pub use black_scholes_model::{BlackScholes, black_scholes};
pub use chooser::chooser_black_scholes;
pub use cliquet::cliquet_black_scholes;
pub use compound::compound_black_scholes;
pub use exchange::exchange_black_scholes;
pub use garman_kohlhagen::{GarmanKohlhagen, garman_kohlhagen};
pub use lookback::lookback_black_scholes;
pub use monte_carlo::monte_carlo_option_pricing;
pub use option_pricing::OptionPricing;
pub use payoff::Profit;
pub use power::power_black_scholes;
pub use quanto::quanto_black_scholes;
pub use rainbow::rainbow_black_scholes;
pub use spread::spread_black_scholes;
pub use telegraph::{RegimeVolatility, TELEGRAPH_PATHS, TelegraphProcess, telegraph};
pub use unified::{
    ClosedFormEngine, GenericPricingEngine, MonteCarloPricer, NoMonteCarlo, Priceable,
    price_option_with,
};
pub use utils::{probability_keep_under_strike, simulate_returns};