Methodology

How RetirementPace turns a plan into a projection: every assumption, formula and limitation. The planner and every calculator run on this one engine, with the same tax and limit figures. It is an educational tool, not advice.

Names in code are the plan's own field names.

1. Ground rules

• Pure and deterministic. @retirementpace/engine does no I/O, reads no clock and draws no random numbers inside a calculation. The same plan gives byte-identical output in a browser, a Web Worker and Node (tested).
• Annual steps. The projection runs one calendar year at a time, from 1 January of startYear to the year the last person reaches their planToAge.
• Months inside a year. Within a year, flows are spread evenly across its months. That is how part-years work: retiring in May, claiming Social Security in October, turning 65 or 59½ mid-year. Birth dates are year and month only.
• Dollars. Inputs are in today's dollars (dollars of startYear) unless a field says otherwise. Internally everything is nominal. The inflation factor for year y is F = (1 + inflation)^(y − startYear), and toReal divides every money figure by it. Nothing is rounded inside the engine. Rounding is for display (and the golden files, which round to cents).
• Growth timing (mid-year convention). An account's opening balance earns a full year at its return r. The year's net flows (contributions, deposits and conversions in, minus RMDs, withdrawals and conversions out) earn half a year: closing = opening × (1 + r) + net × (1 + r/2), never below zero.

2. Each year, in order

2.1 People and status

• ageAtYearEnd = year − birthYear. This is the age used for catch-ups, RMDs, the 65+ deductions and spending phases.
• A person is alive through the year they reach planToAge. From the next year:
  • the survivor files single;
  • the deceased's accounts become the survivor's (spousal rollover, treated as their own), and their contributions stop;
  • wages stop;
  • pensions and annuities continue at survivorPercent (default 0).
• The household is retired once every living person's retirement month has arrived in or before this year. Spending then switches to the retirement budget.

2.2 Income

• Salary and self-employment run from the start year until the owner's retirement month, prorated by month, unless the stream gives its own endYear. amount = annual × F × (1 + growth)^(years since the stream started) × workMonths / 12.
• Other streams (pension, annuity, rental, part-time, other) pay in every year within their startYear–endYear. With indexing: 'none', annual is a fixed nominal amount. Otherwise it is in today's dollars and inflated.
• All income streams are taxable as ordinary income. Salary and part-time are W-2 wages, subject to FICA. Self-employment is subject to self-employment tax. Rental income is entered net.

2.3 Social Security

• Full retirement age (FRA) comes from SSA's table by birth year: 65 for 1937 and earlier, rising two months a year to 66 for 1943–1954, then to 67 for 1960 and later.
• Claiming adjustment at claim age c (whole months; claims are clamped to 62–70):
  • Early, m months before FRA: 1 − (min(m, 36) × 5/9 % + max(0, m − 36) × 5/12 %). That gives 70% at 62 for FRA 67, and 75% at 62 for FRA 66, which matches SSA's table.
  • Late: 1 + (months after FRA, up to 70) × 2/3 %. That gives 124% at 70 for FRA 67.
• Amount. benefitAtFRA × adjustment × F, paid from the claim month (13 − claim month months in the first year).
• COLA equals the plan's inflation assumption. The published COLA (2.8% paid in 2026, 3.6% in 2027) is stored for reference and not used in projections.
• Survivor (v1): after a death, the survivor receives the larger of their own benefit and the deceased's, provided the deceased had claimed.
• Not modelled: spousal benefits and survivor benefits before the survivor's own claim (v2); the earnings test; SSA's rule that a birthday on the 1st counts as the previous month (plans carry no birth day).

2.4 Contributions and limits

Requested contributions are annual × F × (1 + growth)^(years). They are prorated for the months before untilAge, which defaults to the owner's retirement age. Limits apply per person per year:

