Skip to content
TotalFinance

Volatility · @insiderfinance/totalfinance

@insiderfinance/totalfinance/volatility/essvi

import { … } from '@insiderfinance/totalfinance/volatility/essvi'
stable-by-law (pre-1.0; not a 1.0 stability guarantee)iface 5type 1fn 4JSON ↗
iface

ESSVIArbitrage

#

No-arbitrage diagnosis of an eSSVI surface.

Signature
import type { ESSVIArbitrage } from '@insiderfinance/totalfinance/volatility/essvi';

/** No-arbitrage diagnosis of an eSSVI surface. */
export interface ESSVIArbitrage {
    /** No calendar-spread arbitrage — `w(k, t)` non-decreasing in `t` at every grid `k` (the definition). */
    calendarArbitrageFree: boolean;
    /** No butterfly arbitrage — the exact Gatheral `g ≥ 0` density test at every grid maturity. */
    butterflyArbitrageFree: boolean;
    /** The minimum Gatheral `g(k)` over the grid and maturities (`≥ 0` ⇔ butterfly-free). */
    minButterflyG: number;
    /** Minimum `Δw` between adjacent maturities over the grid (`≥ 0` ⇔ calendar-free). */
    minCalendarSlope: number;
}
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
butterflyArbitrageFreeboolean

No butterfly arbitrage — the exact Gatheral g ≥ 0 density test at every grid maturity.

unitless by name
RequiredNo @default declared
calendarArbitrageFreeboolean

No calendar-spread arbitrage — w(k, t) non-decreasing in t at every grid k (the definition).

unitless by name
RequiredNo @default declared
minButterflyGnumber

The minimum Gatheral g(k) over the grid and maturities (≥ 0 ⇔ butterfly-free).

unitless by name
RequiredNo @default declared
minCalendarSlopenumber

Minimum Δw between adjacent maturities over the grid (≥ 0 ⇔ calendar-free).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ESSVICalibration

#

Result of calibrateEssvi.

Signature
import type { ESSVICalibration } from '@insiderfinance/totalfinance/volatility/essvi';

/** Result of {@link calibrateEssvi}. */
export interface ESSVICalibration {
    parameters: ESSVIParameters;
    /** Root-mean-square total-variance error across all points. */
    rmse: number;
    perSliceRmse: Array<{
        timeToExpiryYears: number;
        rmse: number;
    }>;
    /** The fitted skew term structure — the payoff of eSSVI over global-ρ SSVI. */
    rhoTerm: Array<{
        timeToExpiryYears: number;
        rho: number;
    }>;
    arbitrage: ESSVIArbitrage;
    converged: boolean;
    assumptions: {
        conventionsVersion: string;
        phi: 'power-law' | 'heston';
        skew: 'per-maturity';
        weight: 'uniform' | 'vega';
        /** Whether the search began from a caller-supplied start or the internal global-SSVI warm start. */
        initialParameters: 'supplied' | 'ssvi-warm-start';
    };
    diagnostics: Diagnostics;
}
Fields, parameters and returned members (40)

Loading 40 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ESSVICalibrationInput

#

Input for calibrateEssvi.

Signature
import type { ESSVICalibrationInput } from '@insiderfinance/totalfinance/volatility/essvi';

/** Input for {@link calibrateEssvi}. */
export interface ESSVICalibrationInput {
    slices: ESSVISliceInput[];
}
Fields, parameters and returned members (1)
Name · typeMeaning · unitRequired · default
slicesSSVISliceInput[]—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ESSVICalibrationOptions

#

Options for calibrateEssvi.

Signature
import type { ESSVICalibrationOptions } from '@insiderfinance/totalfinance/volatility/essvi';

