Retirement Risk Lab User Manual

Version: 2026-03-02
Scope: v1.0.0 / Engine 1.0.0-engine2

Why Retirement Risk Lab?

When I retired in 2023 after years as Director of Development for a global manufacturing company, one of my wife and my Sunday rituals was “doing the money.” I’d gather the latest balances for everything and use spreadsheet formulas to give my wife an update on how long our money might last - straight-line projections, rough assumptions, best I had.

I knew it wasn’t accurate. Our financial advisor had shown me output from a Monte Carlo simulator once, and it was reassuring - but things change fast, and I didn’t want to depend on someone else for answers about our own financial situation.

I’d just spent a year and a half building a serious blackjack simulator - one that could run two million hands per second and produce deterministic, reproducible results. What I learned from that project was that I had a taste for that kind of rigor: if you’re going to test something, you need to be confident that what you’re testing is the only thing that can change.

So I decided to build a Monte Carlo retirement simulator for myself. One I could trust, inspect, and run as many times as I wanted without bothering anyone.

That’s Retirement Risk Lab. This manual covers how to use it.

1) What this app is

Retirement Risk Lab is an offline Monte Carlo retirement simulator.

It estimates the probability your portfolio survives from current_age through end_age under uncertain returns, inflation, spending, and optional income/expense assumptions.

Core properties:

• Fully offline desktop app (no network needed for simulation)
• Deterministic fixed-seed runs for reproducibility
• Annual and monthly timesteps
• Scenario save/load, run artifact save/load, and run comparison
• In-app help and math transparency output

2) Important input conventions

Before using the app, lock these conventions:

• Money values are annual dollars.
• Percent values are entered as percentages, not decimals.
• Example: enter 5.79 for 5.79% (not 0.0579).
• Projection range is inclusive.
• Simulation runs from current_age through end_age, including both endpoints.
• Default mode is inflation-adjusted spending (real-dollar spending).
• Enable Values are nominal only if you want fixed-dollar spending.
• Avoid double-counting Medicare:
• If your Social Security input is already net of Medicare deductions, leave Medicare Cost as 0.
• Use Medicare Cost only when your SS amount is gross and you want Medicare modeled as a separate drag.

3) Screen layout

The main window has two major areas:

1. Left panel (Inputs) - Core / Income / Advanced tabs - Simulation and goal-seek controls - File action buttons

2. Right panel (Results) - HTML results report - Fan chart / Path table area

Menu bar:

• File: Load/Save Scenario, Run Simulation, Enter License, Save/Load Results, Compare Results
• View: Toggle Fan Chart/Path Table, Export Path CSV, Show Help Home, Show Latest Results
• Help: Quick Start, Features Guide, Path Table Guide, Monte Carlo Primer, Enter License

4) Input fields and meaning

4.1 Core tab

• Current Age: starting age of simulation.
• Retirement Age: age when spending phase starts.
• End Age: final age horizon.
• Starting Balance: portfolio value at start.
• Annual Contribution: annual savings added before retirement age.
• Retirement Spending: annual withdrawal target in retirement.
• Timestep: annual (faster) or monthly (finer detail).
• Trials: number of Monte Carlo trials.
• Values are nominal: disables spending inflation adjustment.

4.2 Income tab

• Enable Social Security Income: toggle Social Security cashflows.
• SS Start Age: age Social Security starts.
• SS Annual Benefit: annual Social Security amount.
• If this value is already net of Medicare deductions, leave Medicare Cost = 0.
• If this value is gross (before Medicare deductions), model Medicare separately using Medicare Cost.
• SS COLA (%): annual growth rate applied to SS benefit.
• Medicare Cost: annual healthcare placeholder drag.
• If SS Annual Benefit is already net of Medicare deductions, keep Medicare Cost = 0.
• If SS Annual Benefit is gross, enter Medicare separately in Medicare Cost.

4.3 Advanced tab

• Mean Return (%): expected annual return assumption.
• Stddev (%): annual return volatility assumption.
• Inflation (%): annual inflation assumption.
• Tax Rate (%): withdrawal-tax placeholder rate.
• RMD Start Age: age required minimum distribution placeholder starts.
• RMD Rate (%): RMD placeholder percentage.
• Seed Mode: fixed or random.
• Seed: seed value used when mode is fixed.
• In random mode, this field is disabled/ignored for input.
• After a random-mode run, app displays the actual seed used so you can reproduce the run later by switching to fixed.

5) Recommended first run workflow

Startup behavior:

• On app launch, Retirement Risk Lab automatically attempts to load baseline.
• If baseline.json is missing, app recreates it and continues.
• If baseline file cannot be written (for example, folder permissions), app still loads embedded baseline values in memory so first run can proceed.
• In normal startup, status line shows Loaded baseline scenario. and fields are pre-populated.

1. Click Load Baseline (or load your own scenario). - If baseline file is missing, app recreates it automatically.
2. Confirm all fields use your intended units.
3. Choose Timestep: - Annual for faster iteration - Monthly for more granular depletion timing
4. Set Trials (start around 10,000 to 50,000 while iterating).
5. Set Seed Mode: - fixed for apples-to-apples comparison runs - random for fresh draw stream each run
6. Click Run Simulation.
7. Review report sections in order: - Run Overview - Assumption Warnings - Ending Balance Distribution - Depletion Timing - Run Metadata - Math Transparency
8. Review fan chart, then toggle Show Path Table for checkpoint detail.

