feat(greeks): Garman-Kohlhagen FX Greeks (delta/gamma/vega/theta/rho_d/rho_f) (#403)

* feat(greeks): add Garman-Kohlhagen FX Greeks for #401

Closed-form Greeks (delta, gamma, vega, theta, ρ_d, ρ_f) for the
Garman–Kohlhagen (1983) FX option pricing model. Closes #401.

Garman–Kohlhagen prices European options on a foreign-exchange spot rate
`S` quoted as domestic per unit of foreign, with the foreign currency
earning interest at rate `r_f`. Structurally GK ≡ BSM with the continuous
dividend yield `q = r_f`, and FX options carry two rate sensitivities
(domestic and foreign) instead of one.

Public surface (`src/greeks/garman_kohlhagen.rs`):
- `delta_gk`, `gamma_gk`, `vega_gk`, `theta_gk`,
  `rho_domestic_gk`, `rho_foreign_gk`
- `GarmanKohlhagenGreeks` trait mirroring the `GarmanKohlhagen` pricing
  trait — implementors provide `get_option(&self)` and inherit default
  delegations to the free functions above.

FX field mapping: `risk_free_rate → r_d`, `dividend_yield → r_f`,
`underlying_price → S`. Greek units mirror the BSM module: vega per 1 %
vol, theta per calendar day (annual ÷ 365), domestic and foreign rho per
1 % rate. Quantity scales linearly; `Side::Short` flips the delta sign
only (consistent with `greeks::delta`).

The implementation uses the carry-adjusted form of `d1`/`d2` directly
(`b = r_d − r_f`) rather than delegating to the existing BSM Greeks. The
existing BSM Greeks compute `d1` from `risk_free_rate` only and then
multiply by `e^(-qT)` — a mismatch that produces incorrect deltas and
thetas when `dividend_yield ≠ 0`. The pricing kernels are unaffected
(they go through `calculate_d_values`, which does include `−q` in the
drift). Fixing the BSM Greeks is tracked separately; for GK we needed
correct FX numbers, hence the standalone implementation.

Tests (18, all passing):
- Delta range: `Δ_call ∈ (0, e^(-r_f·T))`, `Δ_put ∈ (-e^(-r_f·T), 0)`
- Spot delta-parity: `Δ_call − Δ_put = e^(-r_f·T)` to 1e-9
- `Γ > 0`, `ν > 0` for both call and put across moneyness
- `Γ_call = Γ_put`, `ν_call = ν_put` (Black-Scholes invariant)
- Rho signs: long call → +ρ_d, -ρ_f; long put → -ρ_d, +ρ_f
- BSM equivalence at `q = 0` (the only case where buggy BSM agrees)
- Theta vs numerical price-difference (5e-3 tolerance, 1-day bump)
- FX call-delta reference (S=0.98, K=1.00, r_d=5 %, r_f=4 %, T=4/12,
  σ=10 %): Δ ≈ 0.3909 to 1e-3
- Zero volatility on every Greek → error
- American / Bermuda / exotic → `GreeksError::Pricing(UnsupportedOptionType)`
- Trait `GarmanKohlhagenGreeks` round-trips against the free functions
- `Side::Short` negates delta
- Quantity scales linearly

Example: `examples/examples_pricing/src/bin/garman_kohlhagen_greeks.rs`
walks ATM / ITM / OTM calls and puts on a 6-month EUR/USD scenario,
demonstrates the spot delta-parity identity (zero residual) and trait
usage on a wrapper type.

* Simplify Monte Carlo simulator data structure for improved rendering performance.

* address review: handle T=0 + use checked d_add in theta

- Added time_to_expiry helper that mirrors BSM Greeks: Greeks at
  expiration return discrete values (delta = ±1/0 by intrinsic state,
  gamma/vega/theta/ρ_d/ρ_f = 0) instead of erroring out from d1/d2.
- Replaced raw `+` in theta_gk with checked d_add to keep arithmetic
  consistent with the rest of the crate (tracked in src/model/decimal.rs).
- New tests cover T=0 across all six Greeks, including ITM/OTM and short
  side. 23 GK Greek tests pass.

Addresses Copilot review on PR #403.

Author: joaquinbejar

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "optionstratlib"
-version = "0.17.2"
+version = "0.17.3"
 edition = "2024"
 authors = ["Joaquin Bejar <jb@taunais.com>"]
 description = "OptionStratLib is a comprehensive Rust library for options trading and strategy development across multiple asset classes."

Draws/Simulation/simulator_test_montecarlo.html

@@ -23,3 +23,7 @@ path = "src/bin/black_76_greeks.rs"
 [[bin]]
 name = "garman_kohlhagen"
 path = "src/bin/garman_kohlhagen.rs"
+
+[[bin]]
+name = "garman_kohlhagen_greeks"
+path = "src/bin/garman_kohlhagen_greeks.rs"

examples/examples_pricing/Cargo.toml

@@ -0,0 +1,118 @@
+/******************************************************************************
+   Author: Joaquín Béjar García
+   Email: jb@taunais.com
+   Date: 2026-04-27
+******************************************************************************/
+
+//! Garman–Kohlhagen Greeks example — EUR/USD scenario.
+//!
+//! Computes spot delta, gamma, vega, theta, domestic rho, and foreign rho
+//! for ATM, ITM, and OTM calls and puts on a 6-month EUR/USD option, then
+//! demonstrates spot delta-parity (`Δ_call − Δ_put = e^(-r_f·T)`) and the
+//! `GarmanKohlhagenGreeks` trait.
+
+use optionstratlib::error::greeks::GreeksError;
+use optionstratlib::greeks::{
+    GarmanKohlhagenGreeks, delta_gk, gamma_gk, rho_domestic_gk, rho_foreign_gk, theta_gk, vega_gk,
+};
+use optionstratlib::model::types::{OptionStyle, OptionType, Side};
+use optionstratlib::pricing::garman_kohlhagen;
+use optionstratlib::{ExpirationDate, Options};
+use positive::{Positive, pos_or_panic};
+use rust_decimal::MathematicalOps;
+use rust_decimal_macros::dec;
+use tracing::info;
+
+fn build_option(s: f64, k: f64, style: OptionStyle) -> Options {
+    Options::new(
+        OptionType::European,
+        Side::Long,
+        "EURUSD".to_string(),
+        pos_or_panic!(k),
+        ExpirationDate::Days(pos_or_panic!(180.0)),
+        pos_or_panic!(0.10),
+        Positive::ONE,
+        pos_or_panic!(s),
+        dec!(0.045),
+        style,
+        pos_or_panic!(0.025),
+        None,
+    )
+}
+
+fn print_greeks(label: &str, opt: &Options) -> Result<(), Box<dyn std::error::Error>> {
+    let price = garman_kohlhagen(opt)?;
+    let delta = delta_gk(opt)?;
+    let gamma = gamma_gk(opt)?;
+    let vega = vega_gk(opt)?;
+    let theta = theta_gk(opt)?;
+    let rho_d = rho_domestic_gk(opt)?;
+    let rho_f = rho_foreign_gk(opt)?;
+    info!(
+        "{label:<6} S={s:>6} K={k:>6} | price={price:>9.6} Δ={delta:>9.6} Γ={gamma:>9.4} ν={vega:>9.6} Θ={theta:>10.6} ρd={rho_d:>9.6} ρf={rho_f:>9.6}",
+        label = label,
+        s = opt.underlying_price.to_dec(),
+        k = opt.strike_price.to_dec(),
+        price = price,
+        delta = delta,
+        gamma = gamma,
+        vega = vega,
+        theta = theta,
+        rho_d = rho_d,
+        rho_f = rho_f,
+    );
+    Ok(())
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter("info")
+        .without_time()
+        .init();
+
+    info!("=== Garman–Kohlhagen Greeks (6-month EUR/USD, σ=10%, r_d=4.5%, r_f=2.5%) ===");
+    info!("");
+    info!("Calls");
+    print_greeks("OTM", &build_option(1.05, 1.10, OptionStyle::Call))?;
+    print_greeks("ATM", &build_option(1.10, 1.10, OptionStyle::Call))?;
+    print_greeks("ITM", &build_option(1.15, 1.10, OptionStyle::Call))?;
+    info!("");
+    info!("Puts");
+    print_greeks("ITM", &build_option(1.05, 1.10, OptionStyle::Put))?;
+    print_greeks("ATM", &build_option(1.10, 1.10, OptionStyle::Put))?;
+    print_greeks("OTM", &build_option(1.15, 1.10, OptionStyle::Put))?;
+
+    // ---- Spot delta-parity --------------------------------------------
+    let call = build_option(1.10, 1.10, OptionStyle::Call);
+    let put = build_option(1.10, 1.10, OptionStyle::Put);
+    let dc = delta_gk(&call)?;
+    let dp = delta_gk(&put)?;
+    let years = call.expiration_date.get_years()?.to_dec();
+    let df_rf = (-call.dividend_yield.to_dec() * years).exp();
+    let diff = dc - dp;
+    info!("");
+    info!(
+        "Spot delta-parity: Δ_call − Δ_put = {diff:.10}, e^(-r_f·T) = {df:.10}, |err| = {err:.2e}",
+        diff = diff,
+        df = df_rf,
+        err = (diff - df_rf).abs(),
+    );
+
+    // ---- Trait usage --------------------------------------------------
+    struct FxQuote(Options);
+    impl GarmanKohlhagenGreeks for FxQuote {
+        fn get_option(&self) -> Result<&Options, GreeksError> {
+            Ok(&self.0)
+        }
+    }
+    let q = FxQuote(build_option(1.10, 1.10, OptionStyle::Call));
+    info!("");
+    info!(
+        "Trait usage: Δ={delta} ρd={rho_d} ρf={rho_f}",
+        delta = q.delta_gk()?,
+        rho_d = q.rho_domestic_gk()?,
+        rho_f = q.rho_foreign_gk()?,
+    );
+
+    Ok(())
+}