The finance developer workbenchSearch the reference Development · 0.1.4 · unpublished

Public API / @insiderfinance/totalfinance

@insiderfinance/totalfinance/volatility/surface

import from '@insiderfinance/totalfinance/volatility/surface'

Every public export in this entry point, including type-only declarations. Search by name or concept.

Jump to an export (14)

SURFACE_MARKET_KEYS · SURFACE_SCHEMA_VERSION · SurfaceConfig · SurfaceLookup · SurfaceMarket · SurfaceModel · SurfacePoint · SurfaceRow · SurfaceShock · SurfaceSlice · VolatilitySurface · VolatilitySurfaceInput · VolatilitySurfaceSnapshot · volatilitySurface

value

SURFACE_MARKET_KEYS

The documented {@link SurfaceMarket} fields (the {@link MarketInputs} keys, `spot` optional).

export declare const SURFACE_MARKET_KEYS: readonly ['spot', 'riskFreeRate', 'dividendYield', 'asOf'];
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

value

SURFACE_SCHEMA_VERSION

Schema version stamped onto every {@link VolatilitySurface#toJSON } snapshot; checked on restore (WS4.4).

export declare const SURFACE_SCHEMA_VERSION: '1';
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfaceConfig

Non-market surface configuration: price source, model, and per-model calibration knobs (WS3.2).

/** Non-market surface configuration: price source, model, and per-model calibration knobs (WS3.2). */
export interface SurfaceConfig {
    /** Which quote price to invert when a quote has no `impliedVolatility` (default `mid`). */
    priceSource?: PriceSource;
    /**
     * `interpolated` (PCHIP, default), `raw` (linear), `smoothed` (Gaussian kernel), `svi`/`sabr`
     * (parametric per expiry), `ssvi` (one global arbitrage-free surface SVI), `essvi` (SSVI with a
     * per-maturity skew), or `heston` (one global stochastic-vol model fit to the whole surface).
     */
    model?: SurfaceModel;
    /** Below this many usable strikes, an expiry slice is flagged sparse (default 3). */
    minQuotesPerExpiry?: number;
    /** SABR backbone exponent β ∈ [0, 1] for `model: 'sabr'` (default 0.5). */
    sabrBeta?: number;
    /** SABR Hagan expansion for `model: 'sabr'` (default `'lognormal'`). */
    sabrVolatilityType?: SabrVolatilityType;
    /** Gaussian-kernel bandwidth (in log-moneyness) for `model: 'smoothed'` (default auto). */
    smoothingBandwidth?: number;
    /** Warm start (partial pin) for the global `model: 'heston'` calibration — threads into `calibrateHestonSurface`'s `initialParameters`. */
    hestonInitialParameters?: Partial<HestonParameters>;
    /** COS cosine-term count for the `model: 'heston'` calibration & evaluation (default 128). */
    cosineExpansionTerms?: number;
    /** Curvature family for the global `model: 'ssvi'` calibration (default `'power-law'`). */
    ssviPhi?: 'power-law' | 'heston';
    /** Least-squares weighting for `model: 'ssvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant). */
    ssviWeight?: 'uniform' | 'vega';
    /** Curvature family for the global `model: 'essvi'` calibration (default `'power-law'`). */
    essviPhi?: 'power-law' | 'heston';
    /** Least-squares weighting for `model: 'essvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant). */
    essviWeight?: 'uniform' | 'vega';
}
Fields, parameters & returned members (17)
Name / typeMeaning & unitOptional / default
cosineExpansionTerms
number		COS cosine-term count for the `model: 'heston'` calibration & evaluation (default 128).
unitless by name		Optional
No @default declared; consult the signature and description.
essviPhi
'power-law' | 'heston'		Curvature family for the global `model: 'essvi'` calibration (default `'power-law'`).
unitless by name		Optional
No @default declared; consult the signature and description.
essviWeight
'vega' | 'uniform'		Least-squares weighting for `model: 'essvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant).
decimal fraction / multiple		Optional
No @default declared; consult the signature and description.
hestonInitialParameters
Partial<HestonParameters>		Warm start (partial pin) for the global `model: 'heston'` calibration — threads into `calibrateHestonSurface`'s `initialParameters`.
unitless by name		Optional
No @default declared; consult the signature and description.
hestonInitialParameters.kappa
number		Mean-reversion speed κ.
unitless by name		Optional
No @default declared; consult the signature and description.
hestonInitialParameters.rho
number		Spot/variance correlation ρ ∈ [−1, 1].
unitless by name		Optional
No @default declared; consult the signature and description.
hestonInitialParameters.sigma
number		Volatility of variance ξ ("vol of vol").
unitless by name		Optional
No @default declared; consult the signature and description.
hestonInitialParameters.theta
number		Long-run variance θ.
unitless by name		Optional
No @default declared; consult the signature and description.
hestonInitialParameters.v0
number		Initial instantaneous variance v₀ (= σ₀²).
unitless by name		Optional
No @default declared; consult the signature and description.
minQuotesPerExpiry
number		Below this many usable strikes, an expiry slice is flagged sparse (default 3).
unitless by name		Optional
No @default declared; consult the signature and description.
model
SurfaceModel		`interpolated` (PCHIP, default), `raw` (linear), `smoothed` (Gaussian kernel), `svi`/`sabr` (parametric per expiry), `ssvi` (one global arbitrage-free surface SVI), `essvi` (SSVI with a per-maturity skew), or `heston` (one global stochastic-vol model fit to the whole surface).
unitless by name		Optional
No @default declared; consult the signature and description.
priceSource
PriceSource		Which quote price to invert when a quote has no `impliedVolatility` (default `mid`).
unitless by name		Optional
No @default declared; consult the signature and description.
sabrBeta
number		SABR backbone exponent β ∈ [0, 1] for `model: 'sabr'` (default 0.5).
unitless by name		Optional
No @default declared; consult the signature and description.
sabrVolatilityType
SabrVolatilityType		SABR Hagan expansion for `model: 'sabr'` (default `'lognormal'`).
unitless by name		Optional
No @default declared; consult the signature and description.
smoothingBandwidth
number		Gaussian-kernel bandwidth (in log-moneyness) for `model: 'smoothed'` (default auto).
unitless by name		Optional
No @default declared; consult the signature and description.
ssviPhi
'power-law' | 'heston'		Curvature family for the global `model: 'ssvi'` calibration (default `'power-law'`).
unitless by name		Optional
No @default declared; consult the signature and description.
ssviWeight
'vega' | 'uniform'		Least-squares weighting for `model: 'ssvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant).
decimal fraction / multiple		Optional
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfaceLookup

Result of a surface lookup: the IV plus whether the query was extrapolated.

/** Result of a surface lookup: the IV plus whether the query was extrapolated. */
export interface SurfaceLookup extends Computed<number> {
    extrapolated: boolean;
}
Fields, parameters & returned members (48)
Name / typeMeaning & unitOptional / default
assumptions
Assumptions<Record<never, never>>		Every applied convention, echoed back.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.asOf
number
an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)		Optional
No @default declared; consult the signature and description.
assumptions.calendar
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.calendarVersion
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.compounding
import('@insiderfinance/totalfinance/core').InterestCompounding
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.compounding.periodsPerYear
number
per year (count)		Required / declared member
No @default declared; consult the signature and description.
assumptions.compounding.type
'periodic'
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.conventionsVersion
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.dayCount
import('@insiderfinance/totalfinance/core').DayCount
count (integer)		Optional
No @default declared; consult the signature and description.
assumptions.dividendModel
import('@insiderfinance/totalfinance/core').DividendModel
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.engine
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.expiryConvention
'us-equity-close' | 'explicit-instant'		How the contract's expiry label was resolved to an instant: `'us-equity-close'` when a date-only `YYYY-MM-DD` expiry resolved to the US equity/options close — 16:00 America/New_York, or 13:00 on an early-close day; `'explicit-instant'` when the caller supplied a zoned datetime. Named so the convention is never silent (alignment spec P1.6); instrument builders own the full story in Phase 3.
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.model
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.seed
number		The randomness seed this result was computed under — REQUIRED echo for a `randomness: 'seeded'` Pricer (Gate C, 2026-08-23): a stochastic result that does not name its seed cannot be replayed from the result alone. Deterministic paths never set it.
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.timeToExpiryConvention
never
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.timeToExpiryYears
number
years (decimal)		Optional
No @default declared; consult the signature and description.
assumptions.units
import('@insiderfinance/totalfinance/core').GreekUnits
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.units.rho
import('@insiderfinance/totalfinance/core').RhoUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.units.theta
import('@insiderfinance/totalfinance/core').ThetaUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.units.vega
import('@insiderfinance/totalfinance/core').VegaUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics
Diagnostics		How the value was computed, plus any warnings.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.autoReason
string		When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.converged
boolean		Whether an iterative procedure converged. `false` means the value is not trustworthy.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.decomposition
Record<string, number>		Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3).
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.engine
string		Pricing/solver engine name, e.g. `black-scholes-merton`.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.finiteDifferenceBumps
Record<string, number>		Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.)
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.iterations
number		Iteration count for iterative methods.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.method
string		Numerical method, e.g. `closed-form`, `brent`, `finite-difference`.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection
import('@insiderfinance/totalfinance/core/pricing').SelectionReport		The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection.candidates
readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]		Candidates an automatic selection considered; absent for explicit mode.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection.mode
'explicit' | 'automatic'
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.reason
string		Why the selected engine answers this request.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected
{ name: string; version?: string; }
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected.name
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected.version
string
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.timingMs
number		Wall-clock timing in milliseconds, when measured.
milliseconds		Optional
No @default declared; consult the signature and description.
diagnostics.warmup
number		Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.warnings
QuantWarning[]		Structured warnings; always present (possibly empty).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
extrapolated
boolean
unitless by name		Required / declared member
No @default declared; consult the signature and description.
provenance
import('@insiderfinance/totalfinance/core').Provenance		Optional data lineage when the inputs came from a provider.
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.asOf
number
an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)		Optional
No @default declared; consult the signature and description.
provenance.dataset
string
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.provider
string
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.receivedAt
number
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.requestId
string
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.sourceVersion
string
unitless by name		Optional
No @default declared; consult the signature and description.
provenance.warnings
QuantWarning[]
unitless by name		Optional
No @default declared; consult the signature and description.
value
number		The computed value. Never `NaN` or `±Infinity`: a value the model cannot produce is `null` beside a diagnostic that says why (Law 7 — a warning never licenses a non-finite number).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

