abaquant.derivatives.calibration.core¶

Import path: abaquant.derivatives.calibration.core

Domain: Derivative pricing, simulation, calibration, diagnostics, and strategy analysis.

Purpose¶

Object-oriented calibration tools for listed and synthetic option smiles.

When to use it¶

This module fits model parameters to observations. Inspect convergence status, residual scale, bounds, weighting, and data provenance before treating fitted parameters as stable estimates.

Public objects¶

class: CalibrationError — Raised when option-model calibration inputs are incomplete or invalid.
class: CalibrationResult — Fitted option-model calibration result. * CalibrationResult.summary — Return compact fit diagnostics and calibrated parameters. * CalibrationResult.error_table — Return the contract-level market-versus-model residual table. * CalibrationResult.parameter_table — Return calibrated parameters as a two-column table. * CalibrationResult.as_dict — Return a serialization-friendly representation of the calibration result. * CalibrationResult.visualize — Visualize model-versus-market fit quality or calibrated parameters. * CalibrationResult.report — Return an exportable report describing the calibration fit.
class: BSMFlatVolCalibration — Calibrate a single flat Black–Scholes–Merton volatility. * BSMFlatVolCalibration.fit — Fit the flat-volatility model and return a calibration result.
class: SABRSmileCalibration — Calibrate SABR alpha, rho, and nu against a listed volatility smile. * SABRSmileCalibration.fit — Fit SABR smile parameters and return the calibration diagnostics.
class: HestonCalibration — Calibrate Heston parameters against option prices or implied volatilities. * HestonCalibration.fit — Fit Heston stochastic-volatility parameters.

Detailed reference¶

Object-oriented calibration tools for listed and synthetic option smiles.

Purpose¶

The module provides a small, deterministic calibration layer that connects market option-chain observations to advanced option-pricing models. It exposes result objects with fitted parameters, model-versus-market tables, residual statistics, and visualization/export hooks.

Conventions¶

Rates and dividend yields are decimal annual quantities. Maturities are in years. Option premiums and strikes use the same currency units as the underlying spot price. Implied volatilities are annualized decimal volatilities.

Scope and limitations¶

Calibrations are numerical least-squares fits. Results depend on input quality, liquidity filters, initial parameters, and bounds. They are diagnostics, not trading recommendations.

exception abaquant.derivatives.calibration.core.CalibrationError¶

Bases: ValueError

Raised when option-model calibration inputs are incomplete or invalid.

class abaquant.derivatives.calibration.core.CalibrationResult(model_name, parameters, error, success, message, market_data, model_data, objective, option_type, metadata=<factory>, provenance=None)¶

Bases: object

Fitted option-model calibration result.

Parameters:

model_name (str) – Human-readable model identifier, such as "bsm" or "heston".
parameters (Mapping[str, float]) – Calibrated model parameters.
error (float) – Root-mean-square calibration error in the selected objective units.
success (bool) – Whether the numerical optimizer reported success.
message (str) – Solver or workflow message.
market_data (pandas.DataFrame) – Cleaned market observations used in the fit.
model_data (pandas.DataFrame) – Contract-level model values, market values, and residuals.
objective (str) – Objective used during fitting: "price" or "iv".
option_type (str) – Option family used by the fit.
metadata (Mapping[str, object]) – Additional reproducibility metadata such as bounds, maturity, and rate.
provenance (DataProvenance | None)

summary()¶

Return compact fit diagnostics and calibrated parameters.

Return type:: dict[str, object]

error_table()¶

Return the contract-level market-versus-model residual table.

Return type:: DataFrame

parameter_table()¶

Return calibrated parameters as a two-column table.

Return type:: DataFrame

as_dict()¶

Return a serialization-friendly representation of the calibration result.

Return type:: dict[str, object]

visualize(*, chart='model_vs_market', backend=None, theme=None, save_path=None, filename=None)¶

Visualize model-versus-market fit quality or calibrated parameters.

Parameters:

chart ({"model_vs_market", "residuals", "parameters"}, default="model_vs_market") – Calibration diagnostic to render.
backend (str | None) – Standard AbaQuant visualization overrides.
theme (object | None) – Standard AbaQuant visualization overrides.
save_path (str | None) – Standard AbaQuant visualization overrides.
filename (str | None) – Standard AbaQuant visualization overrides.

