address review: pass-through PricingError + GK doc/match cleanup

joaquinbejar · joaquinbejar · commit be44687f7cf2 · 2026-04-26T10:28:07.000+02:00
Addresses the four Copilot review comments on PR #399. - src/pricing/unified.rs: the closed-form branches (BS, Black-76, GK) were wrapping every underlying `PricingError` via `method_error(..)`, which discarded the structured variant and made it impossible for callers to pattern-match on `UnsupportedOptionType` / `ExpirationDate` / `Greeks`. Switch the three branches to `?` pass-through so the original variant survives. Update the `# Errors` docstring to describe the actual propagation behaviour and the variant set callers should expect. - src/pricing/garman_kohlhagen.rs: collapse the 14-arm `OptionType` match into `European => black_scholes(option); _ => Err(...)`. The wildcard arm tags the error as `"Non-European"`, which is what the unit tests already assert via `is_err()` and is more maintainable when new exotic variants land. - src/pricing/garman_kohlhagen.rs: document the non-negative `r_f` limitation imposed by `Options::dividend_yield: Positive` in both the module-level *Limitations* section and the function-level `# Limitations` block. Negative-rate FX regimes (CHF / JPY / EUR 2015–2022) cannot be expressed with the current schema; lifting the constraint requires a dedicated signed `foreign_rate` field, which is deliberately out of scope. `cargo test --lib`: 3805 passed; 0 failed. Clippy / fmt / build clean.
diff --git a/.issue-black76-greeks.md b/.issue-black76-greeks.md
@@ -0,0 +1,56 @@
+## Overview
+
+Implement Greeks (Delta, Gamma, Vega, Theta, Rho) for the Black-76 closed-form pricing model. Black-76 is used for options on futures, forwards, swaptions, and commodity futures. Greeks are essential for risk management and hedging.
+
+## Context
+
+- Related PRs: #398 (Black-76 pricing kernel)
+- Model reference: Black (1976) "The pricing of commodity contracts"
+- Existing Greeks framework: `src/greeks/` with Black-Scholes, Monte-Carlo Greeks
+- Field mapping: `underlying_price` → forward F, `risk_free_rate` → r (discount), `dividend_yield` → ignored (F is carry-adjusted)
+
+## Formulas
+
+All derivatives are with respect to spot movements in the forward price F.
+
+**Call delta**: `Δ_call = e^(-rT) · N(d1)`
+**Put delta**: `Δ_put = -e^(-rT) · N(-d1)`
+
+**Gamma** (same for calls/puts): `Γ = e^(-rT) · n(d1) / (F · σ · √T)` where n = std normal pdf
+
+**Vega** (same for calls/puts): `ν = F · e^(-rT) · n(d1) · √T` (per 1% vol change)
+
+**Theta** (per calendar day): `Θ_call = -F · e^(-rT) · n(d1) · σ / (2√T) - r · K · e^(-rT) · N(d2)`
+
+**Rho** (per 1% rate change): `ρ_call = K · T · e^(-rT) · N(d2)`
+
+## Tasks
+
+- [ ] `src/greeks/black_76.rs` — delta, gamma, vega, theta, rho functions (call/put variants)
+- [ ] Helper `calculate_d_values_black_76` if not already co-located (verify deduplication vs pricing module)
+- [ ] Trait `Black76Greeks` with default implementations (pattern mirror from `BlackScholesGreeks`)
+- [ ] Tests: reference values (Hull), Greek identities (e.g. call-delta - put-delta = e^(-rT)), monotonicity, edge cases
+- [ ] Example: `examples/examples_pricing/src/bin/black_76_greeks.rs` — compute Greeks for commodity futures scenario
+- [ ] Docs: header in `src/greeks/mod.rs`, inline `///` per function
+- [ ] Re-exports: `pub use black_76::{Black76Greeks, ...}` in `src/greeks/mod.rs`
+
+## Acceptance criteria
+
+- [ ] Delta monotonicity: call delta 0..1, put delta -1..0, relation `Δ_call - Δ_put = e^(-rT)`
+- [ ] Gamma > 0 always (convexity)
+- [ ] Vega > 0 always (price increases with volatility)
+- [ ] Hull reference values to 1e-3 tolerance (pick 2-3 examples from Hull tables)
+- [ ] Cross-check vs Black-Scholes Greeks with S=F·e^(-rT), q=0 to 1e-9 (Greeks should match exactly post transformation)
+- [ ] Zero volatility → error (consistent with pricing)
+- [ ] Unsupported option types (American, exotic) → appropriate error
+- [ ] `cargo clippy --all-targets --all-features --workspace -- -D warnings` clean
+- [ ] `cargo fmt --all --check` clean
+- [ ] `cargo test --all-features --workspace` clean
+- [ ] `cargo build --release` clean
+- [ ] All `pub` items documented
+
+## References
+
+- Black, F. (1976). "The pricing of commodity contracts." Journal of Financial Economics.
+- Hull, J. (2017). *Options, Futures, and Other Derivatives* (10th ed.). Prentice Hall.
+- Wystup, U. (2006). *FX Options and Structured Products*.
diff --git a/.issue-gk-greeks.md b/.issue-gk-greeks.md
@@ -0,0 +1,61 @@
+## Overview
+
+Implement Greeks (Delta, Gamma, Vega, Theta, and two Rhos) for the Garman-Kohlhagen FX pricing model. Garman-Kohlhagen is the standard for options on foreign exchange. FX Greeks differ from equity Greeks in that they depend on two interest rates (domestic and foreign) and have two separate Rho sensitivities.
+
+## Context
+
+- Related PRs: #399 (Garman-Kohlhagen pricing kernel)
+- Model reference: Garman & Kohlhagen (1983) "Foreign currency option values"
+- Existing Greeks framework: `src/greeks/` with Black-Scholes, Monte-Carlo Greeks
+- Field mapping: `underlying_price` → spot FX S, `risk_free_rate` → r_d (domestic), `dividend_yield` → r_f (foreign, since GK ≡ BSM with q=r_f)
+- Structural note: GK Greeks are **mathematically equivalent** to BSM Greeks post-transformation, but FX conventions use spot-delta (not forward-delta) and split rho into `rho_d` (domestic) and `rho_f` (foreign)
+
+## Formulas
+
+All Greeks use spot S and two interest rates.
+
+**Call delta (spot)**: `Δ_call = e^(-r_f·T) · N(d1)`
+**Put delta (spot)**: `Δ_put = -e^(-r_f·T) · N(-d1)`
+
+**Gamma** (same for calls/puts): `Γ = e^(-r_f·T) · n(d1) / (S · σ · √T)` where n = std normal pdf
+
+**Vega** (same for calls/puts): `ν = S · e^(-r_f·T) · n(d1) · √T` (per 1% vol change)
+
+**Theta** (per calendar day): Complex formula including both r_d and r_f terms (see Garman & Kohlhagen 1983 or Hull)
+
+**Rho domestic** (per 1% domestic rate change): `ρ_d = K · T · e^(-r_d·T) · N(d2)` for calls, `= -K · T · e^(-r_d·T) · N(-d2)` for puts
+
+**Rho foreign** (per 1% foreign rate change): `ρ_f = -S · T · e^(-r_f·T) · N(d1)` for calls, `= S · T · e^(-r_f·T) · N(-d1)` for puts
+
+## Tasks
+
+- [ ] `src/greeks/garman_kohlhagen.rs` — delta, gamma, vega, theta, rho_domestic, rho_foreign functions (call/put variants)
+- [ ] Helper `calculate_d_values_garman_kohlhagen` if needed (verify deduplication vs pricing module)
+- [ ] Trait `GarmanKohlhagenGreeks` with default implementations (pattern from `BlackScholesGreeks`)
+- [ ] Tests: reference values (Garman & Kohlhagen paper, Hull, Wystup), Greek identities (delta parity), monotonicity in S/r_d/r_f, edge cases
+- [ ] Example: `examples/examples_pricing/src/bin/garman_kohlhagen_greeks.rs` — compute Greeks for USD/EUR FX option scenario
+- [ ] Docs: header in `src/greeks/mod.rs`, inline `///` per function, explain r_d/r_f split
+- [ ] Re-exports: `pub use garman_kohlhagen::{GarmanKohlhagenGreeks, ...}` in `src/greeks/mod.rs`
+
+## Acceptance criteria
+
+- [ ] Delta monotonicity: call delta 0..e^(-r_f·T), put delta between -e^(-r_f·T)..0, delta parity
+- [ ] Gamma > 0 always (convexity)
+- [ ] Vega > 0 always
+- [ ] Rho sensitivities have correct sign (positive for long calls in r_d, negative in r_f; opposite for puts)
+- [ ] Hull and Garman & Kohlhagen reference values to 1e-3 tolerance (2-3 FX examples)
+- [ ] Cross-check vs Black-Scholes Greeks with S and q=r_f to 1e-9 (delta, gamma, vega post-transformation should match exactly)
+- [ ] Zero volatility → error
+- [ ] Unsupported option types (American, exotic) → appropriate error
+- [ ] Theta formula tested against numerical differentiation (Black-Scholes theta benchmark adapted for GK)
+- [ ] `cargo clippy --all-targets --all-features --workspace -- -D warnings` clean
+- [ ] `cargo fmt --all --check` clean
+- [ ] `cargo test --all-features --workspace` clean
+- [ ] `cargo build --release` clean
+- [ ] All `pub` items documented
+
+## References
+
+- Garman, M. B., & Kohlhagen, S. W. (1983). "Foreign currency option values." Journal of International Money and Finance, 2(3), 231–237.
+- Hull, J. (2017). *Options, Futures, and Other Derivatives* (10th ed.). Prentice Hall. [Chapter 17 on FX options]
+- Wystup, U. (2006). *FX Options and Structured Products*. Wiley.
diff --git a/src/pricing/garman_kohlhagen.rs b/src/pricing/garman_kohlhagen.rs
@@ -17,14 +17,27 @@
 //! `Options` carries a single risk-free rate plus a `dividend_yield`. For
 //! Garman–Kohlhagen we reuse those fields with the FX interpretation:
 //!