type

SurfaceMarket

Market snapshot for `volatilitySurface()` — the workspace-canonical {@link MarketInputs}, except `spot` is optional (it falls back to each quote's `underlyingPrice` when omitted) (WS3.2).

/**
 * Market snapshot for `volatilitySurface()` — the workspace-canonical {@link MarketInputs}, except `spot` is
 * optional (it falls back to each quote's `underlyingPrice` when omitted) (WS3.2).
 */
export type SurfaceMarket = Omit<MarketInputs, 'spot'> & {
    /** Spot price. Falls back to each quote's `underlyingPrice` when omitted. */
    spot?: number;
};
Fields, parameters & returned members (4)
Name / typeMeaning & unitOptional / default
asOf
string | number		Snapshot time: epoch ms, `'YYYY-MM-DD'`, or a ZONED ISO datetime — one grammar for "when" across every package. Each boundary resolves it once via core `resolveAsOf` (zone-less datetimes are rejected with a teaching error; TotalFinance never reads the machine clock or zone).
an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)		Required / declared member
No @default declared; consult the signature and description.
dividendYield
number		Continuous dividend yield; defaults to 0 when omitted.
decimal rate (0.05 = 5%)		Optional
No @default declared; consult the signature and description.
riskFreeRate
number
decimal rate (0.05 = 5%)		Required / declared member
No @default declared; consult the signature and description.
spot
number		Spot price. Falls back to each quote's `underlyingPrice` when omitted.
unitless by name		Optional
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

