greeks-pattern

name: greeks-pattern description: How to expose first- and second-order Greeks via the GreeksExt trait in stochastic-rs. Invoke when adding a new pricer that needs delta/gamma/vega/theta/rho/vanna/charm/volga/veta, or when a Monte Carlo pricer is missing the single-pass greeks() override.

Greeks pattern — stochastic-rs

The GreeksExt trait in stochastic-rs-quant::traits lets pricers report first- and second-order Greeks via a uniform interface. The trait has default implementations that compute each Greek by finite-differencing the pricer's calculate_price(), plus a single greeks() aggregator that returns the full bundle.

The single-pass greeks() aggregator is the load-bearing part for MC pricers: defaults call each Greek separately, which means N independent re-pricings (with different random seeds, in general). Overriding greeks() to share a single set of MC paths across all Greeks is mandatory for MC pricers; otherwise users get visibly inconsistent delta/gamma/vega from re-runs.

1. The trait surface

// stochastic-rs-quant/src/traits/pricing.rs

#[derive(Debug, Clone, Default)]
pub struct Greeks {
    pub delta: f64,
    pub gamma: f64,
    pub vega: f64,
    pub theta: f64,
    pub rho: f64,
    pub vanna: f64,
    pub charm: f64,
    pub volga: f64,
    pub veta: f64,
}

pub trait GreeksExt: PricerExt {
    fn delta(&self) -> f64 { /* default: central diff in spot */ }
    fn gamma(&self) -> f64 { /* default: central second-diff in spot */ }
    fn vega(&self)  -> f64 { /* default: central diff in vol */ }
    fn theta(&self) -> f64 { /* default: forward diff in tau, sign-flipped */ }
    fn rho(&self)   -> f64 { /* default: central diff in r */ }
    fn vanna(&self) -> f64 { /* default: cross-diff (S, σ) */ }
    fn charm(&self) -> f64 { /* default: cross-diff (S, T) */ }
    fn volga(&self) -> f64 { /* default: second-diff in σ */ }
    fn veta(&self)  -> f64 { /* default: cross-diff (σ, T) */ }

    /// Single-pass aggregator. Default implementation calls each
    /// per-Greek method individually, which is fine for analytic
    /// pricers (delta() + gamma() + vega() are independent
    /// finite-difference calls) but is INCORRECT for Monte Carlo
    /// pricers — they must override this to share a single set of paths.
    fn greeks(&self) -> Greeks {
        Greeks {
            delta: self.delta(),
            gamma: self.gamma(),
            vega:  self.vega(),
            theta: self.theta(),
            rho:   self.rho(),
            vanna: self.vanna(),
            charm: self.charm(),
            volga: self.volga(),
            veta:  self.veta(),
        }
    }
}

2. Which Greek when

The Greeks struct is a flat f64 bundle by design. Per-pricer overrides typically fill only the Greeks that have analytic closed forms (e.g. BSM does delta/gamma/vega/theta/rho analytically) and leave the second-order cross-Greeks at the trait default (numerical).

3. NaN defaults — when you don't compute a Greek

If a pricer cannot compute a particular Greek (e.g. a fixed-strike basket pricer that has no σ parameter to bump), set the field to f64::NAN rather than 0.0. Convention:

fn vega(&self) -> f64 {
    f64::NAN  // basket has no σ; consumers detect via .is_nan()
}

Do not return 0.0 for "not applicable" cases. Zero is a valid sensitivity value and silently masks bugs (a basket reporting 0 vega looks like a vol-immunised portfolio, which is misleading).

4. Single-pass MC override (mandatory for MC pricers)

The default greeks() aggregator calls each Greek method sequentially. For an analytic pricer that re-uses the same closed-form inputs, this is fine. For a Monte Carlo pricer, each call re-samples paths from a different RNG state (or the same seed twice, depending on construction), and the resulting deltas / gammas / vegas don't share control variates. The user observes "delta-from-greeks() ≠ delta-direct()" within numerical noise.

The mandated pattern: override greeks() to do one big simulation and populate all Greeks from the same path set:

