Module surface 

Volatility-surface traits and typed market-data contracts.

Structs

BidAskInversionError

Error returned by NormalizedSurfaceQuote::bid_ask_iv_bounds when one side of the spread fails to invert. Carries the side that failed so downstream diagnostics can attribute the failure correctly.

BidAskIvBounds

Bid/ask implied-volatility band derived from BidAskPrices.

BidAskPenalty

Tuning for the bid-ask-infeasibility penalty.

BidAskPenaltyRecord

Trace entry for one quote that received a bid-ask-infeasibility penalty during calibration (#154 soft-penalty mode).

BidAskPrices

Raw bid/ask market quote data attached to a normalized surface quote.

ButterflyArbitrageProjection

Per-slice record of a butterfly-arbitrage projection applied by the joint SSVI calibrator’s post-fit cleanup. When g(k) < 0 was detected at one or more strikes on a slice, the projection raises ϕ_T from phi_before to phi_after until min_k g(k) ≥ 0 on the strike grid. max_g_violation_before records the most-negative g(k) observed before the projection (0.0 when no violation existed and the projection was a no-op).

ButterflyArbitrageViolation

Representative butterfly arbitrage violation on one smile slice.

ButterflyViolation

One slice-strike pair at which Gatheral’s butterfly-arbitrage condition g(k) ≥ 0 was violated by the joint SSVI fit. Reported on JointSsviGlobals::butterfly_arbitrage_violations alongside any post-fit projection corrections.

CalendarArbitrageViolation

Representative calendar arbitrage violation across two expiries.

DupireExtractionDiagnostics

Aggregate diagnostics emitted by Dupire grid extraction.

DupireExtractionGrid

Result of extract_dupire_local_volatility_grid.

DupireExtractionPolicy

Numerical policy for extract_dupire_local_volatility and extract_dupire_local_volatility_grid.

DupireLocalVolPoint

One Dupire-extracted local-volatility node and its supporting derivatives.

FeasibilityDrop

One quote dropped by the calibration-time feasibility filter.

HuberLoss

Validated configuration for a Huber loss.

JointSsviCalibrationBounds

Bounds for the joint Gatheral-Jacquier SSVI calibrator. Composes the per-slice SsviCalibrationBounds (carries θ, ρ, φ admissibility) with bounds on the surface-global Gatheral-Jacquier parameters (η, γ) and on the term-structure parameters used by each ThetaTermStructure variant.

JointSsviCalibrationPolicy

Policy for the joint Gatheral-Jacquier SSVI calibrator (calibrate_joint_ssvi_surface).

JointSsviCalibrationPrior

Validated Bayesian-smoothing prior for the joint Gatheral-Jacquier SSVI calibrator. When configured on JointSsviCalibrationPolicy, the calibration objective gains an additive penalty term λ · Σᵢ ((paramᵢ − prior_paramᵢ) / rangeᵢ)² summed over the five jointly optimised parameters: (power_law_a, power_law_b, eta, gamma, rho). Per-axis range comes from the policy’s JointSsviCalibrationBounds.

JointSsviGlobals

Surface-global outputs of the joint Gatheral-Jacquier SSVI calibration. Returned on SurfaceCalibrationReport::joint_ssvi_globals for surfaces produced by calibrate_joint_ssvi_surface; None for per-slice fits.

LocalVolSurfaceGrid

Local-volatility surface evaluated on a tensor (expiry, log_moneyness) grid.

NormalizedSurfaceQuote

Calibration-ready quote data with explicit weighting and provenance.

ParityConsistencyReport

Verdict on whether a chain’s supplied forward agrees with put-call parity.

ParityForwardCurve

A {constant log-offset, borrow/financing rate} decomposition of the per-tenor parity forwards of one underlying.

ParityForwardCurvePoint

One tenor’s input to estimate_parity_forward_curve: the time to expiry in years and the parity forward recovered from that tenor’s pairs.

ParityForwardCurveResidual

Per-tenor residual produced by estimate_parity_forward_curve, one per input ParityForwardCurvePoint in the order supplied.

ParityForwardEstimate

Forward and discount factor recovered from put-call parity.

ParityQuotePair

A call and put price observed at one strike and a common expiry.

SabrCalibrationBounds

Bounds for calibrating SABR slice parameters with fixed beta.

SabrCalibrationPolicy

Policy for calibrating a SABR surface with fixed beta.

SabrCalibrationPrior

Validated Bayesian-smoothing prior for SABR calibration.

SabrParameters

One SABR parameter set under the Hagan 2002 lognormal approximation.

SabrSmile

One SABR smile slice at a specific expiry.

SabrSurface

Discrete-expiry surface backed by SABR smile slices.

SsviCalibrationBounds

Bounds for calibrating SSVI slice parameters.

SsviCalibrationPolicy

Policy for calibrating an SSVI surface.

SsviCalibrationPrior

Validated Bayesian-smoothing prior for SSVI slice calibration.

SsviSlice

One SSVI slice at a specific expiry.

SsviSurface

Discrete-expiry surface backed by SSVI slices.

StaticArbitrageCheckPolicy

Policy controlling tolerance thresholds for static-arbitrage diagnostics.

StaticArbitrageDiagnostics

Richer static-arbitrage diagnostics than the legacy ArbFreeReport.

SurfaceButterflySelection

Butterfly selection and value from one smile.

SurfaceCalibrationInput

End-to-end normalized calibration payload for one option-chain snapshot.

SurfaceCalibrationOutcome

Fitted surface plus its structured calibration report.

SurfaceCalibrationQualityThresholds

Thresholds used to classify calibrated surface fit quality.

SurfaceCalibrationReport

Full report for one calibrated surface.

SurfaceCalibrationResidual

Residual row for one normalized quote in a fitted surface report.

SurfaceCalibrationSearchPolicy

Optimization controls shared by the public surface calibration APIs.

SurfaceCalibrationSummary

Aggregate fit-quality summary for a calibrated surface.

SurfaceCarryInputs

Explicit carry assumptions required to normalize a live chain into calibration-ready surface observations.

SurfaceDeltaCoordinate

Optional delta-space coordinate carried with a normalized quote.

SurfaceDeltaStrike

One delta-grid node paired with its inverted strike.

SurfaceDeltaStrikeSelection

One theoretical delta strike and the nearest listed strike selected for it.

SurfaceDeltaStrikeSelectionRequest

Parameters for selecting a listed strike from a delta target.

SurfaceDeltaWingStrikeSelection

Put/call wing strikes selected from the same absolute delta.

SurfaceLogMoneyness

Log-moneyness coordinate, typically ln(K / F) or ln(F / K) depending on the caller’s convention.

SurfaceMarketContext

Market context shared across a normalized calibration payload.

SurfaceNormalizationOutcome

Normalized calibration payload plus the diagnostics emitted while building it from live chain state.

SurfaceNormalizationPolicy

Policy governing how live quotes are turned into calibration-ready surface observations.

SurfaceNormalizationReport

Structured diagnostics emitted by quote normalization.

SurfacePerTenorForwards

Per-tenor forward overrides applied on top of the spot-plus-carry forward.

SurfaceQualityFilteredOutcome

End-to-end outcome of the quality-filtered prep pipeline.

SurfaceQuoteAdjustment

One retained quote-quality adjustment inside a normalization report.

SurfaceQuoteCoordinate

Strike-space coordinate for one normalized surface quote.

SurfaceQuoteObservation

Market observation attached to one normalized surface quote.

SurfaceQuoteProvenance

Provenance attached to one normalized surface quote.

SurfaceQuoteQuality

Live-feed anomaly flags attached to a normalized quote.

SurfaceQuoteQualityPolicy

Quality gates applied to raw chain quotes before normalization.

SurfaceQuoteQualityRejection

One contract dropped by the quality filter, with metadata for debugging.

SurfaceQuoteQualityReport

Full diagnostic report from one quality-filter pass.

SurfaceQuoteQualitySummary

Compact diagnostic counters from one quality-filter pass.

SurfaceQuoteTreatment

Quote-quality treatment used for crossed, locked, and stale markets.

SurfaceQuoteWeight

Weight decomposition attached to one normalized quote.

SurfaceRejectedQuote

One quote rejected from the normalized calibration payload.

SurfaceRepairAdjustment

Final adjustment applied to one representative (expiry, strike) node.

SurfaceRepairInputOutcome

Repaired normalized input plus the explicit repair report that produced it.

SurfaceRepairOutcome

Family-specific post-fit repair result with repaired nodes and recalibration.

SurfaceRepairPolicy

Deterministic repair controls for explicit post-fit smoothing workflows.

SurfaceRepairReport

Structured report for one explicit repair pass over normalized surface data.

SurfaceRepairSummary

Aggregate summary of an explicit surface repair pass.

SurfaceRiskReversalSelection

Risk-reversal selection and value from one smile.

SurfaceSelectedSmilePoint

One validated (strike, implied volatility) smile point.

SurfaceSelectionQuotePolicy

Policy for consuming normalized quotes in strike-selection helpers.

SurfaceSliceCalibrationReport

Slice-level summary row for a fitted surface.

SurfaceSmileAmericanDeltaStrikeSelectionRequest

Validated request for selecting a listed strike at a target absolute delta using actual American model delta and smile-sourced implied volatility.

SurfaceSmileDeltaSelectionPolicy

Tunable convergence policy for smile-aware delta-target strike selection.

SurfaceSmileDeltaStrikeSelectionRequest

Validated request for selecting a listed strike at a target absolute delta against a calibrated smile.

SurfaceSmileRiskMetrics

Standard smile-metrics bundle: ATM IV plus 25-delta and 10-delta risk reversals (each carrying its own butterfly via SurfaceSmileRiskReversal::butterfly).

SurfaceSmileRiskReversal

Smile-based risk reversal with companion butterfly and ATM IV.

SurfaceSmileRiskReversalWing

One side of a smile-based risk reversal: both wing strikes plus the smile IV evaluated at the theoretical strike.

SurfaceTenor

Surface expiry represented in years.

SurfaceWingSmileSelection

ATM and wing points selected from one smile.

SviCalibrationPolicy

Policy for calibrating an SVI surface.

SviCalibrationPrior

Validated Bayesian-smoothing prior for raw-SVI calibration.

SviNaturalCalibrationBounds

Bounds for calibrating natural SVI parameters.

SviNaturalParameters

Natural SVI parameterization.

SviRawCalibrationBounds

Bounds for calibrating raw SVI parameters.

SviRawParameters

Raw SVI parameterization.

SviSmile

One SVI smile slice at a specific expiry.

SviSurface

Discrete-expiry surface backed by SVI smile slices.

TrimmedMseLoss

Validated configuration for a trimmed-MSE loss.

Enums

AcceptableReason

Specific reason a calibrated fit was classified as FitQuality::Acceptable.

BidOrAsk

Which side of a bid/ask spread an operation refers to.

DegeneracyReason

Specific degeneracy detected on an otherwise successful calibration.

FailureReason

Specific failure mode for a calibration report.

FeasibilityDropReason

Reason an individual quote was hard-dropped by the bid-ask-feasibility filter (#154).

FeasibilityPolicy

Bid-ask-feasibility configuration applied during surface calibration.

FeasibilityWarning

Non-fatal warning produced by the bid-ask-feasibility filter while preparing the calibration (#154).

FitQuality

Overall trust classification for a calibrated surface fit.

LossFunction

Loss function used to aggregate per-quote residuals during surface calibration.

MoneynessWindow

Per-expiry moneyness-window gate.

SurfaceCalibrationModel

Fitted model family recorded in a calibration report. Joint Gatheral-Jacquier surfaces produced by calibrate_joint_ssvi_surface are tagged as SurfaceCalibrationModel::Ssvi (same surface family); consumers distinguish them from per-slice fits by inspecting SurfaceCalibrationReport::joint_ssvi_globals for Some(_) — keeping this enum exhaustive and SemVer-stable.

SurfaceCalibrationObjectiveSpace

Residual space used to compare market and model quotes during surface calibration.

SurfaceDeltaConvention

Delta convention carried alongside a delta-space coordinate.

SurfaceNormalizationAdjustmentReason

Adjustment reason recorded when normalization retains a quote but reduces its quality weight.

SurfaceNormalizationRejectReason

Reject reason recorded in the normalization report when one live quote is dropped from the calibration payload.

SurfacePriceSource

Source used to derive the normalized reference price.

SurfaceQuoteQualityRejectReason

Reasons a chain contract is dropped by the quality filter.

SurfaceQuoteTreatmentKind

Quality-treatment kind applied to a normalized quote.

SurfaceReferencePricePolicy

Reference-price selection policy used during quote normalization.

SurfaceRepairAdjustmentReason

Why one surface node was adjusted during an explicit repair workflow.

SurfaceSliceCalibrationParameters

Slice-level fitted parameter payload attached to a calibration report.

SurfaceSmileRiskReversalWingQuality

Whether a wing’s evaluation point fell inside the listed-strikes support on that wing.

SviCalibrationParameterization

Which SVI parameterization to fit during calibration.

ThetaTermStructure

Parameterisation of the ATM total-variance term-structure θ(T) used by the joint Gatheral-Jacquier SSVI calibrator. Each variant determines both the closed-form / small-search Pass-1 fit of θ(T) and the post-fit extrapolation of θ(T) outside the anchor tenor range.

ThetaTermStructureParams

Parametric payload for a fitted crate::ThetaTermStructure. Carried on JointSsviGlobals::theta_term_structure_params; the variant matches the one configured on crate::JointSsviCalibrationPolicy.

Constants

DEFAULT_FORWARD_PARITY_RELATIVE_TOLERANCE

Suggested relative tolerance for check_forward_parity: a supplied forward within 10 bp of the parity forward is treated as consistent.

DEFAULT_PARITY_MONEYNESS_WINDOW

Suggested half-width of the near-ATM log-moneyness window for select_near_atm_parity_pairs: ±0.05, roughly ±5% in strike.

SMILE_DELTA_DEFAULT_BRACKET_EXPANSIONS

Default cap on doubling / halving expansions used to bracket the delta-target objective in the American smile-delta path.

SMILE_DELTA_DEFAULT_MAX_ITERATIONS

Default cap on smile-aware delta-target fixed-point iterations (European path) and on bisection iterations (American path).

SMILE_DELTA_DEFAULT_OBJECTIVE_TOLERANCE

Default absolute tolerance on the absolute-delta residual used by the American smile-delta seed early-exit and bisection convergence checks.

SMILE_DELTA_DEFAULT_RELATIVE_TOLERANCE

Default convergence tolerance on (next_strike - prev_strike).abs() / max(forward.abs(), 1.0) between successive smile-aware delta-target iterations.

Traits

SurfaceSmile

Trait for querying a single-expiry implied-volatility smile slice.

VolSurface

Trait for querying an implied-volatility surface.

Functions

calibrate_joint_ssvi_surface

Calibrate an SSVI surface jointly across all expiry slices (Gatheral-Jacquier 2014).

calibrate_sabr_surface

Calibrate a SABR surface from normalized market quotes.

calibrate_ssvi_surface

Calibrate an SSVI surface from normalized market quotes.

calibrate_svi_surface

Calibrate an SVI surface from normalized market quotes.

check_forward_parity

Check a supplied forward against the put-call-parity forward of the chain.

diagnose_static_arbitrage

Diagnose representative static-arbitrage violations using the default tolerances.

diagnose_static_arbitrage_with_policy

Diagnose representative static-arbitrage violations using an explicit tolerance policy.

estimate_parity_forward

Recover the forward and discount factor from put-call parity.

estimate_parity_forward_curve

Fit a {constant log-offset, borrow/financing rate} curve across per-tenor parity forwards.

extract_dupire_local_volatility

Extract one Dupire local-volatility node at (expiry, strike).

extract_dupire_local_volatility_grid

Extract Dupire local volatility on a tensor grid of (expiry, log_moneyness) nodes.

normalize_chain_for_surface

Normalize the live chain into calibration-ready surface quotes.

normalize_chain_for_surface_with_forward_overrides

Normalize the live chain with explicit per-tenor forward overrides applied to the shared market context.

prepare_calibration_input_with_quality_policy

Apply the quality policy to a raw chain, then normalize the survivors into a calibration-ready SurfaceCalibrationInput.

prepare_calibration_input_with_quality_policy_and_forward_overrides

Like prepare_calibration_input_with_quality_policy, but with per-tenor forward overrides applied to the shared market context.

repair_sabr_surface

Sample a calibrated SABR surface, repair the sampled nodes explicitly, and re-fit a SABR surface from the repaired payload.

repair_ssvi_surface

Sample a calibrated SSVI surface, repair the sampled nodes explicitly, and re-fit an SSVI surface from the repaired payload.

repair_surface_input

Repair representative surface nodes explicitly and return a new normalized calibration payload plus a structured repair report.

repair_svi_surface

Sample a calibrated SVI surface, repair the sampled nodes explicitly, and re-fit an SVI surface from the repaired payload.

select_near_atm_parity_pairs

Keep only the pairs whose strike sits within max_abs_log_moneyness of reference_forward — i.e. |ln(K / reference_forward)| <= max_abs_log_moneyness.

surface_butterfly_from_normalized_quotes

Select a butterfly from normalized quotes.

surface_butterfly_from_smile

Select a butterfly from one smile.

surface_delta_from_strike

Compute an absolute delta coordinate for a strike.

surface_delta_grid

Build a sorted, deduplicated absolute-delta coordinate grid.

surface_nearest_strike

Select the listed strike nearest to a target, with lower-strike tie-breaks.

surface_raw_interpolated_skew

Non-parametric short-DTE risk reversal, butterfly, and ATM IV from raw quotes.

surface_risk_reversal_from_normalized_quotes

Select a risk reversal from normalized quotes.

surface_risk_reversal_from_smile

Select a risk reversal from one smile.

surface_select_delta_strike

Select the nearest listed strike to a theoretical delta strike.

surface_select_delta_wing_strikes

Select put and call listed wing strikes from one absolute delta.

surface_select_smile_american_delta_strike

Select one listed strike at a target absolute delta using actual American model delta and a calibrated smile for strike-local implied volatility.

surface_select_smile_american_delta_wing_strikes

Select put and call listed wing strikes at one absolute delta using actual American model delta and smile-sourced implied volatility.

surface_select_smile_delta_strike

Select one listed strike at a target absolute delta using a calibrated smile to source the implied volatility consistent with each iterate.

surface_select_smile_delta_wing_strikes

Select put and call listed wing strikes at one absolute delta using a calibrated smile for the implied volatility at each iterate.

surface_select_wing_normalized_quotes

Select ATM and symmetric wings from normalized quotes.

surface_select_wing_smile_points

Select ATM and symmetric listed wings from one smile.

surface_signed_delta_from_strike

Compute signed delta for a strike under a supported surface convention.

surface_smile_iv_at_delta

Look up smile-implied IV at a single delta target on one wing.

surface_smile_risk_metrics

Compute the standard smile-metrics bundle: ATM IV, RR25, RR10, fly25, fly10 in one call.

surface_smile_risk_reversal

Compute a smile-based risk reversal, butterfly, and ATM IV in one call.

surface_strike_from_delta

Invert an absolute delta coordinate into a strike.

surface_strike_grid_from_deltas

Build a sorted delta grid and invert each coordinate to a strike.