type

SurfaceModel

`raw`/`interpolated`/`smoothed` are non-parametric (linear, PCHIP, and a Gaussian-kernel smoother); `svi`/`sabr` fit a parametric smile per expiry; `heston` calibrates one global stochastic-vol model to the whole surface. Parametric models fall back to an interpolated smile for expiries with too few strikes. (Dupire local-volatility *surface fitting* is sequenced later — spec §10.1.)

/**
 * `raw`/`interpolated`/`smoothed` are non-parametric (linear, PCHIP, and a Gaussian-kernel smoother);
 * `svi`/`sabr` fit a parametric smile per expiry; `heston` calibrates one global stochastic-vol model
 * to the whole surface. Parametric models fall back to an interpolated smile for expiries with too few
 * strikes. (Dupire local-volatility *surface fitting* is sequenced later — spec §10.1.)
 */
export type SurfaceModel = 'raw' | 'interpolated' | 'smoothed' | 'svi' | 'sabr' | 'ssvi' | 'essvi' | 'heston';
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfacePoint

A raw solved surface point before smoothing.

/** A raw solved surface point before smoothing. */
export interface SurfacePoint {
    expiry: string;
    strike: number;
    type: OptionType;
    timeToExpiryYears: number;
    impliedVolatility: number;
}
Fields, parameters & returned members (5)
Name / typeMeaning & unitOptional / default
expiry
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
impliedVolatility
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
strike
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
timeToExpiryYears
number
years (decimal)		Required / declared member
No @default declared; consult the signature and description.
type
OptionType
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfaceRow

One chart-facing row from {@link VolatilitySurface#toRows } — the smile-chart / heatmap feed. Per the workspace missing-value policy (WS2.12), every chart-facing numeric is `number | null`: a non-finite stored value becomes `null`, never `NaN` and never omitted.

/**
 * One chart-facing row from {@link VolatilitySurface#toRows} — the smile-chart / heatmap feed. Per the
 * workspace missing-value policy (WS2.12), every chart-facing numeric is `number | null`: a non-finite
 * stored value becomes `null`, never `NaN` and never omitted.
 */
export interface SurfaceRow {
    expiry: string;
    strike: number;
    /** `ln(strike/forward)`, or `null` if non-finite. */
    logMoneyness: number | null;
    /** Stored call-delta at the strike, or `null` if the stored value is non-finite. */
    delta: number | null;
    /** Stored implied vol at the strike, or `null` if the stored value is non-finite. */
    impliedVolatility: number | null;
}
Fields, parameters & returned members (5)
Name / typeMeaning & unitOptional / default
delta
number | null		Stored call-delta at the strike, or `null` if the stored value is non-finite.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
expiry
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
impliedVolatility
number | null		Stored implied vol at the strike, or `null` if the stored value is non-finite.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
logMoneyness
number | null		`ln(strike/forward)`, or `null` if non-finite.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
strike
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfaceShock

A vol-structure shock echoed in a shocked surface's {@link VolatilitySurface.assumptions} (WS4.4).

/** A vol-structure shock echoed in a shocked surface's {@link VolatilitySurface.assumptions} (WS4.4). */
export interface SurfaceShock {
    /** Additive parallel shift applied to every stored IV (in vol points, e.g. `0.02` = +2 vol). */
    parallel: number;
    /** Skew rotation: adds `skewTilt · k` where `k = ln(K/forward)` (log-moneyness). */
    skewTilt: number;
    /** Which quantity the tilt is pinned to: `'strike'` (default) or `'moneyness'`. */
    sticky: 'strike' | 'moneyness';
}
Fields, parameters & returned members (3)
Name / typeMeaning & unitOptional / default
parallel
number		Additive parallel shift applied to every stored IV (in vol points, e.g. `0.02` = +2 vol).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
skewTilt
number		Skew rotation: adds `skewTilt · k` where `k = ln(K/forward)` (log-moneyness).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
sticky
'strike' | 'moneyness'		Which quantity the tilt is pinned to: `'strike'` (default) or `'moneyness'`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

SurfaceSlice

One per-expiry smile, strikes ascending.

/** One per-expiry smile, strikes ascending. */
export interface SurfaceSlice {
    expiry: string;
    /** Time to expiry in years (ACT/365F). */
    timeToExpiryYears: number;
    /** Forward `S·e^{(r−q)t}`. */
    forward: number;
    strikes: number[];
    impliedVolatilities: number[];
    /** Call-delta `e^{−qt}·N(d1)` at each strike (the smile's delta axis, for skew lookups). */
    deltas: number[];
    /** Fitted raw-SVI parameters when `model: 'svi'` (absent if the slice fell back to interpolation). */
    svi?: SVIParameters;
    /** Fitted SABR parameters when `model: 'sabr'` (absent if the slice fell back to interpolation). */
    sabr?: SabrParameters;
    /** The globally-calibrated SSVI parameters when `model: 'ssvi'` (shared across all slices). */
    ssvi?: SSVIParameters;
    /** The globally-calibrated eSSVI parameters when `model: 'essvi'` (shared across all slices). */
    essvi?: ESSVIParameters;
    /** The globally-calibrated Heston parameters when `model: 'heston'` (shared across all slices). */
    heston?: HestonParameters;
}
Fields, parameters & returned members (38)
Name / typeMeaning & unitOptional / default
deltas
number[]		Call-delta `e^{−qt}·N(d1)` at each strike (the smile's delta axis, for skew lookups).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi
ESSVIParameters		The globally-calibrated eSSVI parameters when `model: 'essvi'` (shared across all slices).
unitless by name		Optional
No @default declared; consult the signature and description.
essvi.phi
import('@insiderfinance/totalfinance/volatility').SSVIPhi		Curvature function (global), same family as SSVI.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.eta
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.gamma
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.kind
('heston') | ('power-law')
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.lambda
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.thetaTerm
{ timeToExpiryYears: number; theta: number; rho: number; }[]		Per-knot `(t, θ, ρ)`: θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
expiry
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
forward
number		Forward `S·e^{(r−q)t}`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston
HestonParameters		The globally-calibrated Heston parameters when `model: 'heston'` (shared across all slices).
unitless by name		Optional
No @default declared; consult the signature and description.
heston.kappa
number		Mean-reversion speed κ.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.rho
number		Spot/variance correlation ρ ∈ [−1, 1].
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.sigma
number		Volatility of variance ξ ("vol of vol").
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.theta
number		Long-run variance θ.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.v0
number		Initial instantaneous variance v₀ (= σ₀²).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
impliedVolatilities
number[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
sabr
SabrParameters		Fitted SABR parameters when `model: 'sabr'` (absent if the slice fell back to interpolation).
unitless by name		Optional
No @default declared; consult the signature and description.
sabr.alpha
number		Initial volatility level α (> 0).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
sabr.beta
number		Backbone exponent β ∈ [0, 1].
unitless by name		Required / declared member
No @default declared; consult the signature and description.
sabr.nu
number		Volatility of volatility ν (≥ 0).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
sabr.rho
number		Correlation ρ ∈ (−1, 1).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi
SSVIParameters		The globally-calibrated SSVI parameters when `model: 'ssvi'` (shared across all slices).
unitless by name		Optional
No @default declared; consult the signature and description.
ssvi.phi
import('@insiderfinance/totalfinance/volatility').SSVIPhi		Curvature function.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.eta
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.gamma
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.kind
('heston') | ('power-law')
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.lambda
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.rho
number		Global skew `ρ ∈ (−1, 1)`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.thetaTerm
{ timeToExpiryYears: number; theta: number; }[]		ATM total-variance knots `(t, θ)`, strictly increasing in both (calendar-arbitrage-free).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
strikes
number[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
svi
SVIParameters		Fitted raw-SVI parameters when `model: 'svi'` (absent if the slice fell back to interpolation).
unitless by name		Optional
No @default declared; consult the signature and description.
svi.a
number		Vertical level (minimum total variance is `a + b·σ·√(1−ρ²)`).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
svi.b
number		Wing slope / curvature, `≥ 0`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
svi.m
number		Horizontal shift (log-moneyness of the smile's centre).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
svi.rho
number		Skew / rotation, `∈ [−1, 1]`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
svi.sigma
number		Smoothness, `> 0`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
timeToExpiryYears
number		Time to expiry in years (ACT/365F).
years (decimal)		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

class

VolatilitySurface

A fitted implied-volatility surface with diagnostics-bearing lookup.

export declare class VolatilitySurface {
  constructor(input: VolatilitySurfaceInput);
  static fromJSON(snapshot: VolatilitySurfaceSnapshot): VolatilitySurface;
  arbitrage(options?: ArbitrageCheckOptions): ArbitrageReport;
  readonly assumptions: Assumptions<{ shock?: SurfaceShock; }>;
  readonly diagnostics: Diagnostics;
  readonly essvi?: ESSVIParameters;
  expiries(): string[];
  readonly heston?: HestonParameters;
  impliedVolatility(strike: number, expiry: string | number): number;
  impliedVolatilityByDelta(callDelta: number, expiry: string | number): number;
  impliedVolatilityByMoneyness(moneyness: number, expiry: string | number, options?: { forward?: boolean; }): number;
  lookup(strike: number, expiry: string | number): SurfaceLookup;
  readonly model: SurfaceModel;
  readonly points: SurfacePoint[];
  shock(shifts: { parallel?: number; skewTilt?: number; }, { sticky }?: { sticky?: 'strike' | 'moneyness'; }): VolatilitySurface;
  slice(expiry: string | number): SurfaceSlice | undefined;
  readonly slices: SurfaceSlice[];
  readonly ssvi?: SSVIParameters;
  toJSON(): VolatilitySurfaceSnapshot;
  toRows(): SurfaceRow[];
}
Fields, parameters & returned members (201)

This large namespace is split into complete field pages. No fields are omitted.

Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

VolatilitySurfaceInput

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface VolatilitySurfaceInput {
    quotes: OptionQuote[];
    market: SurfaceMarket;
    config?: SurfaceConfig;
}
Fields, parameters & returned members (24)
Name / typeMeaning & unitOptional / default
config
SurfaceConfig
unitless by name		Optional
No @default declared; consult the signature and description.
config.cosineExpansionTerms
number		COS cosine-term count for the `model: 'heston'` calibration & evaluation (default 128).
unitless by name		Optional
No @default declared; consult the signature and description.
config.essviPhi
'power-law' | 'heston'		Curvature family for the global `model: 'essvi'` calibration (default `'power-law'`).
unitless by name		Optional
No @default declared; consult the signature and description.
config.essviWeight
'vega' | 'uniform'		Least-squares weighting for `model: 'essvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant).
decimal fraction / multiple		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters
Partial<HestonParameters>		Warm start (partial pin) for the global `model: 'heston'` calibration — threads into `calibrateHestonSurface`'s `initialParameters`.
unitless by name		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters.kappa
number		Mean-reversion speed κ.
unitless by name		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters.rho
number		Spot/variance correlation ρ ∈ [−1, 1].
unitless by name		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters.sigma
number		Volatility of variance ξ ("vol of vol").
unitless by name		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters.theta
number		Long-run variance θ.
unitless by name		Optional
No @default declared; consult the signature and description.
config.hestonInitialParameters.v0
number		Initial instantaneous variance v₀ (= σ₀²).
unitless by name		Optional
No @default declared; consult the signature and description.
config.minQuotesPerExpiry
number		Below this many usable strikes, an expiry slice is flagged sparse (default 3).
unitless by name		Optional
No @default declared; consult the signature and description.
config.model
SurfaceModel		`interpolated` (PCHIP, default), `raw` (linear), `smoothed` (Gaussian kernel), `svi`/`sabr` (parametric per expiry), `ssvi` (one global arbitrage-free surface SVI), `essvi` (SSVI with a per-maturity skew), or `heston` (one global stochastic-vol model fit to the whole surface).
unitless by name		Optional
No @default declared; consult the signature and description.
config.priceSource
PriceSource		Which quote price to invert when a quote has no `impliedVolatility` (default `mid`).
unitless by name		Optional
No @default declared; consult the signature and description.
config.sabrBeta
number		SABR backbone exponent β ∈ [0, 1] for `model: 'sabr'` (default 0.5).
unitless by name		Optional
No @default declared; consult the signature and description.
config.sabrVolatilityType
SabrVolatilityType		SABR Hagan expansion for `model: 'sabr'` (default `'lognormal'`).
unitless by name		Optional
No @default declared; consult the signature and description.
config.smoothingBandwidth
number		Gaussian-kernel bandwidth (in log-moneyness) for `model: 'smoothed'` (default auto).
unitless by name		Optional
No @default declared; consult the signature and description.
config.ssviPhi
'power-law' | 'heston'		Curvature family for the global `model: 'ssvi'` calibration (default `'power-law'`).
unitless by name		Optional
No @default declared; consult the signature and description.
config.ssviWeight
'vega' | 'uniform'		Least-squares weighting for `model: 'ssvi'`: `'uniform'` (default) or `'vega'` (ATM-dominant).
decimal fraction / multiple		Optional
No @default declared; consult the signature and description.
market
SurfaceMarket
unitless by name		Required / declared member
No @default declared; consult the signature and description.
market.asOf
string | number		Snapshot time: epoch ms, `'YYYY-MM-DD'`, or a ZONED ISO datetime — one grammar for "when" across every package. Each boundary resolves it once via core `resolveAsOf` (zone-less datetimes are rejected with a teaching error; TotalFinance never reads the machine clock or zone).
an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)		Required / declared member
No @default declared; consult the signature and description.
market.dividendYield
number		Continuous dividend yield; defaults to 0 when omitted.
decimal rate (0.05 = 5%)		Optional
No @default declared; consult the signature and description.
market.riskFreeRate
number
decimal rate (0.05 = 5%)		Required / declared member
No @default declared; consult the signature and description.
market.spot
number		Spot price. Falls back to each quote's `underlyingPrice` when omitted.
unitless by name		Optional
No @default declared; consult the signature and description.
quotes
OptionQuote[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

VolatilitySurfaceSnapshot

A serialized surface (spec WS4.4). Carries the model, per-slice smile state (including any fitted `svi`/`sabr`/`heston` parameters), points, assumptions/diagnostics, the global Heston parameters, `spotRef`, and the config knobs needed to REBUILD interpolators. Closures are never serialized — {@link VolatilitySurface.fromJSON} rebuilds them from this state so the restored surface answers `iv()` identically.

/**
 * A serialized surface (spec WS4.4). Carries the model, per-slice smile state (including any fitted
 * `svi`/`sabr`/`heston` parameters), points, assumptions/diagnostics, the global Heston parameters, `spotRef`,
 * and the config knobs needed to REBUILD interpolators. Closures are never serialized —
 * {@link VolatilitySurface.fromJSON} rebuilds them from this state so the restored surface answers `iv()`
 * identically.
 */
export interface VolatilitySurfaceSnapshot {
    schemaVersion: string;
    model: SurfaceModel;
    slices: SurfaceSlice[];
    points: SurfacePoint[];
    assumptions: Assumptions<{
        shock?: SurfaceShock;
    }>;
    diagnostics: Diagnostics;
    /** The global SSVI parameters when `model: 'ssvi'`. */
    ssvi?: SSVIParameters;
    /** The global eSSVI parameters when `model: 'essvi'`. */
    essvi?: ESSVIParameters;
    /** The global Heston parameters when `model: 'heston'`. */
    heston?: HestonParameters;
    referenceSpot: number;
    /** Config knobs needed to rebuild the per-slice interpolators without re-solving from quotes. */
    config: {
        riskFreeRate: number;
        dividendYield: number;
        sabrBeta: number;
        sabrVolatilityType: SabrVolatilityType;
        smoothingBandwidth?: number;
        cosineExpansionTerms: number;
    };
}
Fields, parameters & returned members (75)
Name / typeMeaning & unitOptional / default
assumptions
Assumptions<{ shock?: SurfaceShock; }>
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.asOf
number
an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)		Optional
No @default declared; consult the signature and description.
assumptions.calendar
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.calendarVersion
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.compounding
import('@insiderfinance/totalfinance/core').InterestCompounding
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.compounding.periodsPerYear
number
per year (count)		Required / declared member
No @default declared; consult the signature and description.
assumptions.compounding.type
'periodic'
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.conventionsVersion
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.dayCount
import('@insiderfinance/totalfinance/core').DayCount
count (integer)		Optional
No @default declared; consult the signature and description.
assumptions.dividendModel
import('@insiderfinance/totalfinance/core').DividendModel
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.engine
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.expiryConvention
'us-equity-close' | 'explicit-instant'		How the contract's expiry label was resolved to an instant: `'us-equity-close'` when a date-only `YYYY-MM-DD` expiry resolved to the US equity/options close — 16:00 America/New_York, or 13:00 on an early-close day; `'explicit-instant'` when the caller supplied a zoned datetime. Named so the convention is never silent (alignment spec P1.6); instrument builders own the full story in Phase 3.
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.model
string
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.seed
number		The randomness seed this result was computed under — REQUIRED echo for a `randomness: 'seeded'` Pricer (Gate C, 2026-08-23): a stochastic result that does not name its seed cannot be replayed from the result alone. Deterministic paths never set it.
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.shock
SurfaceShock
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.shock.parallel
number		Additive parallel shift applied to every stored IV (in vol points, e.g. `0.02` = +2 vol).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.shock.skewTilt
number		Skew rotation: adds `skewTilt · k` where `k = ln(K/forward)` (log-moneyness).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.shock.sticky
'strike' | 'moneyness'		Which quantity the tilt is pinned to: `'strike'` (default) or `'moneyness'`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.timeToExpiryConvention
never
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.timeToExpiryYears
number
years (decimal)		Optional
No @default declared; consult the signature and description.
assumptions.units
import('@insiderfinance/totalfinance/core').GreekUnits
unitless by name		Optional
No @default declared; consult the signature and description.
assumptions.units.rho
import('@insiderfinance/totalfinance/core').RhoUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.units.theta
import('@insiderfinance/totalfinance/core').ThetaUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
assumptions.units.vega
import('@insiderfinance/totalfinance/core').VegaUnit
unitless by name		Required / declared member
No @default declared; consult the signature and description.
config
{ cosineExpansionTerms: number; dividendYield: number; riskFreeRate: number; sabrBeta: number; sabrVolatilityType: SabrVolatilityType; smoothingBandwidth?: number; }		Config knobs needed to rebuild the per-slice interpolators without re-solving from quotes.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
config.cosineExpansionTerms
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
config.dividendYield
number
decimal rate (0.05 = 5%)		Required / declared member
No @default declared; consult the signature and description.
config.riskFreeRate
number
decimal rate (0.05 = 5%)		Required / declared member
No @default declared; consult the signature and description.
config.sabrBeta
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
config.sabrVolatilityType
SabrVolatilityType
unitless by name		Required / declared member
No @default declared; consult the signature and description.
config.smoothingBandwidth
number
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics
Diagnostics
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.autoReason
string		When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.converged
boolean		Whether an iterative procedure converged. `false` means the value is not trustworthy.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.decomposition
Record<string, number>		Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3).
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.engine
string		Pricing/solver engine name, e.g. `black-scholes-merton`.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.finiteDifferenceBumps
Record<string, number>		Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.)
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.iterations
number		Iteration count for iterative methods.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.method
string		Numerical method, e.g. `closed-form`, `brent`, `finite-difference`.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection
import('@insiderfinance/totalfinance/core/pricing').SelectionReport		The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection.candidates
readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]		Candidates an automatic selection considered; absent for explicit mode.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.selection.mode
'explicit' | 'automatic'
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.reason
string		Why the selected engine answers this request.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected
{ name: string; version?: string; }
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected.name
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
diagnostics.selection.selected.version
string
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.timingMs
number		Wall-clock timing in milliseconds, when measured.
milliseconds		Optional
No @default declared; consult the signature and description.
diagnostics.warmup
number		Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted.
unitless by name		Optional
No @default declared; consult the signature and description.
diagnostics.warnings
QuantWarning[]		Structured warnings; always present (possibly empty).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi
ESSVIParameters		The global eSSVI parameters when `model: 'essvi'`.
unitless by name		Optional
No @default declared; consult the signature and description.
essvi.phi
import('@insiderfinance/totalfinance/volatility').SSVIPhi		Curvature function (global), same family as SSVI.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.eta
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.gamma
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.kind
('heston') | ('power-law')
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.phi.lambda
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
essvi.thetaTerm
{ timeToExpiryYears: number; theta: number; rho: number; }[]		Per-knot `(t, θ, ρ)`: θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston
HestonParameters		The global Heston parameters when `model: 'heston'`.
unitless by name		Optional
No @default declared; consult the signature and description.
heston.kappa
number		Mean-reversion speed κ.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.rho
number		Spot/variance correlation ρ ∈ [−1, 1].
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.sigma
number		Volatility of variance ξ ("vol of vol").
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.theta
number		Long-run variance θ.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
heston.v0
number		Initial instantaneous variance v₀ (= σ₀²).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
model
SurfaceModel
unitless by name		Required / declared member
No @default declared; consult the signature and description.
points
SurfacePoint[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
referenceSpot
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
schemaVersion
string
unitless by name		Required / declared member
No @default declared; consult the signature and description.
slices
SurfaceSlice[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi
SSVIParameters		The global SSVI parameters when `model: 'ssvi'`.
unitless by name		Optional
No @default declared; consult the signature and description.
ssvi.phi
import('@insiderfinance/totalfinance/volatility').SSVIPhi		Curvature function.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.eta
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.gamma
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.kind
('heston') | ('power-law')
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.phi.lambda
number
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.rho
number		Global skew `ρ ∈ (−1, 1)`.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
ssvi.thetaTerm
{ timeToExpiryYears: number; theta: number; }[]		ATM total-variance knots `(t, θ)`, strictly increasing in both (calendar-arbitrage-free).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

function

volatilitySurface

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export declare function volatilitySurface(input: VolatilitySurfaceInput): VolatilitySurface;
Fields, parameters & returned members (22)
Name / typeMeaning & unitOptional / default
(input)
VolatilitySurfaceInput
unitless by name		Required / declared member
No @default declared; consult the signature and description.
(input).config
SurfaceConfig
unitless by name		Optional
No @default declared; consult the signature and description.
(input).market
SurfaceMarket
unitless by name		Required / declared member
No @default declared; consult the signature and description.
(input).quotes
OptionQuote[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.arbitrage
(options?: ArbitrageCheckOptions) => ArbitrageReport		Run the static no-arbitrage diagnostics (calendar + butterfly) over this surface.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.assumptions
Assumptions<{ shock?: SurfaceShock; }>
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.diagnostics
Diagnostics
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.essvi
ESSVIParameters		The global eSSVI parameters when `model: 'essvi'`, else `undefined`.
unitless by name		Optional
No @default declared; consult the signature and description.
return.expiries
() => string[]		Sorted list of the surface's expiry labels.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.heston
HestonParameters		The global Heston parameters when `model: 'heston'`, else `undefined`.
unitless by name		Optional
No @default declared; consult the signature and description.
return.impliedVolatility
(strike: number, expiry: string | number) => number		Implied vol at `(strike, expiry)`. Throws if the surface is empty (never fabricates).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.impliedVolatilityByDelta
(callDelta: number, expiry: string | number) => number		Implied vol on the call-delta axis: interpolate the strike whose call-delta equals `callDelta` (∈ (0, 1)) from the slice's stored delta ladder, then read the smile there. A 0.25 delta selects the 25-delta call strike.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.impliedVolatilityByMoneyness
(moneyness: number, expiry: string | number, options?: { forward?: boolean; }) => number		Implied vol on the moneyness axis. `moneyness` is `K/S` (spot-moneyness) by default, or `K/F` (forward-moneyness) when `forward` is set — so `impliedVolatilityByMoneyness(1, e)` is the at-the-money(-forward) vol. For a NUMERIC `expiry` (a maturity in years) the forward is computed AT THAT MATURITY, `F(t) = spot·e^{(r−q)·t}` — not borrowed from the nearest fitted slice, which anchored a mid-expiry query to a neighbour's forward and shifted the ATM-forward point off by the carry between them.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.lookup
(strike: number, expiry: string | number) => SurfaceLookup		Implied vol at `(strike, expiry)` with diagnostics. Strike uses the per-slice smile; expiry interpolates total variance linearly between the two bracketing slices. `extrapolated` is true when the query lies outside the fitted strike range or expiry range.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.model
SurfaceModel
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.points
SurfacePoint[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.shock
(shifts: { parallel?: number; skewTilt?: number; }, { sticky }?: { sticky?: 'strike' | 'moneyness'; }) => VolatilitySurface		Return a NEW surface with a shifted vol structure, produced WITHOUT re-fitting: each stored IV sample gains a `parallel` offset plus a `skewTilt · k` skew rotation (`k = ln(K/forward)`, log-moneyness), the per-slice deltas are recomputed from the shifted IVs, and only the interpolators are rebuilt. The shock is echoed in the new surface's `assumptions.shock`. `sticky`: `'strike'` (default) pins the tilt to each stored strike's own log-moneyness vs the slice forward; `'moneyness'` lets the same additive shift travel with moneyness. Because the shift is applied to the stored strike-indexed IV samples, both modes coincide at the stored strikes in this eager v1 — the distinction only matters once a surface is re-anchored to a new spot/forward, which this method does not do; the requested mode is recorded in `assumptions.shock.sticky` so a caller that later re-anchors knows how the tilt was meant to travel. Parametric models (`svi`/`sabr`/`heston`) have no closed-form shock, so the current smile is SAMPLED at each slice's stored strikes, those samples are shifted, and the result DEGRADES to `'interpolated'` with a `volatility.shock_degraded_to_interpolated` `warn` — the parametric fit is not re-fit. Non-parametric models (`raw`/`interpolated`/`smoothed`) are preserved.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.slice
(expiry: string | number) => SurfaceSlice | undefined		The smile at an expiry (exact label or nearest by `t`), or `undefined` if none.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.slices
SurfaceSlice[]
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.ssvi
SSVIParameters		The global SSVI parameters when `model: 'ssvi'`, else `undefined`.
unitless by name		Optional
No @default declared; consult the signature and description.
return.toJSON
() => VolatilitySurfaceSnapshot		Serialize the surface to a plain, JSON-safe {@link VolatilitySurfaceSnapshot} (no closures). Restore it with {@link VolatilitySurface.fromJSON}; the pair round-trips `iv()` identically on all six models.
unitless by name		Required / declared member
No @default declared; consult the signature and description.
return.toRows
() => SurfaceRow[]		The smile-chart / heatmap feed: one {@link SurfaceRow} per (slice, stored strike), with `logMoneyness = ln(strike/forward)` and the stored `delta`/`iv`. Per the workspace missing-value policy (WS2.12), any non-finite chart-facing numeric is emitted as `null` (never `NaN`, never omitted).
unitless by name		Required / declared member
No @default declared; consult the signature and description.
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.