@robotixai/calculator-engine

Financial retirement projection engine with Monte Carlo simulation.

Features

• Deterministic year-by-year projection (basic + advanced mode)
• Monte Carlo simulation (1K-10K runs, seeded PRNG)
• Multi-jurisdiction tax (US, UK, Cayman, Custom)
• Withdrawal strategies (Standard, Guyton-Klinger, Age-Banded)
• Sensitivity analysis (tornado chart)
• Historical backtest (154 years of Shiller data)
• Retirement age optimizer (binary search)
• Retirement age x spending heatmap
• Advanced mode with cash waterfall, loans, properties
• Portfolio blending and estate value calculation

Installation

npm install @robotixai/calculator-engine

No peer dependencies required. All types and defaults are included in the package.

Quick Start

import { runProjection, runMonteCarloSimulation, DEFAULT_SCENARIO } from '@robotixai/calculator-engine';

// Deterministic projection
const { timeline, metrics } = runProjection(DEFAULT_SCENARIO);
console.log(`Terminal balance: $${metrics.terminal_real.toFixed(2)}`);

// Monte Carlo simulation
const mcResult = runMonteCarloSimulation(DEFAULT_SCENARIO, runProjection, { runs: 1000 });
console.log(`Success probability: ${mcResult.probability_no_shortfall}%`);

API Reference

Projection

Function	Description
runProjection(scenario, overrideReturns?)	Deterministic year-by-year projection (basic mode). Returns { timeline, metrics }.
runAdvancedProjection(scenario, overrideReturns?)	Advanced mode projection with cash waterfall, individual financial items, loans, and properties.

Monte Carlo

Function / Type	Description
runMonteCarloSimulation(scenario, projectionFn, options?)	Seeded PRNG Monte Carlo runner. Returns MCResult with percentiles, fan chart, and success probability.
MCOptions	{ runs?, seed?, budgetMs? }
MCResult	{ probability_no_shortfall, median_terminal, p10_terminal, p90_terminal, fan_chart, ... }
ProjectionFn	Type alias for the projection function signature.

Sensitivity Analysis

Function / Type	Description
runSensitivityAnalysis(scenario, projectionFn)	Tornado chart analysis across 7 key parameters. Returns SensitivityFactor[] sorted by impact.
SensitivityFactor	{ name, label, lowValue, highValue, lowTerminal, highTerminal, spread }

Historical Backtest

Function / Type	Description
runHistoricalBacktest(scenario, projectionFn)	Rolling-window backtest using embedded Shiller data (1871-2024). Returns BacktestResult.
BacktestPeriod	{ startYear, endYear, terminalReal, survived }
BacktestResult	{ periods, successRate }

Retirement Age Optimizer

Function / Type	Description
findEarliestRetirementAge(scenario, projectionFn, mcFn?, options?)	Linear scan + binary search for earliest viable retirement age and minimum contribution.
OptimizerResult	{ retirementAge, terminalReal, survived, mcSuccessPct }
OptimizerOutput	{ results, earliestViableAge, minContribution }
OptimizerOptions	{ mcThreshold? }

Heatmap

Function / Type	Description
generateHeatmap(scenario, projectionFn, options?)	Generates a 2D grid of retirement age x annual spending viability cells.
HeatmapCell	{ retirementAge, annualSpending, viable, terminalReal }
HeatmapOptions	{ retirementAgeRange?, spendingRange?, steps? }

Portfolio

Function / Type	Description
blendPortfolio(assets)	Computes weighted-average return, fee, and liquidity across assets.
calculateEstateValue(endBalance, endDebt, items, years)	Computes estate value with per-item earmarking.
BlendedPortfolio	{ totalValue, blendedReturn, blendedFee, blendedPerfFee, liquidPct }

Engine Modules

Module	Purpose
projection.ts	Basic-mode deterministic projection (contributions, income, withdrawals, fees, taxes, growth)
advanced.ts	Advanced-mode 9-step cash waterfall with individual financial items
monte-carlo.ts	Seeded PRNG, Box-Muller normal/log-normal return generation, fan chart
tax.ts	US progressive brackets, UK progressive with personal allowance taper, Cayman zero, Custom flat
withdrawal.ts	Standard, Guyton-Klinger guardrails, Age-Banded spending phases
sensitivity.ts	Tornado chart across 7 parameters with clamping guards
backtest.ts	154 years of embedded Shiller real total stock returns
optimizer.ts	Linear scan + binary search for earliest viable retirement age
heatmap.ts	2D retirement age x spending grid
portfolio.ts	Portfolio blending and estate value

Edge Cases & Guards

• Near-zero threshold ($100): Prevents asymptotic depletion with high withdrawal rates
• Box-Muller ln(0) guard: Clamps u1 to [1e-10, 1) to prevent -Infinity returns
• Return clamp: Normal distribution returns clamped to >= -1.0 (can't lose more than 100%)
• MC run validation: Runs must be 0 (disabled) or 100-10,000
• Wall-clock budget: MC and optimizer abort after 50 seconds
• RMD divisor guard: Handles missing/zero divisors gracefully
• Age-Banded gaps: Returns $0 withdrawal with console warning
• Sensitivity clamping: retirement_age stays in (current_age, end_age), percentages >= 0
• Amortization zero-rate: Falls back to principal / term to avoid division by zero

License

MIT