Module derivatives 

Derivatives math (options & related)

Pure pricing, Greeks, and implied volatility for engines that also run crate::stocks::ta on the underlier. This module does not subscribe to option chains, manage multi-leg books, or know about OSI / exchange symbols.

---

How a quant uses these metrics (trading perspective)

Metric	Trading question	Desk habit
Price	Fair value vs mid / edge?	Compare model to NBBO; mark inventory
Δ Delta	How much underlier exposure per option?	Hedge: sell ≈ Δ shares per long call
Γ Gamma	How fast does the hedge go wrong?	Scalp gamma; size limits into events
ν Vega	What if IV moves a point?	Vol trades, earnings, event premium
Θ Theta	What does the book bleed overnight?	Carry P&L, calendar spreads
ρ Rho	Rate risk?	Usually second-order for short-dated equity
Vanna / Volga / Charm	Surface & Δ-drift risk	Sticky-strike stories; overnight re-hedge
IV	What vol is the market implying?	Surfaces, relative value, skew stories
Intrinsic / time value	How much is “optionality”?	Early exercise intuition (European here)
Parity residual	Is the quote book consistent?	Sanity / arb alert (within fees)

Typical workflow on a name (e.g. AAPL):

1. Trade the underlier path with TA (StochState, EmaState, …) on 1m/5s bars.
2. For each option of interest, maintain IV from mid and Greeks at live spot.
3. Risk: sum Δ/Γ/ν over positions; hedge underlier when net Δ exceeds a band.
4. Research: reprice a chain on a vol surface assumption; compare to TA regime (e.g. high RVOL + high IV).

This crate supplies steps 1–3 math only. Order routing, position servers, and “should I sell the 0.30Δ call?” stay in your strategy code.

---

How an engineer wires this (engineering perspective)

Market data (async / websockets)          finance-solution (sync, pure)
───────────────────────────────          ─────────────────────────────
1m bars for underlier          ──push──► StochState / EmaState / …
option quote (bid/ask/mid)     ──IV───► BsmState::set_vol_from_price
underlier tick                 ──spot─► for c in chain { c.set_spot(s); greeks() }
futures mark                   ──F────► Black76State::set_forward
FX spot                        ──S────► GkState::set_spot

Recommended shape (mirrors TA):

Layer	Type	When
Config	BsmParams / Black76Params / GkParams (Copy)	Contract + market inputs
Validated	ValidatedBsm::new / …	One-shot research / backtest bar
Live	BsmState / Black76State / GkState	Per-contract object in HashMap
Teaching	bsm_solution / black76_solution / gk_solution	Formulas + print_table

Concurrency: keep math sync. Your runtime may rayon over strikes or tokio only to receive data — there is no I/O inside these functions.

---

Models

Model	Underlier	Status
Black–Scholes–Merton	Spot S, continuous yield q	available (+ cross Greeks)
Black ’76	Forward / futures F	available
Garman–Kohlhagen	FX spot, (r_d), (r_f)	available
CRR binomial	European / American tree	available

Equity single-name Europeans with continuous yield ≈ BSM.
Options on futures / many index products → Black ’76.
FX vanillas → Garman–Kohlhagen.
American early exercise / American IV → CRR (crr_price, american_implied_vol).
Crypto perps need funding / mark conventions outside this module.

Units (read carefully)

Input	Unit
Spot / forward / strike	same money units
time_years	years (30.0/365.25 for ~30 calendar days)
rates	continuous, absolute (0.05 = 5%)
vol	annualized absolute (0.20 = 20%)
Vega	per +1.0 in σ (use vega_per_vol_point for per 1%)
Theta / charm	per year (use *_per_calendar_day helpers)

Quick start

use finance_solution::derivatives::{
    OptionType, BsmParams, ValidatedBsm, bsm_price, bsm_greeks, bsm_cross_greeks,
    bsm_implied_vol, Black76Params, black76_price, GkParams, gk_price,
};

let p = BsmParams::atm_one_year(100.0, 0.05, 0.20);
let model = ValidatedBsm::new(p).unwrap();
let call = model.price(OptionType::Call).unwrap();
let g = model.greeks(OptionType::Call).unwrap();
let x = bsm_cross_greeks(p, OptionType::Call).unwrap();
assert!(call > 0.0 && g.delta > 0.0 && x.volga.is_finite());