/** Options for {@link calibrateEssvi}. */
export interface ESSVICalibrationOptions {
    /** Curvature family; default `'power-law'`. */
    phi?: 'power-law' | 'heston';
    /**
     * Least-squares weighting of the total-variance residuals: `'uniform'` (default) or `'vega'` — weight each
     * point by its Black vega `∝ φ(d₁)·√t`, so liquid ATM/near-the-money strikes dominate the fit. Threaded
     * through the SSVI warm-start too.
     */
    weight?: 'uniform' | 'vega';
    /** Outer-search iteration budget (default 2,000, maximum 10,000). */
    maximumIterations?: number;
    /** Outer-search tolerance (default 1e-12). */
    tolerance?: number;
    /**
     * Warm start (Stage 4.5): a scalar `rho` broadcasts to every maturity knot, an array must match
     * the slice count; `phi.kind` must equal the calibration's `phi` family. A supplied start REPLACES
     * the internal SSVI warm start (echoed in `assumptions.initialParameters`).
     */
    initialParameters?: {
        rho: number | number[];
        phi: SSVIPhi;
    };
}
Fields, parameters and returned members (11)
Name · typeMeaning · unitRequired · default
initialParameters{ phi: SSVIPhi; rho: number | number[]; }

Warm start (Stage 4.5): a scalar rho broadcasts to every maturity knot, an array must match the slice count; phi.kind must equal the calibration's phi family. A supplied start REPLACES the internal SSVI warm start (echoed in assumptions.initialParameters).

unitless by name
OptionalNo @default declared
initialParameters.phiSSVIPhi—unitless by nameRequiredNo @default declared
initialParameters.phi.etanumber—unitless by nameRequiredNo @default declared
initialParameters.phi.gammanumber—unitless by nameRequiredNo @default declared
initialParameters.phi.kind('heston') | ('power-law')—unitless by nameRequiredNo @default declared
initialParameters.phi.lambdanumber—unitless by nameRequiredNo @default declared
initialParameters.rhonumber | number[]—unitless by nameRequiredNo @default declared
maximumIterationsnumber

Outer-search iteration budget (default 2,000, maximum 10,000).

unitless by name
OptionalNo @default declared
phi'power-law' | 'heston'

Curvature family; default 'power-law'.

unitless by name
OptionalNo @default declared
tolerancenumber

Outer-search tolerance (default 1e-12).

unitless by name
OptionalNo @default declared
weight'vega' | 'uniform'

Least-squares weighting of the total-variance residuals: 'uniform' (default) or 'vega' — weight each point by its Black vega ∝ φ(d₁)·√t, so liquid ATM/near-the-money strikes dominate the fit. Threaded through the SSVI warm-start too.

unitless by name
OptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ESSVIParameters

#

Calibrated eSSVI surface parameters — SSVI with a per-maturity skew.

Signature
import type { ESSVIParameters } from '@insiderfinance/totalfinance/volatility/essvi';

/** Calibrated eSSVI surface parameters — SSVI with a per-maturity skew. */
export interface ESSVIParameters {
    /** Curvature function (global), same family as SSVI. */
    phi: SSVIPhi;
    /** Per-knot `(t, θ, ρ)`: θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity. */
    thetaTerm: Array<{
        timeToExpiryYears: number;
        theta: number;
        rho: number;
    }>;
}
Fields, parameters and returned members (6)
Name · typeMeaning · unitRequired · default
phiSSVIPhi

Curvature function (global), same family as SSVI.

unitless by name
RequiredNo @default declared
phi.etanumber—unitless by nameRequiredNo @default declared
phi.gammanumber—unitless by nameRequiredNo @default declared
phi.kind('heston') | ('power-law')—unitless by nameRequiredNo @default declared
phi.lambdanumber—unitless by nameRequiredNo @default declared
thetaTerm{ timeToExpiryYears: number; theta: number; rho: number; }[]

Per-knot (t, θ, ρ): θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

ESSVISliceInput

#

