Class VarEngine

java.lang.Object
com.quantfinlib.risk.VarEngine
public final class VarEngine extends Object
Portfolio Value-at-Risk, all four classic flavors over one input shape: factor exposures (currency P&L per unit factor return — a delta vector) against a factor covariance matrix or a factor-return history. RiskMetrics answers the single-series question; this engine answers the portfolio one, where the methods disagree and the disagreement is informative:
  • Delta-normal (variance-covariance) — σ_P = √(δ'Σδ), VaR = z·σ_P. Instant, and exactly wrong for optionality;
  • Monte Carlo — Cholesky-correlated Gaussian factor draws through the linear map; converges to delta-normal for a linear book (the tests pin that agreement), and exists so the same harness can price non-linear books by full revaluation;
  • Delta-gamma (Cornish-Fisher): second-order P&L δ'Δx + ½Δx'ΓΔx whose skew tilts the quantile via the Cornish-Fisher expansion. A short-gamma book's VaR is worse than delta-normal says and a long-gamma book's better, the asymmetry delta-normal cannot see;
  • Historical — replay actual factor-return rows through the exposures; no distributional assumption, no correlation matrix, exactly as fat-tailed as the sample was.

Conventions: VaR and ES are returned as positive losses in currency units; confidence is the one-sided level (0.99 = 99%); factor returns and Σ are per-horizon (scale √t outside). Sample-based methods share the tail definitions of TailRisk. Monte Carlo factors the covariance with PsdMatrices.choleskyPsd(double[][]), so a rank-deficient factor covariance is accepted and an indefinite one is rejected. Expected shortfall accompanies each method — post-FRTB, ES is the primary number and VaR the diagnostic. Research lane, deterministic (MC per seed).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    VarEngine.ScenarioReval
    Revalues the book under one scenario's factor moves.
    static final record 
    VarEngine.VarResult
    VaR and ES from Gaussian Monte Carlo factor scenarios.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    deltaGammaEs(double[] exposures, double[][] gamma, double[][] covariance, double confidence)
    Second-order ES: the tail mean of the Cornish-Fisher loss quantile, integrated in closed form.
    static double
    deltaGammaVar(double[] exposures, double[][] gamma, double[][] covariance, double confidence)
    Second-order VaR via the Cornish-Fisher quantile of the delta-gamma P&L.
    static double
    deltaNormalEs(double[] exposures, double[][] covariance, double confidence)
    Delta-normal ES: the Gaussian tail mean, σ·φ(z)/(1−c).
    static double
    deltaNormalVar(double[] exposures, double[][] covariance, double confidence)
    Delta-normal VaR: z-quantile of the Gaussian portfolio P&L.
    static VarEngine.VarResult
    filteredHistoricalVar(double[] exposures, double[][] factorReturns, double lambda, int burnIn, double confidence)
    Filtered historical simulation (Hull and White 1998, J.
    static VarEngine.VarResult
    fullRevaluationVar(double[][] scenarios, VarEngine.ScenarioReval pricer, double confidence)
    Full-revaluation VaR: every scenario repriced through the caller's pricer.
    static VarEngine.VarResult
    historicalVar(double[] exposures, double[][] factorReturns, double confidence)
    Historical simulation: each row of factorReturns is one scenario replayed through the exposures.
    static VarEngine.VarResult
    monteCarloVar(double[] exposures, double[][] covariance, double confidence, int scenarios, long seed)
     
    static double
    portfolioStdev(double[] exposures, double[][] covariance)
    Portfolio stdev √(δ'Σδ) in currency units.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • portfolioStdev

      public static double portfolioStdev(double[] exposures, double[][] covariance)
      Portfolio stdev √(δ'Σδ) in currency units.

    • deltaNormalVar

      public static double deltaNormalVar(double[] exposures, double[][] covariance, double confidence)
      Delta-normal VaR: z-quantile of the Gaussian portfolio P&L.

    • deltaNormalEs

      public static double deltaNormalEs(double[] exposures, double[][] covariance, double confidence)
      Delta-normal ES: the Gaussian tail mean, σ·φ(z)/(1−c).

    • monteCarloVar

      public static VarEngine.VarResult monteCarloVar(double[] exposures, double[][] covariance, double confidence, int scenarios, long seed)

    • deltaGammaVar

      public static double deltaGammaVar(double[] exposures, double[][] gamma, double[][] covariance, double confidence)
      Second-order VaR via the Cornish-Fisher quantile of the delta-gamma P&L. Moments of δ'Δx + ½Δx'ΓΔx under Gaussian factors: mean ½tr(ΓΣ), variance δ'Σδ + ½tr((ΓΣ)²), and the skew that moves the quantile. Accurate for moderate gamma — the expansion degrades when the quadratic term dominates (skew beyond ~1), which is when full revaluation Monte Carlo earns its cost; that boundary is the documented limit, not a hidden one.

    • deltaGammaEs

      public static double deltaGammaEs(double[] exposures, double[][] gamma, double[][] covariance, double confidence)
      Second-order ES: the tail mean of the Cornish-Fisher loss quantile, integrated in closed form. With loss quantile q(p) = −μ + σ·(z_p + (z_p²−1)·s/6) (s = loss skew), the identities E[Z·1{Z>z}] = φ(z) and E[(Z²−1)·1{Z>z}] = z·φ(z) give ES = −μ + σ·φ(z)/(1−c)·(1 + z·s/6) — no numerical integration, and it reduces exactly to deltaNormalEs(double[], double[][], double) when Γ = 0. Same moderate-gamma validity bound as deltaGammaVar(double[], double[][], double[][], double).

    • historicalVar

      public static VarEngine.VarResult historicalVar(double[] exposures, double[][] factorReturns, double confidence)
      Historical simulation: each row of factorReturns is one scenario replayed through the exposures. No assumptions — and no more tail than the window actually contained.

    • filteredHistoricalVar

      public static VarEngine.VarResult filteredHistoricalVar(double[] exposures, double[][] factorReturns, double lambda, int burnIn, double confidence)
      Filtered historical simulation (Hull and White 1998, J. Risk 1(1); Barone-Adesi, Giannopoulos and Vosper 1999): each factor's history is devolatilised by its own EWMA volatility and rescaled to today's, r̃_t,i = r_t,i · σ_{T+1,i} / σ_t,i, and the rescaled rows are replayed through the exposures. The scenarios keep the empirical shape and cross-dependence of the standardised shocks but carry the current volatility, which plain historical simulation ignores.

      EWMA: σ²_t = λσ²_{t−1} + (1−λ)r²_{t−1}, causal and bias-corrected (σ²_t = Σ_{k<t}(1−λ)λ^{t−1−k}r_k² / (1−λ^t)); the first burnIn rows are only used to warm the filter and are not replayed. σ_{T+1} is the forecast after the last row.

      Parameters:
      factorReturns - rows of factor returns, oldest first
      lambda - EWMA decay in (0, 1), 0.94 for daily RiskMetrics
      burnIn - rows used only to start the filter, ≥ 1

    • fullRevaluationVar

      public static VarEngine.VarResult fullRevaluationVar(double[][] scenarios, VarEngine.ScenarioReval pricer, double confidence)
      Full-revaluation VaR: every scenario repriced through the caller's pricer. This is the method that sees what every sensitivity shortcut misses (a knocked-out barrier, a pinned short gamma, an autocall triggered by the scenario itself). Scenarios are rows of factor moves: historical rows for historical full-reval, Cholesky-generated rows for Monte Carlo full-reval. A pricer returning NaN/Infinity throws: a scenario your pricer cannot price is a modelling problem, not a quantile.