• 401(k), 403(b), 457 deferrals. Traditional and Roth together are capped at the 402(g) limit plus a catch-up: the age-50 catch-up, or the higher one if the person is 60, 61, 62 or 63 at year end. Deferrals can't exceed the year's pay. Traditional is filled first, then Roth.
• Mandatory Roth catch-up. If last year's wages exceeded the threshold ($150,000, tested against 2025 wages for 2026), the catch-up part can't be pre-tax. Traditional deferrals stop at the base limit and the rest goes to the person's Roth 401(k). With no Roth 401(k), the catch-up isn't made. The first year uses that year's wages as a stand-in for last year's.
• Employer match is rate × min(employee deferral to that account, upToPercentOfSalary × pay). It lands in the same account. It is cut back if base deferrals plus match would exceed the 415(c) annual additions limit (catch-ups are outside 415(c)).
• IRAs. Traditional and Roth together are capped at the IRA limit plus the age-50 catch-up. They are also capped at earned income: for a married couple, the couple's earned income less what the other spouse already contributed (the spousal IRA rule).
• HSAs. Capped at the self-only limit, or the family limit shared by a married couple (family coverage is assumed for couples). Each person 55+ adds their own $1,000 catch-up. Everything is prorated for the months before 65 (Medicare).
• Over the limit. Anything over a limit is still saved: it spills into a taxable account. That is the plan's first taxable account, or one the engine adds ("Other savings").
• Tax treatment. Traditional 401(k), traditional IRA and HSA contributions reduce ordinary income that year. Roth and taxable contributions don't.
• Not modelled: the Roth IRA income phase-out and traditional IRA deductibility phase-outs (all traditional IRA contributions are treated as deductible); the 401(a)(17) compensation cap; plan-specific rules such as vesting or true-ups.

2.5 Spending

• Retirement:
  • the base is baseAnnual × phase multiplier × F, where the phase comes from p1's age;
  • plus healthcare for each living person: pre65Annual for the months they are retired and under 65, and medicareAnnual for the months from 65, both inflated by F × (1 + inflationPremium)^(years);
  • plus one-time items and negative events (purchases).
• Before retirement, with a stated budget: preRetirementAnnual × F, plus healthcare for anyone already retired and under 65.
• Before retirement, with no stated budget: the household spends what is left after taxes and planned savings. Working years neither add to nor draw on the portfolio beyond the planned contributions. The one exception: if savings plus taxes exceed income, the portfolio makes up the difference.
• Positive events (an inheritance, a home sale) are cash in that year. They are taxed as nothing, ordinary income, or long-term gains, as the event says.

2.6 Required minimum distributions

• Start age by birth year: 72 for 1950 and earlier; 73 for 1951–1959; 75 for 1960 and later. These come from the final regulations (T.D. 10001). Born 1959 is 73 under the proposed regulations (REG-103529-23). The final rules reserve that case because SECURE 2.0 lists the 1959 cohort under both 73 and 75.
• RMD = prior year-end balance ÷ the Uniform Lifetime Table (Pub 590-B Table III) divisor for the owner's age at year end. It applies to traditional 401(k)s and IRAs. Roth IRAs and designated Roth 401(k)s have none during the owner's life.
• The first RMD is taken in the year the start age is reached; the April 1 deferral isn't used. The Joint Life table (for a spouse more than 10 years younger) isn't used. An RMD larger than the year's need is saved to the taxable account after tax.

2.7 Withdrawals, conversions and taxes (solved together)

Taxes depend on withdrawals, and withdrawals depend on taxes, so the year is solved as a fixed point:

1. Start with no withdrawals and compute the year's taxes.
2. The cash the accounts must supply is need = contributions + taxes + spending − (income + Social Security + RMDs + events).
3. Withdraw need in strategy order, recompute taxes, and repeat until taxes move by less than $1, up to 20 passes. Each pass shrinks the error by the year's combined marginal rate, so most years settle in a few.
4. A year with a high combined rate settles slowly: for example, 35% federal plus a 10% state rate plus the 10% penalty. Near or above 100% it may not settle at all; the Social Security phase-in can multiply the rate by 1.85. For such a year, after the 20 passes the engine switches to Aitken's Δ² step. Taxes are piecewise linear in the withdrawals, so the step lands on the fixed point within a linear piece, usually in one or two rounds. Years that settle in 20 passes never reach this step. Each year records whether it converged. A local property-test sweep of 3,000 random households per property found no year that didn't.

Withdrawal orders:

• Conventional: cash, taxable, traditional IRA, traditional 401(k), Roth IRA, Roth 401(k), HSA. Within a type, accounts go in plan order.
• Proportional: every account in proportion to what it can give.
• Custom: the listed types first, then the rest in conventional order, so money is never stranded.

How withdrawals are taxed:

• Taxable accounts realise gains pro rata. The gain share is (balance − basis) ÷ balance, taxed as long-term gain. Basis falls by the same share.
• Traditional accounts are ordinary income.
• Early-withdrawal penalty. 10% of traditional withdrawals is added for the share of the year before the owner reaches 59½. For example, someone reaching 59½ in July pays it on half that year's traditional withdrawals.
• Roth withdrawals are tax- and penalty-free. v1 assumes early Roth withdrawals come from contributions.
• HSA withdrawals are tax-free up to the year's healthcare spending, and ordinary income beyond that (the 20% penalty before 65 isn't modelled).
• Not modelled: the rule of 55; 72(t) substantially-equal payments; the five-year rule and ordering rules for Roth earnings.
• Shortfall. If the accounts run dry, the unmet amount is recorded as shortfall. The first year with a shortfall over $1 is the plan's depletion year.

