Skip to content

v0.17.2 — Black-76 + Garman–Kohlhagen pricing models

Choose a tag to compare

@joaquinbejar joaquinbejar released this 26 Apr 09:27
· 4 commits to main since this release
6cc3226

Release adding two new closed-form pricing models:

  • Black-76 (Black 1976) for European options on futures and forwards.
  • Garman–Kohlhagen (1983) for European FX options.

0.17.0 and 0.17.1 were preparatory iterations of this work
(0.17.0 was never published; 0.17.1 shipped to crates.io with a
partial subset). 0.17.2 is the first version that ships both models
together. PricingEngine is #[non_exhaustive] (semver-major from the
0.16.x line) and the two new variants are appended at the tail of the
enum so existing discriminants are preserved.

Added

Black-76 model (Black 1976):

  • pricing::black_76: closed-form black_76(option) -> Result<Decimal, PricingError>
    for European options on futures / forwards. Reuses the existing d1
    / d2 / big_n helpers; Decimal end-to-end via d_mul / d_sub;
    tracing::instrument on the entry point. Only OptionType::European
    is supported — American, Bermuda and exotics return
    PricingError::UnsupportedOptionType.
  • pricing::Black76 trait with default calculate_price_black_76
    (mirrors BlackScholes).
  • pricing::PricingEngine::ClosedFormBlack76 variant + dispatch from
    price_option.
  • greeks::utils::calculate_d_values_black_76 pub(crate) helper.
  • examples/examples_pricing/src/bin/black_76.rs: runnable demo
    (Hull canonical example, ITM commodity-futures call, unified-API
    dispatch, short-side sign convention).

Garman–Kohlhagen model (Garman & Kohlhagen 1983):

  • pricing::garman_kohlhagen: closed-form
    garman_kohlhagen(option) -> Result<Decimal, PricingError> for
    European options on FX spot rates. Structurally identical to BSM
    with q = r_f; the implementation delegates to black_scholes
    after type validation, guaranteeing bit-exact equivalence (verified
    to 1e-9 in the tests).
  • pricing::GarmanKohlhagen trait with default
    calculate_price_garman_kohlhagen (mirrors the BlackScholes
    trait pattern).
  • pricing::PricingEngine::ClosedFormGK variant + dispatch from
    price_option.
  • examples/examples_pricing/src/bin/garman_kohlhagen.rs: runnable
    demo (Hull canonical USD/GBP, ITM EUR/USD with FX parity check,
    unified-API dispatch, symmetric-rate degenerate case).

Infrastructure updates:

  • examples/examples_pricing/: new workspace member with binaries for
    both models.
  • lib.rs mermaid: Forward-Priced subgraph routing
    black_76 -> {Future, Forward}; new FX / Currency subgraph routing
    garman_kohlhagen -> FX Spot.

Changed

  • pricing::PricingEngine is now #[non_exhaustive] so future engine
    variants do not require a new major bump.
  • pricing::mod.rs Core Models / Model Selection Guidelines /
    Performance Considerations now include both Black-76 and
    Garman–Kohlhagen with explicit field mapping documentation.
  • financial_types bumped to 0.2.2 (adds UnderlyingAssetType::Future
    and UnderlyingAssetType::Forward).
  • PricingError and GreeksError pass-through in closed-form dispatch
    (BS, Black-76, GK) for full error-variant fidelity.