-//! - `Options::risk_free_rate`  — domestic risk-free rate `r_d`.
-//! - `Options::dividend_yield`  — foreign risk-free rate `r_f`.
+//! - `Options::risk_free_rate`  — domestic risk-free rate `r_d`
+//!   (signed `Decimal`, may be negative).
+//! - `Options::dividend_yield`  — foreign risk-free rate `r_f`
+//!   (`Positive`, must be ≥ 0 — see *Limitations* below).
 //! - `Options::underlying_price` — spot FX rate `S`.
 //!
 //! No schema change is required. The mapping is intentional: GK is the
 //! standard textbook reduction of BSM under the FX interpretation, and
 //! delegating to [`crate::pricing::black_scholes_model::black_scholes`]
 //! guarantees a bit-exact equivalence to the BSM kernel.
+//!
+//! ## Limitations
+//!
+//! Because `Options::dividend_yield` is a [`positive::Positive`],
+//! reusing it as `r_f` constrains the foreign rate to be non-negative.
+//! Negative-rate FX regimes (e.g. CHF, JPY, EUR for parts of the
+//! 2015–2022 cycle) cannot be priced through this entry point with the
+//! current `Options` schema. Lifting that limitation requires either a
+//! dedicated signed `foreign_rate` field on `Options` (a schema change,
+//! deliberately out of scope for this addition) or a follow-up issue
+//! tracking a relaxed FX-specific input struct.
 
 use crate::Options;
 use crate::error::PricingError;