Roth conversions come from traditional accounts (IRAs first) into the owner's Roth IRA. The engine adds a Roth IRA if the owner has none. Each conversion is ordinary income that year, and its tax is paid from cash flow.

• fixedAmount converts amount × F each year in the range.
• fillBracket converts until ordinary taxable income reaches the top of the named bracket. Ordinary income never falls as the conversion grows, so the engine solves for the amount with a bracketing root-finder (Illinois regula falsi, $1 tolerance) around the withdrawal fixed point. The conversion's own tax and any extra Social Security it makes taxable are included.

2.8 Taxes

Federal income tax.

• Ordinary income is:
  • wages, plus net self-employment income less half the self-employment tax;
  • less pre-tax contributions;
  • plus pensions and other income;
  • plus RMDs, traditional withdrawals and conversions;
  • plus cash interest, taxable HSA withdrawals and ordinary events.
• Preferential income is taxable-account dividends, realised gains and capital-gain events.
• The taxable part of Social Security follows the Publication 915 worksheet. Provisional income is other income plus half of benefits. The base amounts are $25,000/$34,000 (single) and $32,000/$44,000 (joint), with 50% and 85% inclusion. They are fixed in the statute and not indexed.
• Deductions are:
  • the standard deduction;
  • plus the additional amount for each person 65+ ($2,050 unmarried, $1,650 married in 2026);
  • plus, for 2025–2028 only, the senior deduction of $6,000 per person 65+. It phases out at 6% of MAGI over $75,000 ($150,000 joint). For a couple the reduction is figured once and each qualifying spouse takes the reduced amount.
  • v1 never itemizes, and uses AGI as MAGI.
• Deductions come off ordinary income first. Ordinary taxable income goes through the brackets. Preferential income is stacked on top at 0%, 15% and 20% (the Qualified Dividends and Capital Gain Tax Worksheet).

State. stateEffectiveTaxRate × federal taxable income. This is a v1 simplification: there are no state tables.

Payroll.

