Gnanam ESG

What it is

Gnanam ESG is an open-source economic scenario generator for actuaries and quantitative risk professionals. It produces Monte Carlo scenario sets across three risk families — interest rates (Hull–White one- and two-factor), equity (GBM, Heston, jump-diffusion), and credit (Merton structural, Jarrow–Turnbull reduced-form) — plus a portfolio layer that simulates one model per family jointly off a single cross-correlated master draw. Every model runs under the risk-neutral measure and also produces a real-world (P-measure) projection of the same paths, so one run serves both pricing-consistent and projection work. Each of the seven models ships with a citation-grade methodology document, an operator-facing user guide, a UAT specification, and a pytest regression harness that locks bit-identical simulation fingerprints. It was built by an FIA with twenty-plus years in life insurance ALM, Solvency II, NAIC RBC, and IFRS 17 frameworks, for reviewers who expect to check the numbers rather than trust them.

Methodology

Each model family is summarised below in the notation of its own methodology document; the full documents ship with the repository, and every formula used in the code is written out in them.

Rates — Hull–White one-factor (HW1F)

A single-factor Gaussian short-rate model under the risk-neutral measure:

$$dr(t) = \bigl(\theta(t) - \alpha \, r(t)\bigr)\,dt + \sigma(t)\,dW(t)$$

$\theta(t)$ is never constructed explicitly. The implementation uses the decomposition $r(t) = x(t) + \varphi(t)$, with $\varphi$ chosen in closed form so the model reproduces the input discount curve exactly — no numerical differentiation of a noisy forward curve. The piecewise-constant $\sigma(t)$ is bootstrapped from an ATM swaption vol grid via Jamshidian’s decomposition of each payer swaption into puts on zero-coupon bonds; each step is a one-dimensional Brent root-find on a monotone function, with no Monte Carlo anywhere in calibration.

Rates — Hull–White two-factor / G2++ (HW2F)

Two correlated Ornstein–Uhlenbeck factors, so the short and long ends of the curve can decorrelate, steepen, and flatten:

$$r(t) = x(t) + y(t) + \varphi(t)$$ $$dx(t) = -a\,x(t)\,dt + \sigma(t)\,dW_1(t), \qquad dy(t) = -b\,y(t)\,dt + \eta(t)\,dW_2(t), \qquad \operatorname{corr}(dW_1, dW_2) = \rho$$

Piecewise-constant $\sigma(t)$ and $\eta(t)$ are bootstrapped from a dual-tenor swaption grid; swaption pricing is by 32-point Gauss–Hermite quadrature with a conditional Jamshidian decomposition (Brigo–Mercurio §4.2). The mean reversions $a$, $b$ and the factor correlation $\rho$ are user-supplied constants — joint calibration of all five parameters is deliberately not attempted.

Equity — Geometric Brownian motion (GBM)

$$\frac{dS(t)}{S(t)} = (\mu - q)\,dt + \sigma\,dW(t)$$

Simulation always runs under the risk-neutral measure with $\mu = r$; the closed-form log solution makes the log-Euler scheme exact. The single $\sigma$ is fitted to a 5×5 implied-vol grid by a bounded scalar optimiser minimising the equal-weighted sum of squared implied-vol residuals; the per-cell residual heatmap shows exactly what a one-parameter model cannot say about the surface. Multi-asset runs (up to 50 assets) correlate the Brownian increments through a Cholesky factor of the input matrix.

Equity — Heston stochastic volatility

$$\frac{dS(t)}{S(t)} = (r - q)\,dt + \sqrt{v(t)}\,dW_S(t), \qquad dv(t) = \kappa\bigl(\theta - v(t)\bigr)\,dt + \xi\sqrt{v(t)}\,dW_v(t)$$

