Struct VolatilitySurface 

pub struct VolatilitySurface {
    points: HashMap<i64, HashMap<i64, VolPoint>>,
    atm_vols: HashMap<i64, f64>,
    delta_curves: HashMap<i64, Vec<DeltaIvPoint>>,
    strike_precision: f64,
    last_update: Option<i64>,
    expiries: BTreeSet<i64>,
}

Volatility surface for a single underlying.

Supports two data representations:

1. Strike-space: direct (strike, expiry) → IV grid with bilinear interpolation
2. Delta-space: (delta, expiry) → IV curves, queried via strike→delta conversion

When both are available, strike-space is preferred (exact). When only delta-space data exists (e.g., from Block Scholes delta.iv feed), the caller provides spot price to convert query strikes to deltas for interpolation.

Fields

points: HashMap<i64, HashMap<i64, VolPoint>>

Map from quantized_strike -> expiry -> VolPoint

atm_vols: HashMap<i64, f64>

ATM volatilities by expiry for quick ATM lookups

delta_curves: HashMap<i64, Vec<DeltaIvPoint>>

Delta-IV curves by expiry, sorted by delta ascending

strike_precision: f64

Strike quantization factor (e.g., 100 = $100 precision)

last_update: Option<i64>

Last update time for the entire surface (milliseconds)

expiries: BTreeSet<i64>

All known expiries for iteration

Implementations

impl VolatilitySurface

pub fn new() -> Self

Create a new empty volatility surface with default $1 strike precision.

pub fn with_precision(strike_precision: f64) -> Self

Create a new volatility surface with custom strike precision.

Arguments

• strike_precision - Strike price bucket size (e.g., 1.0 for $1 buckets)

fn quantize_strike(&self, strike: f64) -> i64

Quantize strike to avoid floating point comparison issues.

pub fn insert(&mut self, strike: f64, expiry: i64, iv: f64)

Insert or update a volatility point.

pub fn set_atm_vol(&mut self, expiry: i64, iv: f64)

Set ATM volatility for an expiry.

pub fn set_delta_iv(&mut self, expiry: i64, delta: f64, iv: f64)

Store a delta-IV point for an expiry.

Delta-IV curves are used when strike-level data is unavailable. The caller provides spot price at query time to convert strikes to deltas.

pub fn get(&self, strike: f64, expiry: i64) -> Option<f64>

Get volatility at exact (strike, expiry) or None.

pub fn get_point(&self, strike: f64, expiry: i64) -> Option<&VolPoint>

Get the full VolPoint at exact (strike, expiry) or None.

pub fn get_interpolated_with_spot( &self, strike: f64, expiry: i64, spot: Option<f64>, ) -> Option<f64>

Get volatility with interpolation if exact match not found.

Uses bilinear interpolation across strike and expiry dimensions. If spot is provided and no strike-level data exists, falls back to delta-space interpolation: converts the query strike to a call delta and interpolates the delta-IV smile, then interpolates across expiries.

pub fn get_interpolated(&self, strike: f64, expiry: i64) -> Option<f64>

Get volatility with interpolation (no spot price for delta conversion).

fn interpolate_delta_surface( &self, strike: f64, expiry: i64, spot: f64, ) -> Option<f64>

Interpolate the delta-IV surface for a given strike and expiry.

Converts strike to call delta using approximate ATM vol, then linearly interpolates the delta-IV smile at that delta. Finally interpolates across expiries.

fn interpolate_delta_smile_at_expiry( &self, strike: f64, expiry: i64, spot: f64, ) -> Option<f64>

Interpolate the delta-IV smile at a single expiry for a given strike.

pub fn get_atm(&self, expiry: i64) -> Option<f64>

Get ATM volatility for a given expiry.

pub fn last_update(&self) -> Option<i64>

Get the last update timestamp.

pub fn expiries(&self) -> &BTreeSet<i64>

Get all known expiries.

pub fn len(&self) -> usize

Get the number of points in the surface.

pub fn is_empty(&self) -> bool

Check if the surface is empty.

pub fn export_all_points(&self) -> Vec<VolPoint>

Export all strike-space points for serialisation.

pub fn export_delta_curves(&self) -> Vec<DeltaCurveExport>

Export delta-IV curves for every expiry.

pub fn export_atm_vols(&self) -> Vec<(i64, f64)>

Export ATM vols as (expiry, iv) pairs.

pub fn sanitize_arb_free(&mut self, spot: f64, risk_free_rate: f64) -> u32

Enforce static no-arbitrage constraints on the strike-indexed surface.

For each expiry, walks strikes ascending and clamps IVs down so that:

1. Call prices are non-increasing in K (no vertical-spread arb)
2. Call prices are convex in K (no butterfly arb)

Both constraints follow from risk-neutral pricing; they must hold for any arb-free surface. We enforce in price space (via Black-Scholes) then back out the clamped IV by bisection — this handles non-uniform strike grids correctly and uses the same pricer the rest of the system trusts.

Only clamps down: if an IV is lower than it should be for arb-freeness, we do nothing. Lowering an IV cannot create new arbs against neighbors we have already cleaned.

Returns the number of IV points modified. Pass risk_free_rate = 0.0 on testnet.

fn update_iv(&mut self, quantized_strike: i64, expiry: i64, new_iv: f64)

Mutate the stored IV for an already-present (quantized_strike, expiry).

pub fn clear(&mut self)

Clear all data from the surface.

fn find_bracketing_values( &self, target: i64, keys: &[i64], ) -> Option<(i64, i64)>

Find bracketing values for interpolation.

fn bilinear_interpolate(&self, point: BilinearPoint) -> Option<f64>

Perform bilinear interpolation on the four corner values.

Trait Implementations

impl Clone for VolatilitySurface

fn clone(&self) -> VolatilitySurface

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VolatilitySurface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for VolatilitySurface

fn default() -> Self

Returns the “default value” for a type.