6) How to read results

6.1 Run Overview

• Survival probability: percent of trials not depleted before end age.
• Depletion probability: complement of survival probability.
• Wilson 95% CI: precision interval around survival estimate.
• Trial quality label: interpretation of CI width.

6.2 Ending Balance Distribution

• p10, p50, p90, and min refer to ending-balance percentiles.
• These are distribution points, not direct success probabilities.

6.3 Depletion Timing

• Shows percentile-path depletion markers where applicable.
• Median depletion age summarizes failed trials only.
• In monthly mode, median depletion month is also reported (when failures exist).

6.4 Run Metadata

• Seed used
• RNG identifier
• Elapsed runtime

6.5 Assumption Warnings

• Non-blocking checks for suspicious assumption combinations.
• Warnings do not prevent execution; they flag potential modeling issues.

6.6 Math Transparency

Shows model formulas and convention text used in the run, including:

• Return distribution assumptions
• Monthly conversion conventions
• Operation order conventions
• Percentile method conventions

7) Fan chart and path table

• Fan chart plots path percentiles (p10/p50/p90) by age checkpoint.
• Show Path Table toggles to an amortization-style checkpoint table using the same underlying path percentiles.
• Export Path CSV... exports current path table data (or compare-path table data in compare mode).

8) Goal seek (target success)

Controls:

• Target Success (%)
• Adjust By (for example lower spending or raise retirement income)
• Find Target Mix
• Fast goal-seek (skip final chart run)

Behavior:

• Normal mode runs seek iterations and final full run output.
• Fast mode returns recommendation quickly and skips final full rendering.
• After fast mode, click Run Final Simulation for full chart/table/report output.
• Raise retirement income is implemented as an SS placeholder: the solver raises modeled SS Annual Benefit from SS Start Age; it does not create separate pre-SS bridge income.

9) Scenario and results files

9.1 Scenario files

• Save Scenario... saves inputs only.
• Load Scenario... loads inputs from JSON.
• Load Baseline auto-recreates baseline JSON when missing, so baseline load does not fail due to missing file.
• Current schema: retire-risk.scenario v2.
• Default location behavior:
• Uses sibling Scenarios/ next to the app executable/bundle when writable.
• Falls back to Documents/RetirementRiskLab/Scenarios/ when app folder is not writable.

9.2 Run artifact files

• Save Results... saves scenario + run output as canonical run artifact.
• Load Results... loads a prior run artifact into the UI.
• Compare Results... loads run A and run B and shows B - A deltas.
• Current schema: retire-risk.run v2.
• Legacy retire-risk.run-snapshot v1 files remain loadable.
• Default location behavior:
• Uses sibling Results/ next to the app executable/bundle when writable.
• Falls back to Documents/RetirementRiskLab/Results/ when app folder is not writable.

10) Help system in app

The results panel can show built-in guides:

• Quick Start
• Features Guide
• Suggested Starting Assumptions
• Monte Carlo Primer
• Path Table Guide

Use:

• View > Show Help Home
• View > Show Latest Results

11) Licensing behavior (app side)

License manager entry points:

• File > Enter License...
• Help > Enter License...

Activation methods:

• Import license file
• Paste license JSON and validate

Stored license location:

• Windows: %APPDATA%\RetirementRiskLab\license.json
• macOS: ~/Library/Application Support/RetirementRiskLab/license.json
• Linux (experimental builds): ~/.config/RetirementRiskLab/license.json

Enforcement mode is compile-time:

• SOFT: unlicensed users can run simulation with reminders/watermark behavior
• HARD: simulation blocked until valid license

12) Troubleshooting

12.1 RR_ERR_TRIALS_OUT_OF_RANGE

Meaning:

• Path percentile output is too large for selected trials/timestep.

Fix:

• Reduce Trials, especially in monthly mode and long horizons.

12.2 Runs feel slow

• Lower trials while iterating assumptions.
• Use annual mode during setup, then monthly for final detail.
• Use fast goal-seek for initial targeting.

12.3 Compare chart unavailable

• One or both run files do not include path output required for overlay chart.
• Compare summary metrics may still be available.

12.4 Reproducibility differences

• Fixed-seed runs are deterministic on the same build/platform.
• Cross-platform differences may occur from floating-point behavior.

12.5 Window geometry persistence

• Known gap in current baseline: window size/position persistence can fail on both macOS and Windows.
• If this occurs, relaunch falls back to default window geometry.

12.6 App blocked on first launch (direct download builds)

• macOS:
• If Gatekeeper blocks first launch, Control-click the app, choose Open, then confirm.
• If needed, use System Settings > Privacy & Security and allow the blocked app.
• Windows:
• If SmartScreen warns on first launch, choose More info then Run anyway (only for your trusted build).
• Linux:
• Linux builds are currently experimental/deferred and not part of the baseline shipping targets.
• If you experiment with Linux builds, ensure required runtime libraries are installed for your distro.
• For licensing-enabled Linux builds, install libsodium-dev before compile so static crypto linkage succeeds.
• Placement:
• Prefer running from a user-writable folder.
• If app folder is not writable, scenario/results folders automatically fall back to Documents/RetirementRiskLab.

13) Suggested operating discipline

• Change one assumption block at a time.
• Keep seed fixed when comparing scenario variants.
• Increase trial count only after assumptions are stable.
• Save key run artifacts for audit trail and compare workflows.
• Treat outputs as planning analysis, not guarantees.