with $d\langle W_S, W_v\rangle(t) = \rho\,dt$. All five parameters $(\kappa, \theta, \xi, \rho, v_0)$ are fitted to the same 5×5 surface by least squares on implied-vol residuals, priced analytically via the Lewis (2001) characteristic-function integral in the Albrecher “little trap” formulation. Simulation uses Andersen’s (2008) Quadratic-Exponential scheme, which keeps variance positive by construction — including in sub-Feller calibrations, where naive Euler schemes go negative and must truncate.

Equity — Jump-diffusion (Merton 1976)

$$\frac{dS(t)}{S(t^{-})} = (r - q - \lambda k)\,dt + \sigma\,dW(t) + \bigl(e^{J} - 1\bigr)\,dN(t), \qquad k = e^{\mu_J + \sigma_J^2/2} - 1$$

$N(t)$ is a Poisson process of intensity $\lambda$ and jump sizes are $J \sim \mathcal{N}(\mu_J, \sigma_J^2)$; the compensator $\lambda k$ in the drift keeps the discounted spot a martingale with jumps switched on. The four parameters $(\sigma, \lambda, \mu_J, \sigma_J)$ are fitted by least squares on implied-vol residuals, with each candidate priced by Merton’s closed-form Poisson-weighted mixture of Black–Scholes prices. The methodology document is explicit that a 25-cell surface identifies these parameters only weakly, and reads railed parameters as a statement about the surface, not solver success.

Credit — Merton structural (1974)

The firm’s asset value follows a geometric diffusion and equity is a European call on the assets struck at the debt face $D$:

$$\frac{dV(t)}{V(t)} = r\,dt + \sigma_V\,dW(t)$$

The unobservable pair $(V, \sigma_V)$ is recovered from observed equity value and equity volatility by the two-equation solver

$$E = V\,N(d_1) - D\,e^{-rT}N(d_2), \qquad \sigma_E\,E = N(d_1)\,\sigma_V\,V$$

solved by bounded least squares inside no-arbitrage bounds; a solve is accepted only when both round-trip relative residuals are at or below $10^{-8}$. Default is assessed at debt maturity — the classic zero-coupon contract — with analytic default probability, distance to default, and credit spread as closed-form checks on the simulation.

Credit — Jarrow–Turnbull reduced-form (1995)

Default is the first jump of a counting process with hazard rate $\lambda(t)$, taken piecewise-constant between spread tenors:

$$Q(t) = \exp\bigl(-\Lambda(t)\bigr), \qquad \Lambda(t) = \int_0^t \lambda(s)\,ds$$

The hazard vector is bootstrapped from an operator-supplied credit-spread term structure under recovery of face paid at default, one Brent root-find per tenor with the recovery integral evaluated in closed form; curves implying a negative segment hazard are rejected outright rather than clipped. Default times are simulated by exact inverse transform of the survival law, so the paths carry the calibrated survival curve with no discretisation.

Portfolio — joint multi-risk simulation

One model per risk family consumes its own slice of a single correlated Gaussian master draw:

$$X = L\,Z, \qquad L\,L^{\mathsf{T}} = C$$

The master matrix $C$ composes each engine’s within-family correlation block with operator-specified cross-family correlations; an infeasible composition is repaired by eigenvalue clipping and the repair is always reported, never silent. Dependence is Gaussian by default, with an optional Student-t copula for joint tail dependence ($\nu$ configurable, and its documented effect on whole-horizon aggregates disclosed). Three sleeves map paths to a portfolio value index — a 10-year constant-maturity zero-coupon bond (rates), a total-return basket (equity), a risky bond (credit) — with VaR, CVaR, drawdown, and diversification-benefit diagnostics.

Validation

The validation regime is the same across the platform: closed-form reprice of the calibration instruments, analytic-versus-Monte-Carlo diagnostics, and a regression harness that locks results bit-for-bit.

