VolSurface

VolSurface calibrates individual SVI smiles for each expiry in a multi-expiry option chain and builds a total-variance interpolator across maturities. Once fitted, you can retrieve a VolCurve for maturities within the fitted range, including dates that fall between fitted pillars. You can also export the surface as a long-format DataFrame or derive a ProbSurface of risk-neutral distributions.

from oipd import VolSurface

Constructor

VolSurface(
    method="svi",
    pricing_engine="black76",
    price_method="mid",
    max_staleness_days=3,
)

str

default:"svi"

Calibration algorithm. Currently "svi" is the supported method.

Literal['black76', 'bs']

default:"black76"

Pricing model used for implied volatility inversion. Use "black76" for options on futures or forwards, and "bs" for spot options (Black-Scholes).

Literal['mid', 'last']

default:"mid"

Quote type to fit against per slice. "mid" uses the bid-ask midpoint, falling back to last_price when the mid is unavailable. "last" fits against last_price.

int

default:"3"

Maximum age of option quotes in calendar days, relative to the valuation date. Stale rows are excluded before fitting each slice.

Methods

fit(chain, market, column_mapping, horizon, failure_policy)

Calibrate all expiries in the chain and build the surface interpolator. Returns self for chaining.

surface.fit(
    chain,
    market,
    column_mapping=None,
    horizon=None,
    failure_policy="skip_warn",
)

pd.DataFrame

required

Multi-expiry option chain DataFrame. Must contain an expiry column and at least two unique expiry dates after filtering.

MarketInputs

required

Market inputs providing the risk-free rate, valuation date, and underlying price.

dict[str, str] | None

default:"None"

Optional mapping in the form {"dataframe_column": "oipd_column"}. See Standard columns for the target names.

str | date | pd.Timestamp | None

default:"None"

Optional fit horizon that filters out expiries beyond the cutoff. Accepts human-readable strings like "30d" or "12m", or an explicit date. Expiries after the cutoff are dropped before fitting.

Literal['skip_warn', 'raise']

default:"skip_warn"

Slice-level failure handling policy. "skip_warn" skips failing expiries and continues; "raise" propagates the first error immediately.

VolSurface

The fitted VolSurface instance (self).

Raises: ValueError if failure_policy is not a supported value. CalculationError if the expiry column is missing or invalid, if fewer than two unique expiries remain after filtering, or if calibration fails.

fit requires at least two unique expiries. Pass a single-expiry chain to VolCurve.fit instead.

slice(expiry)

Return a VolCurve for the requested maturity. If expiry matches a fitted pillar exactly, the original parametric curve is returned. Otherwise, a synthetic curve is derived from the total-variance interpolator.

surface.slice(expiry)

str | date | pd.Timestamp

required

Target expiry. Accepts ISO date strings like "2025-06-20", Python date objects, or pd.Timestamp. Interpolated maturities between fitted pillars are supported.

VolCurve

A VolCurve for the requested maturity.

Raises: ValueError if fit has not been called or if the maturity is outside the fitted range.

iv_results(domain, points, include_observed, start, end, step_days)

Return a long-format DataFrame of fitted IV results across expiries.

surface.iv_results(
    domain=None,
    points=200,
    include_observed=True,
    start=None,
    end=None,
    step_days=1,
)

tuple[float, float] | None

default:"None"

Optional (min_strike, max_strike) range per slice.

int

default:"200"

Number of fitted-curve evaluation points per expiry slice.

bool

default:"True"

Whether to include observed market IV columns.

str | date | pd.Timestamp | None

default:"None"

Lower expiry bound. Defaults to the first fitted pillar.

str | date | pd.Timestamp | None

default:"None"

Upper expiry bound. Defaults to the last fitted pillar.

int | None

default:"1"

Calendar-day sampling interval. Fitted pillar expiries are always included. Pass None to export fitted pillars only.

pd.DataFrame

Long-format DataFrame with an expiry column and per-slice IV data.

total_variance(K, t)

Return total variance at strike K and maturity t.

surface.total_variance(100, t=45 / 365)

float

required

Strike price.

float | str | date | pd.Timestamp

required

Maturity as a year fraction or date-like value within the fitted range.