• Employee FICA: 6.2% Social Security up to the wage base, plus 1.45% Medicare.
• Self-employment tax: 12.4% (within the wage base left after the person's wages) plus 2.9%, on 92.35% of net earnings. Half of it is deductible.

Not modelled (v2): NIIT (3.8%), IRMAA, AMT, the 0.9% Additional Medicare Tax, itemized deductions, credits, and state tables.

2.9 Growth

• Each account's mix is the plan allocation, or the account's override. A mix is fixed, or a glide path by the owner's age: linear between points, flat beyond the ends, with p1's age for joint accounts.
• Return = stocks × μs + bonds × μb + cash × μc − fees, using the arithmetic mean nominal returns. Cash-type accounts earn the cash return with no fee.
• Taxable accounts pay out taxableYield of their opening balance (default 2%) each year. It is taxed as qualified dividends, reinvested and added to basis. It is part of the account's return, not extra to it.
• Cash accounts' interest (opening balance × cash return) is taxed as ordinary income each year.

2.10 The record

Each year records:

• every flow by account, and balances;
• taxes by type, AGI, taxable income, taxable Social Security, deductions and the marginal rate;
• spending, surplus and shortfall;
• whether the rules were projected;
• the iterations used.

The summary carries the depletion year, success (no shortfall), ending balance (nominal and real), lifetime taxes and lifetime shortfall.

3. Monte Carlo

simulate(plan, { runs = 1000, seed }) runs the same ledger as §2 once per simulated market. Contributions, limits, taxes, RMDs, conversions and withdrawals are all worked out per path.

• Returns.
  • Each year draws a stocks, bonds and cash return. For each asset, 1 + R is lognormal with the plan's arithmetic mean μ and standard deviation σ, so log(1 + R) ~ N(m, s²) with s² = ln(1 + σ²/(1 + μ)²) and m = ln(1 + μ) − s²/2.
  • The plan's correlations are applied to the underlying normals through a Cholesky factor. With no correlations given, the assets are independent.
  • Years are independent of each other (no momentum or mean reversion).
  • Inflation is fixed at the plan's assumption (stochastic inflation is v2).
• Account return that year is mix · R − fees, with the account's allocation at the owner's age. Cash accounts earn the drawn cash return. Cash interest is taxed at that return, floored at zero.
• Results are over all runs:
  • success rate: the share of runs with no shortfall over $1 in any year;
  • bands: the 10th/25th/50th/75th/90th percentiles of the total balance across accounts at each year end, in today's dollars, by linear interpolation between closest ranks;
  • depletion: the share of runs that ran out, by p1's age in the first shortfall year;
  • median ending balance, in today's dollars.
• Deterministic vs. Monte Carlo. The deterministic projection grows every account at the arithmetic mean. Volatility drags compound growth below that, so the Monte Carlo median ends below the deterministic line, by more the riskier the mix. With every σ set to zero, each Monte Carlo run reproduces the deterministic projection (tested).
• Not modelled (v2): historical backtesting (rolling real sequences), stochastic inflation, fat tails, serial correlation.

Reproducibility

• The seed is an input. The site uses one fixed seed, so a plan shows the same success rate on every visit.
• Each run has its own stream, derived from the seed and the run number (splitmix32) and feeding xoshiro128**. A run's returns don't depend on what other runs drew, so two plans simulated on the same seed face the same markets. That makes "more savings never lowers the success rate" hold run by run.
• Normals come from the Marsaglia polar method.
• Byte-identical in every browser and in Node. ECMAScript leaves Math.exp, Math.log and Math.pow implementation-defined, and engines can disagree in the last bit. The engine never calls them. exp and log are fdlibm ports, built from exactly-specified arithmetic; integer powers multiply. A test bans the platform functions from engine code. Another builds the real worker bundle, runs it in a Node worker thread, and compares it byte for byte with the engine called directly.

Speed

• The ledger is split in two. compilePlan does everything that doesn't depend on returns once per plan: income, Social Security, contributions and limits, spending, payroll tax, RMD divisors, allocations by age. runLedger walks the balances once per path.
• 1,000 runs × 61 years take about 60–80 ms on an M-series laptop. A plan that root-finds Roth conversions every year takes about 125 ms. The budget is 300 ms, and a CI benchmark fails past 600 ms.
• In the browser it runs in a Web Worker: the deterministic result first, Monte Carlo as it lands, with inputs debounced 250 ms.

4. The free planner's starting assumptions

A new plan starts from the quick start's three answers: age, savings, and savings per year. Everything else is a stated assumption. Each one is shown under the quick start and can be changed in the planner's detail sections. They are judgment calls, not official figures:

These are deliberately unflattering. A 40-year-old on the defaults lands near a 50% success rate, mostly because healthcare costs grow faster than inflation for 55 years. The planner says so in words ("At risk"), not only in colour.

5. Rules data

Every indexed figure is stored with the irs.gov, ssa.gov, cms.gov or medicare.gov page it came from, and a test fails if one is missing. The list of sources is at the end of this page. As of 2026-10-24:

Years after the latest complete year are projected:

• the 2026 figures are indexed by the plan's inflation assumption and rounded to the dollar;
• anything already published for that year is laid over the top;
• fields a later partial year has published are indexed from that year (2028's wage base grows from 2027's);
• statutory amounts are not indexed: the senior deduction (which ends after 2028), the Social Security taxation bases, and the HSA catch-up.

Projected years are flagged on every row (rulesProjected). Real IRS indexing uses chained CPI and rounds down to set increments, so projected figures are approximate by design.

6. Testing

• Unit tests per module:
  • bracket boundaries, checked against the Rev. Proc.'s own tax-at-threshold column;
  • Social Security at 62, FRA and 70, against SSA's table;
  • RMD start ages by cohort;
  • every contribution limit and catch-up edge, including 59/60 and 63/64;
  • the penalty before 59½.
• Golden ledgers: six sample plans whose yearly ledgers, rounded to cents, are checked in. Any change to them fails CI until it is reviewed.
• Property tests (fast-check):
  • more savings never lowers ending wealth or brings depletion earlier;
  • higher spending never raises either;
  • a later claim never lowers lifetime Social Security to 95;
  • taxes are never negative;
  • cash flow balances every year and the fixed point converges.
• Monte Carlo:
  • zero volatility reproduces the deterministic ledger;
  • bands are ordered and shares sum to one;
  • more savings never lowers the success rate, and higher spending never raises it (same seed);
  • the PRNG and lognormal moments, Cholesky, and exp/log within 1 ulp of the platform;
  • the benchmark;
  • worker-bundle parity.
• Coverage: at least 90% of engine lines.

7. Calculators

Every calculator runs on this engine with the same rules data. Four of them run a whole plan through §2 and §3. The rest are short formulas, given here. All use the mid-year convention of §1.

7.1 Retirement calculator

A one-person plan: a salary until the retirement age, savings into a traditional 401(k), Social Security at the claiming age, spending plus healthcare, and the planner's starting assumptions (§4). It is projected (§2) and simulated (§3) exactly as the planner would. With its default inputs it is the quick start's plan, and a test holds the two equal.

7.2 How much do I need to retire

• target = max(0, spending − other income) ÷ withdrawal rate.
• The real return is r = (1 + nominal) ÷ (1 + inflation) − 1.
• Savings grow at r: B(t + 1) = B(t) × (1 + r) + S × (1 + r/2). The years to the target are the first whole year with B ≥ target, looking up to 100 years ahead.
• The yearly savings that reach the target in n years: S = (target − B(0) × (1 + r)^n) ÷ ((1 + r/2) × Σ (1 + r)^k for k < n), never below zero.

7.3 Safe withdrawal rate

• The plan is a 65-year-old retiree with one tax-free (Roth) account, no other income, no healthcare line and no state tax.
• They spend the first year's withdrawal, then the same amount raised with inflation.
• The mix is fixed at the chosen stock share, the rest in bonds. Returns, fees and inflation are the planner's (§4).
• Success is the share of 1,000 simulated markets (§3) in which the money lasts the chosen number of years. The table reruns 3% to 6% on the same seed, so every rate faces the same markets.

7.4 Social Security claiming age

• The factors are §2.3's, for each whole age from 62 to 70, plus full retirement age when it isn't a whole year.
• The monthly benefit is factor × FRA benefit ÷ 12, in today's dollars (the COLA equals inflation). It is paid from the claim month, and totals count every month before the age entered.
• With a discount rate d, a payment in the k-th year after 62 counts ÷ (1 + d)^k.
• The break-even age is the first month at which the later claim's running total reaches the earlier claim's.

7.5 Required minimum distributions

The start age and the Uniform Lifetime Table are §2.6's. Each year, RMD = prior year-end balance ÷ period(age at year end), and the next balance is B × (1 + r) − RMD × (1 + r/2) at the return entered.

7.6 Roth conversions

• The plan is a retiree (and a spouse of the same age, when married) with traditional, Roth and taxable accounts, Social Security, and spending plus the planner's healthcare, to 95.
• It runs twice through §2 at expected returns: without conversions, and with fillBracket conversions (§2.7) from the start year to the year of the chosen age.
• ending after-tax value = ending total − ending pre-tax balance × ending tax rate. Amounts are in today's dollars.

7.7 401(k) with employer match

• The plan is a saver with a salary (growing at the real rate entered) and one traditional 401(k).
• It receives the entered share of salary and the employer match, within the limits of §2.4.
• It holds one asset at the entered return, with no fee, until the retirement age.
• The full-match comparison reruns it contributing the match's limit. Balances are in today's dollars.

7.8 Retirement savings by age

• The yearly need is W = max(0, spending − other income), every year from the retirement age R through the plan age P.
• The nest egg works back from zero: N(a) = (N(a + 1) + W × (1 + r/2)) ÷ (1 + r), from P down to R.
• On pace at age a is max(0, (N − F(a)) ÷ (1 + r)^(R − a)). Here F(a) is what saving the savings rate × salary each year from a grows to by R, with salary growing at the rate entered.
• Everything is real, at expected returns, before tax.

7.9 Catch-up contributions

• Age is tax year − birth year: the age reached by 31 December.
• Limits come straight from the year's published figures (§5), and every one must be published:
  • the 402(g) limit plus the 50-and-over catch-up, or the 60-to-63 catch-up;
  • 415(c), plus the catch-up;
  • the IRA limit, plus its 50-and-over catch-up;
  • the HSA limit, plus the statutory catch-up from 55.
• Catch-ups must be Roth when last year's FICA wages from the employer were over the threshold.

7.10 Compound growth

B(y) = B(y − 1) × (1 + r) + C(y) × (1 + r/2), with C(y) = C × (1 + c)^(y − 1). Today's dollars divide by (1 + inflation)^y. The doubling time is ln 2 ÷ ln(1 + r).

8. The pace baseline

When a member locks a plan (on first save, and whenever they choose to re-baseline), the engine records what the plan expects:

• Expected path: the total balance across accounts at 0, 12, 24, … months after the lock, in nominal dollars, at expected returns. Month 0 is the plan's opening balance.
• Median path: the Monte Carlo median total on the same grid, turned back into nominal dollars with each year's inflation factor.
• Success rate at the lock, with the runs, seed and engine version used.

Time runs from the lock, not from the plan's calendar start. The balances a member enters are today's, so the projection's first year is taken as the 12 months after the lock. Its tax years are still calendar years, a simplification that shifts when within the year a tax is paid, not how much. Between year ends the path is linear, month by month. Before the lock it holds at the opening balance, and past the plan's last year it holds at the final balance.