optionstratlib 0.17.3

OptionStratLib is a comprehensive Rust library for options trading and strategy development across multiple asset classes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

/******************************************************************************
use positive::pos_or_panic;
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 11/8/24
******************************************************************************/

//! # Greeks Module
//!
//! This module provides functionality for calculating option Greeks and related metrics
//! used in options trading and risk management.
//!
//! ## Core Components
//!
//! * `equations` - Implementation of Greek calculations (delta, gamma, theta, vega, rho, vanna,
//! vomma, veta)
//! * `utils` - Utility functions for Greek calculations and related math
//!
//! ## Greeks Provided
//!
//! The module calculates the following Greeks:
//!
//! * Delta (Δ) - Measures the rate of change in option value with respect to the underlying price
//! * Gamma (Γ) - Measures the rate of change in delta with respect to the underlying price
//! * Theta (Θ) - Measures the rate of change in option value with respect to time
//! * Vega  (V) - Measures the rate of change in option value with respect to volatility
//! * Rho   (ρ) - Measures the rate of change in option value with respect to the risk-free rate
//! * Rho_d     - Measures sensitivity to dividend yield changes
//! * Vanna     - Measures the rate of change in delta with respect to volatility
//! * Vomma     - Measures the rate of change in vega with respect to volatility
//! * Veta      - Measures the rate of change in vega with respect to time
//! * Charm     - Measures the rate of change in delta with respect to time
//! * Color     - Measures the rate of change in gamma with respect to time
//!
//! ## Utilities Included
//!
//! The utilities module provides essential mathematical functions for Greek calculations:
//!
//! * d1/d2 calculations for Black-Scholes model
//! * Normal distribution functions (PDF, CDF)
//! * Mathematical helper functions
//!
//! ## Example Usage
//!
//! ```rust
//! use rust_decimal_macros::dec;
//! use optionstratlib::greeks::{
//!     delta, gamma, rho, theta, vanna, vega, veta, vomma, charm, color
//! };
//! use optionstratlib::{ExpirationDate, Options};
//! use optionstratlib::model::types::{ OptionStyle, OptionType, Side};
//! use positive::pos_or_panic;
//! use positive::Positive;
//!
//! // Create a sample option
//! 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,
//!             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,
//!         };
//!
//! // Calculate Greeks
//! let delta_value = delta(&option);
//! let gamma_value = gamma(&option);
//! let theta_value = theta(&option);
//! let vega_value = vega(&option);
//! let rho_value = rho(&option);
//! let vanna_value = vanna(&option);
//! let vomma = vomma(&option);
//! let veta_value = veta(&option);
//! let charm_value = charm(&option);
//! let color_value = color(&option);
//! ```
//!
//! ## Mathematical Background
//!
//! The Greeks are calculated using the Black-Scholes model and its derivatives.
//! Each Greek represents a different dimension of risk:
//!
//! * Delta: First-order price sensitivity
//! * Gamma: Second-order price sensitivity
//! * Theta: Time decay
//! * Vega: Volatility sensitivity
//! * Rho: Interest rate sensitivity
//! * Vanna: Second-order volatility sensitivity
//! * Vomma: Second-order volatility sensitivity
//! * Veta: Second-order time sensitivity
//! * Charm: Second-order time sensitivity
//! * Color: Third-order time sensitivity
//!
//! ## Additional Features
//!
//! * Support for both European and American options
//! * Handling of zero volatility cases
//! * Adjustments for dividends
//! * Special case handling for extreme values
//!
//! ## Second-Order Volatility Greeks
//!
//! The module provides specialized second-order Greeks for volatility analysis:
//!
//! ### Vanna (∂Δ/∂σ)
//! Measures the sensitivity of delta to changes in implied volatility. Useful for:
//! - Anticipating changes to delta-hedge effectiveness as volatility changes
//! - Understanding how delta exposure shifts in volatile markets
//!
//! ### Vomma (Volga) (∂²V/∂σ²)
//! Measures the second-order sensitivity of option price to volatility (rate of change
//! of vega with respect to volatility). Key characteristics:
//! - Options far out-of-the-money have the highest Vomma
//! - Long options benefit from positive Vomma in rising volatility environments
//! - Useful for volatility trading strategies
//!
//! ### Veta (∂Vega/∂t)
//! Measures the rate of change of vega with respect to time. Important for:
//! - Understanding how volatility sensitivity decays over time
//! - Managing time-dependent volatility exposure
//!
//! ### Charm (Delta Decay) (∂Δ/∂t)
//! Measures the rate of change of delta with respect to the passage of time. Key aspects:
//! - Predicts how delta exposure evolves daily even if the underlying price remains unchanged
//! - Particularly important for delta-hedged positions over weekends or holidays
//! - Helps anticipate rehedging needs as time decay affects option moneyness
//!
//! ## Third-Order Volatility Greeks
//!
//! The module provides specialized third-order Greeks for volatility analysis:
//!
//! ### Color (Gamma Decay) (∂Γ/∂t)
//! Measures the rate of change of gamma with respect to time (third-order Greek). Useful for:
//! - Understanding how gamma exposure (and thus convexity) decays over time
//! - Managing gamma-hedged portfolios where hedge effectiveness changes with time passage
//! - Anticipating adjustments in dynamic hedging strategies near expiration
//!
//! ## Curve and Surface Representations
//!
//! These Greeks can be visualized using curves and surfaces:
//!
//! | Metric | Curve (by strike) | Surface (price vs. volatility) | Surface (price vs. time) |
//! |--------|-------------------|-------------------------------|-------------------------|
//! | Vanna  | ✓ `vanna_curve()` | ✓ `vanna_surface()`          | -                       |
//! | Vomma  | -                 | ✓ `vomma_surface()`          | -                       |
//! | Veta   | ✓ `veta_curve()`  | -                             | ✓ `veta_time_surface()` |
//! | Charm  | ✓ `charm_curve()` | -                             | ✓ `charm_time_surface()` |
//! | Color  | ✓ `color_curve()` | -                             | ✓ `color_time_surface()` |
//!
//! ### Example: Generating Volatility Surfaces
//!
//! ```ignore
//! use optionstratlib::chains::chain::OptionChain;
//! use positive::pos_or_panic;
//!
//! // Create an option chain with options at various strikes
//! let chain = OptionChain::new("SPY", pos_or_panic!(450.0), "2024-03-15".to_string(), None, None);
//!
//! // Generate Vanna surface across different volatility levels
//! let volatilities = vec![pos_or_panic!(0.1), pos_or_panic!(0.2), pos_or_panic!(0.3), pos_or_panic!(0.4), pos_or_panic!(0.5)];
//! let vanna_surface = chain.vanna_surface(volatilities)?;
//!
//! // Generate Vomma surface
//! let volatilities = vec![pos_or_panic!(0.15), pos_or_panic!(0.20), pos_or_panic!(0.25), pos_or_panic!(0.30)];
//! let vomma_surface = chain.vomma_surface(volatilities)?;
//!
//! // Generate Veta time surface across different time horizons
//! let days = vec![pos_or_panic!(7.0), pos_or_panic!(14.0), pos_or_panic!(30.0), pos_or_panic!(60.0), pos_or_panic!(90.0)];
//! let veta_surface = chain.veta_time_surface(days)?;
//!
//! // Generate Charm time surface across different time horizons
//! let days = vec![pos_or_panic!(7.0), pos_or_panic!(14.0), pos_or_panic!(30.0), pos_or_panic!(60.0), pos_or_panic!(90.0)];
//! let charm_surface = chain.charm_time_surface(days)?;
//!
//! // Generate Color time surface across different time horizons
//! let days = vec![pos_or_panic!(7.0), pos_or_panic!(14.0), pos_or_panic!(30.0), pos_or_panic!(60.0), pos_or_panic!(90.0)];
//! let color_surface = chain.color_time_surface(days)?;
//! ```

mod black_76;
mod equations;
mod garman_kohlhagen;
pub mod numerical;
mod utils;

pub use black_76::{Black76Greeks, delta_b76, gamma_b76, rho_b76, theta_b76, vega_b76};
pub use equations::{
    Greek, Greeks, GreeksSnapshot, charm, color, delta, gamma, rho, rho_d, theta, vanna, vega,
    veta, vomma,
};
pub use garman_kohlhagen::{
    GarmanKohlhagenGreeks, delta_gk, gamma_gk, rho_domestic_gk, rho_foreign_gk, theta_gk, vega_gk,
};
pub(crate) use utils::calculate_d_values;
pub use utils::calculate_delta_neutral_sizes;
pub use utils::{big_n, calculate_d_values_black_76, d1, d2, n};