impl GreeksExt for MyMcPricer {
    fn greeks(&self) -> Greeks {
        // Generate *one* set of paths.
        let paths = self.simulate_with_seed(self.master_seed);
        // Re-price under each Greek bump using the same path noise
        // (Common Random Numbers — Glasserman 2003 §7.1).
        let v_base = price_from_paths(&paths, self);
        let v_sup  = price_from_paths(&paths, &self.with_spot_bump( h));
        let v_sdn  = price_from_paths(&paths, &self.with_spot_bump(-h));
        let v_vup  = price_from_paths(&paths, &self.with_vol_bump( hs));
        let v_vdn  = price_from_paths(&paths, &self.with_vol_bump(-hs));
        // ... etc ...
        Greeks {
            delta: (v_sup - v_sdn) / (2.0 * h),
            gamma: (v_sup - 2.0 * v_base + v_sdn) / (h * h),
            vega:  (v_vup - v_vdn) / (2.0 * hs),
            // ...
            ..Default::default()  // unfilled Greeks → 0.0; or use NAN sentinel
        }
    }
}

The with_spot_bump(...) / with_vol_bump(...) constructors must clone the pricer with the bumped parameter and re-use the same seed so "common random numbers" gives variance reduction. Two reference implementations:

• GbmMalliavinGreeks (pricing/malliavin_thalmaier/gbm.rs): the cleanest single-pass example; uses Malliavin weights to compute Greeks without finite differencing, but the surrounding greeks() shape is the canonical pattern.
• HestonMalliavinGreeks (pricing/malliavin_thalmaier/heston.rs): multi-asset extension; same single-pass shape with cross-Greeks.

5. Analytic-pricer minimal impl

For an analytic (closed-form) pricer, you usually only override the Greeks you know analytically:

impl GreeksExt for BsmPricer {
    fn delta(&self) -> f64 {
        let d1 = self.d1();
        match self.option_type {
            OptionType::Call => norm_cdf(d1),
            OptionType::Put  => norm_cdf(d1) - 1.0,
        }
    }

    fn gamma(&self) -> f64 {
        let d1 = self.d1();
        norm_pdf(d1) / (self.s * self.sigma * self.tau.sqrt())
    }

    fn vega(&self) -> f64 {
        let d1 = self.d1();
        self.s * norm_pdf(d1) * self.tau.sqrt()
    }

    // theta, rho, vanna, charm, volga, veta — fall through to default
    // finite-difference, which is fine for an analytic pricer.

    // greeks() — fall through to default; the cost of N calls is N
    // closed-form evaluations, no random-noise problem.
}

Reference: BsmPricer in pricing/bsm.rs.

6. Bump-size conventions

The default finite-difference Greeks pick bump sizes that scale with the parameter magnitude:

Custom bump sizes for a specific pricer can be exposed as with_bump_sizes(...) builder methods, but the defaults work for 95% of cases. If you find yourself needing ad-hoc bumps in calibration, that's a hint to switch to analytic Greeks.

7. Testing

A new pricer with GreeksExt must ship at least:

1. Sign tests: call delta is positive, put delta is negative, gamma is positive for both, vega is positive.
2. Put-call parity for delta: Δ_call - Δ_put = e^{-qT}.
3. Bumped-NPV consistency: (price(S+h) - price(S-h)) / (2h) agrees with delta() to the bump precision.
4. Single-pass consistency (MC only): greeks().delta == delta() within MC tolerance, sourced from the same seed.

Reference: pricing/bsm.rs tests. The MC tests live next to each Malliavin-Greeks pricer (pricing/malliavin_thalmaier/*.rs).

8. Anti-patterns

• Do not return 0.0 for "not applicable" Greeks. Use f64::NAN.
• Do not override an individual Greek but leave greeks() at the default in an MC pricer. The user-facing Greeks then have asymmetric precision across components (the override Greek is single-pass, the rest re-sample).
• Do not finite-difference the price by re-running an MC pricer with a different RNG state per Greek. Always seed-share via with_*_bump(...) constructors.
• Do not invent new Greek field names. Greeks is a fixed flat struct; if you need an extra Greek (e.g. zomma = ∂Γ/∂σ), extend the struct in one PR rather than smuggling it through a HashMap-style side channel.

9. Reference impls

• pricing/bsm.rs — analytic + default fall-through.
• pricing/heston.rs — analytic delta/vega/theta + default fall-through.
• pricing/malliavin_thalmaier/gbm.rs — Malliavin-weighted single-pass.
• pricing/malliavin_thalmaier/heston.rs — multi-asset Malliavin.
• pricing/malliavin_thalmaier/sabr.rs — SABR Malliavin.

Related SKILLs

• add-mc-variance-reduction — explains the Common Random Numbers requirement that the single-pass greeks() override depends on.
• calibration-pattern — calibrators consume Greeks via the result's to_model().greeks() chain.
• release-checklist — the rc.X CHANGELOG should note any new Greek added to the public surface.