@insiderfinance/totalfinance 0.1.0

package/modules/fixed-income/dist/models.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Short-rate models (spec §14.3): Vasicek, Cox-Ingersoll-Ross (CIR), and Hull-White (extended
+ * Vasicek, fit to the initial curve) in closed form, plus a Hull-White / Black-Karasinski trinomial
+ * tree for the lognormal case that has no analytic bond price.
+ *
+ * The analytic models expose affine discount-bond prices `P(t,T) = A·e^{−B·r}`, zero rates, the moments
+ * of the short rate, and — for the Gaussian models — the analytic zero-coupon-bond option (Jamshidian)
+ * that yields caplet/floorlet prices. The trinomial tree calibrates its drift to reprice the input
+ * discount curve exactly (Hull-White forward induction), so Black-Karasinski inherits an
+ * arbitrage-free fit. All inputs are validated; bad parameters throw (no silent degradation).
+ */
+import { type QuantWarning } from '../../core/dist/index.js';
+import type { YieldCurve } from './curves.js';
+export interface VasicekParameters {
+    /** Mean-reversion speed (> 0). */
+    a: number;
+    /** Long-run mean level. */
+    b: number;
+    /** Instantaneous volatility (> 0). */
+    sigma: number;
+    /** Current short rate. */
+    r0: number;
+}
+export interface ShortRateMoments {
+    mean: number;
+    variance: number;
+    standardDeviation: number;
+}
+export interface ShortRateModel {
+    /** Affine discount-bond price `P(t,T)` for a short rate `r` at time `t` (τ = T − t in years). */
+    discountBond(shortRate: number, tau: number): number;
+    /** Continuously-compounded zero rate `−ln P / τ`. */
+    zeroRate(shortRate: number, tau: number): number;
+    /** Mean/variance of the short rate at horizonYears `T` (years), from `r0`. */
+    shortRateMoments(years: number): ShortRateMoments;
+}
+/** Inputs shared by Gaussian zero-coupon-bond option methods. */
+export interface ZeroCouponBondOptionInput {
+    optionMaturity: number;
+    bondMaturity: number;
+    strike: number;
+    right: 'call' | 'put';
+}
+/** Inputs shared by Gaussian caplet and floorlet methods. */
+export interface RateOptionletInput {
+    optionMaturity: number;
+    bondMaturity: number;
+    strikeRate: number;
+    accrualFraction: number;
+}
+export interface GaussianShortRateModel extends ShortRateModel {
+    /**
+     * Analytic price of a European call/put on a zero-coupon bond maturing at `tBond`, exercised at
+     * `tOption` (years), struck at `strike` (per unit face) — the Jamshidian decomposition's building
+     * block. Returns a present value as of t = 0.
+     */
+    zeroCouponBondOption(input: ZeroCouponBondOptionInput): number;
+    /** Caplet on the simple rate over `[tOption, tBond]`, strike `capRate`, per unit notional. */
+    caplet(input: RateOptionletInput): number;
+    /** Floorlet on the simple rate over `[tOption, tBond]`, strike `floorRate`, per unit notional. */
+    floorlet(input: RateOptionletInput): number;
+}
+/** Construct a Vasicek model `dr = a(b − r)dt + σ dW`. */
+export declare function vasicek(parameters: VasicekParameters): GaussianShortRateModel;
+export interface CirParameters {
+    a: number;
+    b: number;
+    sigma: number;
+    r0: number;
+}
+/**
+ * A CIR model plus the honest disclosure of whether its parameters keep the short rate strictly
+ * positive. Structurally a {@link ShortRateModel}, so existing consumers are unaffected.
+ */
+export interface CirModel extends ShortRateModel {
+    /** Structured warnings about the calibration (currently: the Feller condition). Always present. */
+    diagnostics: {
+        warnings: QuantWarning[];
+    };
+}
+/**
+ * Construct a CIR model `dr = a(b − r)dt + σ√r dW` (affine, non-negative rates).
+ *
+ * The Feller condition `2ab ≥ σ²` is what keeps the short rate strictly positive. Parameters that
+ * violate it are perfectly ACCEPTABLE — CIR fits to real curves routinely land there, and the
+ * affine bond price stays valid — but the model then puts mass at r = 0, which changes what the
+ * output means. Violation is therefore disclosed (`model.feller_condition_violated`), never thrown
+ * and never silently absorbed.
+ */
+export declare function cir(parameters: CirParameters): CirModel;
+export interface HullWhiteParameters {
+    a: number;
+    sigma: number;
+}
+export interface HullWhiteDiscountBondInput {
+    valuationTime: number;
+    timeToMaturity: number;
+    shortRate: number;
+}
+export interface HullWhiteModel {
+    /** Reconstructed discount bond `P(t,T)` consistent with the initial curve, given short rate `r` at t. */
+    discountBond(input: HullWhiteDiscountBondInput): number;
+    /** Analytic ZCB option as of t = 0 (uses the market curve directly). */
+    zeroCouponBondOption(input: ZeroCouponBondOptionInput): number;
+    caplet(input: RateOptionletInput): number;
+    floorlet(input: RateOptionletInput): number;
+    /** Standard deviation of the short rate at horizonYears `t`. */
+    shortRateStandardDeviation(years: number): number;
+}
+/** Construct a Hull-White model `dr = (θ(t) − a·r)dt + σ dW`, with θ implied by `curve`. */
+export declare function hullWhite(curve: YieldCurve, parameters: HullWhiteParameters): HullWhiteModel;
+export type TreeModel = 'hull-white' | 'black-karasinski';
+export interface ShortRateTreeOptions {
+    meanReversion: number;
+    sigma: number;
+    /** `hull-white` (Gaussian short rate) or `black-karasinski` (lognormal short rate). */
+    model: TreeModel;
+    /** Tree horizonYears in years. */
+    horizonYears: number;
+    /** Number of time steps (default 50). */
+    steps?: number;
+}
+export interface ShortRateTree {
+    readonly model: TreeModel;
+    readonly steps: number;
+    readonly timeStepYears: number;
+    /** Short rate at tree node `(i, j)` (time step i, level j). */
+    shortRate(stepIndex: number, nodeIndex: number): number;
+    /** Tree-implied discount bond price `P(0, T)` for a maturity on the time grid (years). */
+    discountBond(maturity: number): number;
+    /** Reference discount factors the tree was calibrated to, at each grid time. */
+    readonly gridTimes: readonly number[];
+    /** Map a year fraction to its grid step, validating it lands on the grid. */
+    stepOf(years: number): number;
+    /** Half-width of reachable levels at step `i` (nodes span `[-reach, +reach]`). */
+    reachAt(stepIndex: number): number;
+    /**
+     * Generic backward induction from `terminalStep` to the root. `terminal(j)` seeds the value at each
+     * terminal node; at every earlier node the discounted expected continuation is passed to `atNode`,
+     * which returns the node value (inject cashflows, apply call/exercise via min/max). Returns the root
+     * value. The engine behind callable bonds and Bermudan swaptions.
+     */
+    rollback(terminalStep: number, terminal: (j: number) => number, atNode?: (i: number, j: number, continuation: number) => number): number;
+}
+/**
+ * Build a Hull-White / Black-Karasinski trinomial tree calibrated to `curve` via forward induction
+ * (Hull's two-stage procedure). Stage 1 lays out a symmetric mean-reverting tree for the transformed
+ * state `x`; stage 2 shifts each time slice by `α(t)` so the tree reprices every grid discount factor.
+ * For Black-Karasinski the short rate is `exp(x)`, so `α` is solved numerically per step.
+ */
+export declare function shortRateTree(curve: YieldCurve, options: ShortRateTreeOptions): ShortRateTree;
+export interface G2ppParameters {
+    /** Mean reversion of factor x. */
+    a: number;
+    /** Volatility of factor x. */
+    sigma: number;
+    /** Mean reversion of factor y. */
+    b: number;
+    /** Volatility of factor y. */
+    eta: number;
+    /** Instantaneous correlation of the two factors, in [-1, 1]. */
+    rho: number;
+}
+export interface G2ppDiscountBondInput {
+    valuationTime: number;
+    timeToMaturity: number;
+    x?: number;
+    y?: number;
+}
+export interface G2ppModel {
+    /** Reconstructed discount bond `P(t,T)` given factor values `(x, y)` at `t` (default 0 ⇒ the curve). */
+    discountBond(input: G2ppDiscountBondInput): number;
+    /** Analytic zero-coupon-bond option as of t = 0 (Gaussian, like Hull-White but with the G2++ variance). */
+    zeroCouponBondOption(input: ZeroCouponBondOptionInput): number;
+    caplet(input: RateOptionletInput): number;
+    floorlet(input: RateOptionletInput): number;
+    /** Variance of the short rate at horizonYears `t`. */
+    shortRateVariance(years: number): number;
+}
+/**
+ * G2++ (two-additive-factor Gaussian) short-rate model `r(t) = φ(t) + x(t) + y(t)` with correlated
+ * Ornstein-Uhlenbeck factors, fit to the initial `curve` (Brigo–Mercurio). Two factors give a richer,
+ * de-correlating term structure of volatility than one-factor Hull-White, while keeping analytic
+ * discount bonds and (Gaussian) zero-coupon-bond options. Reduces to Hull-White when `eta = 0`.
+ */
+export declare function g2pp(curve: YieldCurve, parameters: G2ppParameters): G2ppModel;
+//# sourceMappingURL=models.d.ts.map

package/modules/fixed-income/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}