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 genuinely disagree and the disagreement is the point:

• 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, 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). 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	fullRevaluationVar(double[][] scenarios, VarEngine.ScenarioReval pricer, double confidence)	Full-revaluation VaR: every scenario repriced through the CALLER'S pricer — the method that sees what every sensitivity shortcut misses (a knocked-out barrier, a pinned short gamma, an autocall triggered by the scenario itself).
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 java.lang.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.

fullRevaluationVar

public static VarEngine.VarResult fullRevaluationVar(double[][] scenarios,
 VarEngine.ScenarioReval pricer,
 double confidence)

Full-revaluation VaR: every scenario repriced through the CALLER'S pricer — 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.