@@ -84,6 +97,13 @@ use tracing::instrument;
 /// expiration cannot be converted to a positive year fraction, and
 /// [`PricingError::MethodError`] when the underlying BSM kernel hits a
 /// numerical wall (e.g. zero volatility, non-finite intermediate value).
+///
+/// # Limitations
+///
+/// `Options::dividend_yield` is a [`positive::Positive`], so the foreign
+/// rate `r_f` mapped onto it must be ≥ 0. Negative-rate FX regimes
+/// cannot be expressed through this entry point with the current schema;
+/// see the module-level *Limitations* section.
 #[instrument(skip(option), fields(
     strike = %option.strike_price,
     style = ?option.option_style,
@@ -94,60 +114,8 @@ use tracing::instrument;
 pub fn garman_kohlhagen(option: &Options) -> Result<Decimal, PricingError> {
     match option.option_type {
         OptionType::European => black_scholes(option),
-        OptionType::American => Err(PricingError::unsupported_option_type(
-            "American",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Bermuda { .. } => Err(PricingError::unsupported_option_type(
-            "Bermuda",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Asian { .. } => Err(PricingError::unsupported_option_type(
-            "Asian",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Barrier { .. } => Err(PricingError::unsupported_option_type(
-            "Barrier",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Binary { .. } => Err(PricingError::unsupported_option_type(
-            "Binary",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Lookback { .. } => Err(PricingError::unsupported_option_type(
-            "Lookback",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Compound { .. } => Err(PricingError::unsupported_option_type(
-            "Compound",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Chooser { .. } => Err(PricingError::unsupported_option_type(
-            "Chooser",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Cliquet { .. } => Err(PricingError::unsupported_option_type(
-            "Cliquet",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Rainbow { .. } => Err(PricingError::unsupported_option_type(
-            "Rainbow",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Spread { .. } => Err(PricingError::unsupported_option_type(
-            "Spread",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Quanto { .. } => Err(PricingError::unsupported_option_type(
-            "Quanto",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Exchange { .. } => Err(PricingError::unsupported_option_type(
-            "Exchange",
-            "Garman-Kohlhagen",
-        )),
-        OptionType::Power { .. } => Err(PricingError::unsupported_option_type(
-            "Power",
+        _ => Err(PricingError::unsupported_option_type(
+            "Non-European",
             "Garman-Kohlhagen",
         )),
     }
diff --git a/src/pricing/unified.rs b/src/pricing/unified.rs
@@ -91,39 +91,34 @@ pub enum PricingEngine {
 ///
 /// # Errors
 ///
-/// Propagates any `PricingError` returned by the selected engine:
-/// `PricingError::ExpirationDate` or `PricingError::MethodError`
-/// from Black–Scholes, Black-76, and Garman–Kohlhagen (all three
-/// surface `MethodError` for zero-volatility / non-finite intermediate
-/// values, and the latter two also return
-/// [`PricingError::UnsupportedOptionType`] for non-European inputs);
-/// [`PricingError::BinomialNodeMissing`] or
-/// [`PricingError::SqrtFailure`] from the binomial lattice; the
-/// equivalent failures from exotic engines (barrier, binary,
-/// compound, chooser, cliquet, lookback, telegraph); and
-/// `PricingError::SimulationError` from the Monte Carlo engine.
+/// Propagates the original `PricingError` returned by the selected engine
+/// without wrapping, so callers can pattern-match on the structured
+/// variants. From the closed-form engines (Black–Scholes, Black-76,
+/// Garman–Kohlhagen) you may receive [`PricingError::ExpirationDate`],
+/// [`PricingError::Greeks`] (for example zero-volatility or non-finite
+/// intermediate values bubbled up from `d1`/`d2`), and (Black-76 and
+/// Garman–Kohlhagen) [`PricingError::UnsupportedOptionType`] for
+/// non-European inputs. From the binomial lattice you may receive
+/// [`PricingError::BinomialNodeMissing`] or [`PricingError::SqrtFailure`].
+/// The Monte Carlo engine surfaces failures as
+/// [`PricingError::SimulationError`], and exotic engines surface their
+/// own variants (barrier, binary, compound, chooser, cliquet, lookback,
+/// telegraph).
 pub fn price_option(option: &Options, engine: &PricingEngine) -> PricingResult<Positive> {
     match engine {
         PricingEngine::ClosedFormBS => {
-            let price_decimal = black_scholes(option)
-                .map_err(|e| PricingError::method_error("Black-Scholes", &e.to_string()))?;
-
-            // Convert Decimal to Positive using From trait
+            let price_decimal = black_scholes(option)?;
             Ok(Positive::new_decimal(price_decimal.abs())?)
         }
         PricingEngine::ClosedFormBlack76 => {
-            let price_decimal = black_76(option)
-                .map_err(|e| PricingError::method_error("Black-76", &e.to_string()))?;
-
+            let price_decimal = black_76(option)?;
             Ok(Positive::new_decimal(price_decimal.abs())?)
         }
         PricingEngine::MonteCarlo { simulator } => simulator
             .get_mc_option_price(option)
             .map_err(|e| PricingError::simulation_error(&e.to_string())),
         PricingEngine::ClosedFormGK => {
-            let price_decimal = garman_kohlhagen(option)
-                .map_err(|e| PricingError::method_error("Garman-Kohlhagen", &e.to_string()))?;
-
+            let price_decimal = garman_kohlhagen(option)?;
             Ok(Positive::new_decimal(price_decimal.abs())?)
         }
     }