• Calibration reprice. HW1F reprices every input swaption to machine precision (~1e-9 bps); HW2F to ≤ 0.001 bps per swaption; Jarrow–Turnbull reproduces every input credit spread to ≤ 0.001 bps per tenor.
• Analytic bond-reprice diagnostic. The rates models compare their own closed-form $P(0,T)$ against the input curve at every maturity — model bias isolated from Monte Carlo noise, with a < 1 bp discretisation target — and separately report the Monte Carlo error (< 10 bps at 2,000 paths with variance reduction).
• Variance reduction, measured. Antithetic variates give a 3–4× reduction in the Monte Carlo standard error of the mean discount factor; the martingale control-variate estimator — unbiased by the martingale property of discounted bond prices — gives roughly a 500× variance reduction over raw Monte Carlo.
• Martingale contracts. The equity and credit simulators check $E^{Q}[S(T)] = S(0)\,e^{(r-q)T}$ (and its credit analogue) against the simulation to Monte Carlo tolerance, with the operator’s real-world drift deliberately set wrong in the tests to prove it cannot leak into the risk-neutral paths. Credit Monte Carlo default frequencies converge to their analytic counterparts within binomial standard errors.
• Bit-identity regression harness. Supplying a seed makes every run reproducible bit-for-bit, and the pytest harness — 155 test files at the time of writing — pins canonical runs to exact numerical fingerprints (for example, the GBM SPX 2024-Q4 calibration is locked at $\sigma = 0.1688$, loss $= 0.0269$). Any change that moves a locked number fails the suite and must justify itself.

A prospective adopter can re-run all of it: clone the repository, run the pytest suite, and reproduce any published run from its saved recipe file and seed. The reprice tables and convergence diagnostics are on screen in every run — the tests are the specification, not prose claims.

Limitations

Stated in the methodology documents’ own terms:

• The rate models are Gaussian. Rates go negative by construction, and the distribution of the short rate is normal at every horizon. HW1F drives the whole curve from one Brownian motion, so all bond prices move in lockstep; HW2F fixes the decorrelation but not the Gaussianity. Neither prices the swaption smile: calibration is to ATM Black (lognormal) vols only, and Bermudans, CMS, and callable bonds are out of scope.
• Calibration quality is bounded by the inputs. The models reproduce whatever curve and surface you pass in; they cannot correct a stale vol grid or a misquoted convention. Curves are interpolated linearly in the zero rate and flat-extrapolated.
• Each equity model has a stated blind spot. GBM flattens the surface to one $\sigma$; Heston has no jumps, so it under-prices the short-dated deep-OTM put wing; jump-diffusion has no volatility clustering, and its jump parameters are weakly identified from a single 25-cell surface.
• The credit models are single-name. Structural and reduced-form marginals with a Gaussian copula across issuers — not CDO tranche or portfolio credit-derivative machinery. Merton assesses default only at maturity against a single zero-coupon debt; Jarrow–Turnbull hazards are deterministic between defaults, and the shipped rating presets are illustrative constructions, not market data.
• Real-world output is a deterministic tilt. Every P-measure projection reuses the risk-neutral paths under a constant market price of risk (or a single hazard-premium scalar), with volatility and jump risk premia explicitly set to zero. The tilt moves the expected path, not its dispersion.
• No liability side. No FX, inflation, mortality, holdings, or cashflow matching — this is an ESG, not an ALM engine.

Do not use it to price smile-dependent exotics, to model portfolio credit tranches, or as a substitute for your own validation and sign-off: it generates scenarios, and the adopting actuary owns everything built on top of them.

Licence and warranty

Apache-2.0. No warranty of any kind. Nothing here is actuarial advice: the adopting actuary owns validation and sign-off in their own control environment, as they would for any model, purchased or built.

Take it

The repository — code, methodology documents, user guides, UAT specifications, and the full regression harness — will be public at launch.

Want it fitted?

If you want this engine calibrated to your business — your curves, your vol surfaces, your reporting basis, your control framework — that is exactly the work I do. Write to bala@gnanamquantech.com.