One maturity slice of the market surface (same shape as SSVI's).

Signature
import type { ESSVISliceInput } from '@insiderfinance/totalfinance/volatility/essvi';

/** One maturity slice of the market surface (same shape as SSVI's). */
export type ESSVISliceInput = SSVISliceInput;
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
impliedVolatilitynumber[]

Implied volatilities aligned to k (converted to w = iv²·t). Provide this or w.

unitless by name
OptionalNo @default declared
knumber[]

Log-moneyness ln(K/F) per observation.

unitless by name
RequiredNo @default declared
timeToExpiryYearsnumber

Maturity in years.

years (decimal)
RequiredNo @default declared
wnumber[]

Total variance σ²·t aligned to k. Provide this or iv.

unitless by name
OptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

calibrateEssvi

#

Fit a calendar-arbitrage-free eSSVI surface: θ knots from each slice's ATM variance (made monotone), then per-maturity ρᵢ and a global φ by least squares — warm-started from a global SSVI fit, so eSSVI begins at the best single-ρ surface and can only improve, with a calendar-crossing penalty keeping the fit arbitrage-free between maturities. See the spec.

Signature
import { calibrateEssvi } from '@insiderfinance/totalfinance/volatility/essvi';

export declare function calibrateEssvi(surface: ESSVICalibrationInput, options?: ESSVICalibrationOptions): ESSVICalibration;
Fields, parameters and returned members (23)

Loading 23 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

essviArbitrageFree

#

Diagnose the no-arbitrage status of an eSSVI surface: butterfly (exact Gatheral g ≥ 0 at each grid maturity, reducing the slice to raw SVI) and calendar (w(k, t) non-decreasing in t at every grid k, scanned directly because θ-monotonicity is not sufficient once ρ varies). See the spec.

Signature
import { essviArbitrageFree } from '@insiderfinance/totalfinance/volatility/essvi';

export declare function essviArbitrageFree(parameters: ESSVIParameters, options?: { grid?: number[]; maturityGrid?: number[]; }): ESSVIArbitrage;
Fields, parameters and returned members (10)
Name · typeMeaning · unitRequired · default
(options){ grid?: number[]; maturityGrid?: number[]; }—unitless by nameOptionalNo @default declared
(options).gridnumber[]—unitless by nameOptionalNo @default declared
(options).maturityGridnumber[]—unitless by nameOptionalNo @default declared
(parameters)ESSVIParameters—unitless by nameRequiredNo @default declared
(parameters).phiSSVIPhi

Curvature function (global), same family as SSVI.

unitless by name
RequiredNo @default declared
(parameters).thetaTerm{ timeToExpiryYears: number; theta: number; rho: number; }[]

Per-knot (t, θ, ρ): θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.

unitless by name
RequiredNo @default declared
return.butterflyArbitrageFreeboolean

No butterfly arbitrage — the exact Gatheral g ≥ 0 density test at every grid maturity.

unitless by name
RequiredNo @default declared
return.calendarArbitrageFreeboolean

No calendar-spread arbitrage — w(k, t) non-decreasing in t at every grid k (the definition).

unitless by name
RequiredNo @default declared
return.minButterflyGnumber

The minimum Gatheral g(k) over the grid and maturities (≥ 0 ⇔ butterfly-free).

unitless by name
RequiredNo @default declared
return.minCalendarSlopenumber

Minimum Δw between adjacent maturities over the grid (≥ 0 ⇔ calendar-free).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

essviTotalVariance

#

Total implied variance w(k, t) on a calibrated eSSVI surface.

Signature
import { essviTotalVariance } from '@insiderfinance/totalfinance/volatility/essvi';

export declare function essviTotalVariance(parameters: ESSVIParameters, k: number, timeToExpiryYears: number): number;
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
(k)number—unitless by nameRequiredNo @default declared
(parameters)ESSVIParameters—unitless by nameRequiredNo @default declared
(parameters).phiSSVIPhi

Curvature function (global), same family as SSVI.

unitless by name
RequiredNo @default declared
(parameters).thetaTerm{ timeToExpiryYears: number; theta: number; rho: number; }[]

Per-knot (t, θ, ρ): θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.

unitless by name
RequiredNo @default declared
(timeToExpiryYears)number—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

essviVolatility

#

Implied volatility √(w/t) on a calibrated eSSVI surface.

Signature
import { essviVolatility } from '@insiderfinance/totalfinance/volatility/essvi';

export declare function essviVolatility(parameters: ESSVIParameters, k: number, timeToExpiryYears: number): number;
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
(k)number—unitless by nameRequiredNo @default declared
(parameters)ESSVIParameters—unitless by nameRequiredNo @default declared
(parameters).phiSSVIPhi

Curvature function (global), same family as SSVI.

unitless by name
RequiredNo @default declared
(parameters).thetaTerm{ timeToExpiryYears: number; theta: number; rho: number; }[]

Per-knot (t, θ, ρ): θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity.

unitless by name
RequiredNo @default declared
(timeToExpiryYears)number—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.