Returns:

Backend-native figure object.

Return type:

matplotlib.figure.Figure or plotly.graph_objects.Figure

report()¶: Return an exportable report describing the calibration fit.

class abaquant.derivatives.calibration.core.BSMFlatVolCalibration(option_chain, spot_price=None, maturity_years=None, risk_free_rate=0.0, dividend_yield=0.0, option_type='call', objective='price', initial_volatility=0.2, bounds=(0.0001, 5.0), weighting='equal', min_open_interest=None)¶

Bases: object

Calibrate a single flat Black–Scholes–Merton volatility.

Parameters:

option_chain (object) – DataFrame-like option observations, or an object exposing iv_smile(...). Required fields are strike and either market_price or implied_volatility depending on the objective.
spot_price (float | None, default=None) – Current underlying price. Required for price-objective fits unless the chain has a spot_price column.
maturity_years (float | None, default=None) – Time to expiry. Required for price-objective fits unless the chain has a maturity_years column or days_to_expiry column.
risk_free_rate (float, default=0.0) – Continuously compounded annual risk-free rate.
dividend_yield (float, default=0.0) – Continuous annual dividend yield.
option_type ({"call", "put"}, default="call") – Option family used during calibration.
objective ({"price", "iv"}, default="price") – Fit to market premiums or listed implied volatilities.
initial_volatility (float)
bounds (tuple[float, float])
weighting (Literal['equal', 'vega', 'open_interest'])
min_open_interest (float | None)

fit()¶

Fit the flat-volatility model and return a calibration result.

Return type:: CalibrationResult

class abaquant.derivatives.calibration.core.SABRSmileCalibration(option_chain, forward_price=None, spot_price=None, maturity_years=None, risk_free_rate=0.0, dividend_yield=0.0, beta=1.0, option_type='call', initial_parameters=None, bounds=None, weighting='equal', min_open_interest=None, max_iter=500, tol=1e-08)¶

Bases: object

Calibrate SABR alpha, rho, and nu against a listed volatility smile.

Parameters:

option_chain (object) – DataFrame-like option observations, or an object exposing iv_smile(...). The fit requires strike and implied_volatility observations.
forward_price (float | None, default=None) – Forward price at the option maturity. If omitted, the value is inferred from spot_price and carry inputs when possible.
maturity_years (float | None, default=None) – Time to expiry in years.
beta (float, default=1.0) – Fixed SABR elasticity parameter.
spot_price (float | None)
risk_free_rate (float)
dividend_yield (float)
option_type (Literal['call', 'put'])
initial_parameters (Mapping[str, float] | None)
bounds (Mapping[str, tuple[float, float]] | None)
weighting (Literal['equal', 'vega', 'open_interest'])
min_open_interest (float | None)
max_iter (int)
tol (float)

fit()¶

Fit SABR smile parameters and return the calibration diagnostics.

Return type:: CalibrationResult

class abaquant.derivatives.calibration.core.HestonCalibration(option_chain, spot_price=None, maturity_years=None, risk_free_rate=0.0, dividend_yield=0.0, option_type='call', objective='iv', initial_parameters=None, bounds=None, weighting='equal', min_open_interest=None, max_contracts=25, max_iter=250, tol=1e-08)¶

Bases: object

Calibrate Heston parameters against option prices or implied volatilities.

Parameters:

option_chain (object) – DataFrame-like option observations, or an object exposing iv_smile(...). Heston fits require strike, maturity, and either market premium or implied-volatility observations depending on the objective.
initial_parameters (Mapping[str, float] | None, default=None) – Initial values for kappa, theta, xi, rho, and v0.
objective ({"iv", "price"}, default="iv") – Calibration target. "iv" is usually faster and more stable.
spot_price (float | None)
maturity_years (float | None)
risk_free_rate (float)
dividend_yield (float)
option_type (Literal['call', 'put'])
bounds (Mapping[str, tuple[float, float]] | None)
weighting (Literal['equal', 'vega', 'open_interest'])
min_open_interest (float | None)
max_contracts (int | None)
max_iter (int)
tol (float)

fit()¶

Fit Heston stochastic-volatility parameters.

Return type:: CalibrationResult