float

Total variance, defined as implied volatility squared times time to expiry.

implied_vol(K, t)

Return the interpolated implied volatility at strike K and maturity t. surface(K, t) is a callable alias.

surface.implied_vol(100, t=45 / 365)

float

Implied volatility in decimal form.

forward_price(t)

Return the interpolated forward price at maturity t.

surface.forward_price(t=45 / 365)

float

Forward price at the requested maturity.

price(strikes, t, call_or_put)

Calculate theoretical option prices from the fitted surface.

surface.price([95, 100, 105], t=45 / 365, call_or_put="call")

float | Sequence[float] | np.ndarray

required

One or more strike prices.

Literal['call', 'put']

default:"call"

Option type.

np.ndarray

Theoretical option prices.

atm_vol(t)

Return the at-the-money implied volatility at maturity t, where ATM is defined at the forward price.

surface.atm_vol(t=45 / 365)

float

Interpolated ATM implied volatility.

implied_distribution(grid_points, cdf_violation_policy)

Derive a ProbSurface from the fitted volatility surface.

surface.implied_distribution(grid_points=None, cdf_violation_policy="warn")

ProbSurface

Risk-neutral probability surface.

delta, gamma, vega, theta, rho, greeks

Compute Greeks at a strike grid and maturity.

surface.delta(strikes, t=45 / 365, call_or_put="call")
surface.gamma(strikes, t=45 / 365)
surface.vega(strikes, t=45 / 365)
surface.theta(strikes, t=45 / 365, call_or_put="call")
surface.rho(strikes, t=45 / 365, call_or_put="call")
surface.greeks(strikes, t=45 / 365, call_or_put="call")

np.ndarray | pd.DataFrame

Individual Greek methods return arrays. greeks returns a DataFrame with strike, delta, gamma, vega, theta, and rho.

plot, plot_3d, plot_term_structure

Render surface plots.

surface.plot()
surface.plot_3d()
surface.plot_term_structure()

matplotlib.figure.Figure

The rendered Matplotlib figure.

Properties

tuple[pd.Timestamp, ...]

Sorted tuple of fitted pillar expiry timestamps. Returns an empty tuple if fit has not been called.

WarningDiagnostics

Structured diagnostic events accumulated during fitting. Inspect .warning_diagnostics.events for data-quality issues (e.g., stale quotes, price fallbacks), model-risk warnings (butterfly arbitrage), and skipped expiries.

dict[pd.Timestamp, Any]

Fitted parameter dictionary for each expiry pillar.

Example

import numpy as np
from oipd import VolSurface, MarketInputs, sources

# 1. Fetch a multi-expiry option chain
chain, snapshot = sources.fetch_chain("SPY", horizon="6m")

market = MarketInputs(
    risk_free_rate=0.053,
    valuation_date=snapshot.asof,
    underlying_price=snapshot.underlying_price,
)

# 2. Fit the surface
surface = VolSurface(method="svi", pricing_engine="black76")
surface.fit(chain, market, failure_policy="skip_warn")

print("Fitted expiries:", surface.expiries)

# 3. Slice at a fitted pillar
expiry = surface.expiries[0]
curve = surface.slice(expiry)
print("ATM vol:", curve.atm_vol)
print("SVI params:", curve.params)

# 4. Slice at an interpolated maturity between fitted pillars
midpoint = surface.expiries[0] + (surface.expiries[1] - surface.expiries[0]) / 2
interp_curve = surface.slice(midpoint)
print("Interpolated ATM vol:", interp_curve.atm_vol)

# 5. Export long-format IV results (pillar expiries only)
df = surface.iv_results(step_days=None, include_observed=False)
print(df.head())

# 6. Derive the probability surface
prob_surface = surface.implied_distribution()
print("Prob surface expiries:", prob_surface.expiries)

# 7. Review diagnostics
diag = surface.warning_diagnostics
print("Total warning events:", diag.summary.total_events)
for event in diag.events:
    print(event.event_type, event.severity, event.message)

Core objects

Inputs and data

Errors and diagnostics

Constructor

Methods

Properties

Example

​Constructor

​Methods

​Properties

​Example

Constructor

Methods

Properties

Example