let iv = bsm_implied_vol(p, OptionType::Call, call).unwrap();
assert!((iv - 0.20).abs() < 1e-4);

// Futures-style
let f = Black76Params::atm_one_year(100.0, 0.05, 0.20);
let _ = black76_price(f, OptionType::Call).unwrap();

// FX-style
let fx = GkParams::atm_one_year(1.10, 0.05, 0.03, 0.12);
let _ = gk_price(fx, OptionType::Call).unwrap();

Live underlier ticks: BsmState / Black76State / GkState.
Teaching: bsm_solution, black76_solution, gk_solution, crr_solution.
American: crr_price + american_implied_vol.

Modules

black76

Black ’76 — European options on a forward / futures

black_scholes

Black–Scholes–Merton European options

crr

Cox–Ross–Rubinstein (CRR) binomial tree

garman_kohlhagen

Garman–Kohlhagen — European FX options

implied_vol

Implied volatility

norm

Standard normal PDF and CDF (no external special-function crate).

state

Live BSM state — engineering for streaming underliers

types

Shared option types and BSM parameter packs.

Structs

Black76Greeks

First-order Black ’76 Greeks (Δ is forward delta).

Black76Params

Black ’76 inputs (European option on a forward).

Black76Solution

Teaching solution for Black ’76.

Black76State

Live Black ’76 contract state (forward / vol / time updates).

Black76Terms

d1/d2 and discount for Black ’76.

BsmCrossGreeks

Cross / second-order BSM Greeks (vol surface & hedge-drift risk).

BsmGreeks

First-order BSM Greeks.

BsmParams

Black–Scholes–Merton inputs (European, continuous dividend yield q).

BsmSolution

Teaching solution: price, greeks, cross Greeks, parity check, formulas.

BsmState

Mutable European option under BSM (spot / vol / time / strike updates).

BsmTerms

Intermediate terms shared by price and Greeks (d1, d2, discounts).

CrrGreeks

Tree first-order risk (Δ/Γ from nodes; vega bumped).

CrrNode

One node for teaching tables.

CrrParams

CRR tree inputs (equity-style continuous (q)).

CrrSolution

Full teaching solution.

GkGreeks

GK Greeks: BSM-style plus dual rate rhos.

GkParams

Garman–Kohlhagen inputs.

GkSolution

Teaching solution for GK.

GkState

Live FX option state.

ValidatedBlack76

Validated Black ’76 snapshot.

ValidatedBsm

Validated BSM pack (strictly positive S,K; non-negative T,σ; finite rates).

ValidatedCrr

Validated CRR pack.

ValidatedGk

Validated GK snapshot.

Enums

ExerciseStyle

European vs American exercise at each node.

OptionType

Call or put (European exercise in this module).

Functions

american_implied_vol

Alias: American IV when style is American (any style works).

black76_greeks

black76_implied_vol

Implied vol for Black ’76 given a market premium.

black76_parity_residual

C − P − e^{-rT}(F − K).

black76_price

black76_solution

black76_terms

bsm_cross_greeks

Cross Greeks: vanna, volga, charm (see BsmCrossGreeks).

bsm_greeks

European BSM Greeks (see BsmGreeks for units).

bsm_implied_vol

Solve for annualized vol given a target BSM premium.

bsm_price

European BSM price.

bsm_solution

Full teaching solution (price, greeks, intrinsic, parity, formulas).

bsm_terms

d1/d2 and discount factors (for teaching / advanced use).

crr_greeks

Tree Δ/Γ + FD vega.

crr_price

CRR option price.

crr_solution

Teaching solution; retains nodes when steps <= 12 (readable table).

forward_moneyness

Forward moneyness S e^{(r-q)T} / K.

gk_cross_greeks

gk_greeks

gk_implied_vol

gk_parity_residual

Put–call parity residual: C − P − (S e^{-r_f T} − K e^{-r_d T}).

gk_price

gk_solution

intrinsic

Intrinsic value (European exercise value at this spot).

put_call_parity_residual

Put–call parity residual: C − P − (S e^{−qT} − K e^{−rT}) (≈ 0 for BSM).

spot_moneyness

Spot moneyness S / K (not forward-adjusted).

time_value

Time value = premium − intrinsic (floored at 0 for numerical noise).

tree_implied_vol

American (or European) implied vol via Newton on CRR price + FD vega.