@insiderfinance/totalfinance/volatility/sabr

interface

SABRCalibrationOptions

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

export interface SABRCalibrationOptions {
    /** Backbone exponent β ∈ [0, 1] (default 0.5). */
    beta?: number;
    /** Hagan expansion to fit against (default `'lognormal'`). */
    volatilityType?: SabrVolatilityType;
    /** LM iteration budget (default 200, maximum 10,000). */
    maximumIterations?: number;
    /** LM tolerance (default 1e-12). */
    tolerance?: number;
    /**
     * Warm start for the `(α, ρ, ν)` search (Stage 4.5); `β` stays an option and is never fitted.
     * Replaces the ATM-derived default start.
     */
    initialParameters?: {
        alpha: number;
        rho: number;
        nu: number;
    };
}

Fields, parameters & returned members (8)

Name / type	Meaning & unit	Optional / default
`beta` `number`	Backbone exponent β ∈ [0, 1] (default 0.5). unitless by name	Optional No @default declared; consult the signature and description.
`initialParameters` `{ alpha: number; nu: number; rho: number; }`	Warm start for the `(α, ρ, ν)` search (Stage 4.5); `β` stays an option and is never fitted. Replaces the ATM-derived default start. unitless by name	Optional No @default declared; consult the signature and description.
`initialParameters.alpha` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`initialParameters.nu` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`initialParameters.rho` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`maximumIterations` `number`	LM iteration budget (default 200, maximum 10,000). unitless by name	Optional No @default declared; consult the signature and description.
`tolerance` `number`	LM tolerance (default 1e-12). unitless by name	Optional No @default declared; consult the signature and description.
`volatilityType` `SabrVolatilityType`	Hagan expansion to fit against (default `'lognormal'`). 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.

interface

SABRCalibrationResult

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

export interface SABRCalibrationResult {
    parameters: SabrParameters;
    /** Root-mean-square implied-volatility error of the fit. */
    rmse: number;
    converged: boolean;
    iterations: number;
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        beta: number;
        volatilityType: SabrVolatilityType;
        /** Whether the search began from a caller-supplied `initialParameters` or the ATM-derived default. */
        initialParameters: 'supplied' | 'default';
    };
    /** Structured warnings; a non-converged fit explains itself here. */
    diagnostics: Diagnostics;
}

Fields, parameters & returned members (31)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ beta: number; conventionsVersion: string; initialParameters: 'supplied' \| 'default'; volatilityType: SabrVolatilityType; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.beta` `number`	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.initialParameters` `'supplied' \| 'default'`	Whether the search began from a caller-supplied `initialParameters` or the ATM-derived default. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.volatilityType` `SabrVolatilityType`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`converged` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `Diagnostics`	Structured warnings; a non-converged fit explains itself here. 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.
`iterations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`parameters` `SabrParameters`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`parameters.alpha` `number`	Initial volatility level α (> 0). unitless by name	Required / declared member No @default declared; consult the signature and description.
`parameters.beta` `number`	Backbone exponent β ∈ [0, 1]. unitless by name	Required / declared member No @default declared; consult the signature and description.
`parameters.nu` `number`	Volatility of volatility ν (≥ 0). unitless by name	Required / declared member No @default declared; consult the signature and description.
`parameters.rho` `number`	Correlation ρ ∈ (−1, 1). unitless by name	Required / declared member No @default declared; consult the signature and description.
`rmse` `number`	Root-mean-square implied-volatility error of the fit. 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)

interface

SABRSmileInput

Market smile input for {@link calibrateSabrSmile}: the forward, and aligned strikes/impliedVolatilities at one expiry.

/**
 * Calibrate `(α, ρ, ν)` of a SABR smile to market implied volatilities at a single expiry. Needs at least 3
 * strikes. Returns the full {@link SabrParameters} (including the fixed `β`), the fit RMSE, and convergence.
 */
/** Market smile input for {@link calibrateSabrSmile}: the forward, and aligned strikes/impliedVolatilities at one expiry. */
export interface SABRSmileInput {
    forward: number;
    strikes: number[];
    /** Implied volatilities aligned to `strikes` (annualized decimals). */
    impliedVolatilities: number[];
    /** Time to expiry in years. */
    timeToExpiryYears: number;
}

Fields, parameters & returned members (4)

Name / type	Meaning & unit	Optional / default
`forward` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`impliedVolatilities` `number[]`	Implied volatilities aligned to `strikes` (annualized decimals). 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.
`timeToExpiryYears` `number`	Time to expiry in years. 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)

function

calibrateSabrSmile

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

export declare function calibrateSabrSmile(input: SABRSmileInput, options?: SABRCalibrationOptions): SABRCalibrationResult;

Fields, parameters & returned members (24)

Name / type	Meaning & unit	Optional / default
`(input)` `SABRSmileInput`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(input).forward` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(input).impliedVolatilities` `number[]`	Implied volatilities aligned to `strikes` (annualized decimals). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(input).strikes` `number[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(input).timeToExpiryYears` `number`	Time to expiry in years. years (decimal)	Required / declared member No @default declared; consult the signature and description.
`(options)` `SABRCalibrationOptions`	unitless by name	Optional No @default declared; consult the signature and description.
`(options).beta` `number`	Backbone exponent β ∈ [0, 1] (default 0.5). unitless by name	Optional No @default declared; consult the signature and description.
`(options).initialParameters` `{ alpha: number; nu: number; rho: number; }`	Warm start for the `(α, ρ, ν)` search (Stage 4.5); `β` stays an option and is never fitted. Replaces the ATM-derived default start. unitless by name	Optional No @default declared; consult the signature and description.
`(options).initialParameters.alpha` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).initialParameters.nu` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).initialParameters.rho` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).maximumIterations` `number`	LM iteration budget (default 200, maximum 10,000). unitless by name	Optional No @default declared; consult the signature and description.
`(options).tolerance` `number`	LM tolerance (default 1e-12). unitless by name	Optional No @default declared; consult the signature and description.
`(options).volatilityType` `SabrVolatilityType`	Hagan expansion to fit against (default `'lognormal'`). unitless by name	Optional No @default declared; consult the signature and description.
`return.assumptions` `{ beta: number; conventionsVersion: string; initialParameters: 'supplied' \| 'default'; volatilityType: SabrVolatilityType; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.beta` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.initialParameters` `'supplied' \| 'default'`	Whether the search began from a caller-supplied `initialParameters` or the ATM-derived default. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.volatilityType` `SabrVolatilityType`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.converged` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `Diagnostics`	Structured warnings; a non-converged fit explains itself here. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.iterations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.parameters` `SabrParameters`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.rmse` `number`	Root-mean-square implied-volatility error of the fit. 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)