End Game - Personal Finance Simulator for Retired Canadians

There's no guarantee that this tool outputs correct results. Use with caution!

The source code is here.

The instructions for running the code are here.

• Overview
• Limitations
• Features
• Example Scenarios

Scenario File

• General Syntax
  • The on statement
• Description of Snippets
  • syntax-version
  • description
  • number-of-iterations
  • simulation-start-date
  • simulation-end-date
  • date-of-birth
  • annual-test-for-survival
  • sex
  • year-zero-amounts
  • oas
  • cpp
  • rif-minimum-withdrawals
  • lif-maximum-withdrawals
  • federal-tax
  • provincial-tax
  • stocks
  • stock-commission
  • stock-price-policy
  • tfsa-room
  • accounts
  • sequential-liquidation
  • annual-tfsa-top-up
  • small-paycheck
• Description of Snippets - Transactions Block
  • transactions
  • bank-deposit
  • bank-withdrawal
  • move-cash
  • spend-bank-balance-above
  • sell-stock
  • buy-stock
  • buy-gic
  • transfer-stock-in
  • transfer-stock-out
  • move-stock
  • annuity-payment
  • stock-split

Overview

• to help you explore different retirement scenarios
• to help you find a better financial plan for your retirement

This tool is focused almost entirely on the retirement phase of life (spending), not on the working phase of life (saving). It can be useful even if you aren't close to retirement, by letting you explore how cash flow works in retirement.

The main steps in using this tool:

• you first create a scenario file, which describes your assets, accounts, date of retirement, and so on. The scenario file is a text file, whose syntax follows certain rules defined by this tool (see below).
• using the scenario file as input, you run this tool to generate output files.
• the output files are all text files, and are placed in the same folder as the input scenario file.
• the output consists of .csv files containing summary data, and a log file. The log file shows the activity in your accounts, yearly tax returns, and so on.
• usually, you'll want to import the .csv files into a spreadsheet tool (MS Excel, Google Sheets, Open Office) and make some charts.

An example chart made with Open Office (cash-and-tax-summary.csv):

An example chart made with Google Sheets (cash-flows.csv):

A second example chart made with Google Sheets. This chart shows the scatter in net cash flow when a certain policy for selling shares reacts to stock prices generated using a probability distribution. In this case, the simulation has been run 20 times by the system, with stock prices being different each time. After 2027, the points below the main body of points are years in which stock prices were low and no stocks were sold, resulting in lower cash flow:

The level of detail in this tool is higher than usual. Whereas most tools focus on a high-level rate of return, this tool actually goes through every single day of your retirement, and applies transactions to your accounts. It includes a basic tax return at the end of each year.

Every retirement financial plan should be supported by a robust simulation showing you the details. Personal finance is quite complex. There are many moving parts, and how those parts all work together in your particular case can be found only with a simulator. You can't do these calculations in your head, and you shouldn't rely entirely on rules of thumb, because such rules usually have exceptions.

This tool has:

• helped me find thousands of dollars in additional cash flow
• increased my level of confidence in my financial plan
• helped me answer many different questions
• helped me in speaking to a financial advisor

Limitations

• there's no spousal logic.
• the set of supported securities is very limited at present: only cash, stocks, GICs, and simple annuities. ETFs can usually be approximated as a stock.
• the set of supported account types is : TFSA, RSP/RIF, LIRA/LIF, non-registered accounts (referred to as NRA here), and simple bank accounts. RSPs are supported in a limited way, because no contributions are allowed.
• only one account of each account type is supported.
• there's no logic specific to insurance, debt, real estate, charitable donations, and so on.
• all amounts are assumed to be in Canadian dollars, and multiple currencies aren't supported

Features

• input-output using text files
• the input text file is a scenario, a text file describing details of your accounts, assets, transactions, start-date for retirement, expected CPP benefit, pension, and so on
• internally, the system runs through every single day of your entire retirement life, and applies transactions defined in your scenario file
• some scenarios have randomness, and some don't
• the randomness only comes from variation in the market price of securities
• basic tax returns are calculated, both federal and provincial (territories not included at present)
• the output is in .csv (comma-separated values) files, which are easily imported into spreadsheet tools such as Google Sheets or Open Office (and thereby charted)
• the logging output shows transactions, yearly summaries, tax returns, and so on
• you can repeat a scenario multiple times, to reflect the spread in outcomes caused by variations in market prices (Monte Carlo simulation)
• the tool can run multiple scenarios in sequence
• the code is implemented in Java, and can be run on any computer
• changes to the market prices of stock are applied once a year
• all amounts are in real dollars (you don't input an inflation rate anywhere)

Some items that aren't modeled explicitly can still be effectively modeled by the system. For example, the sale of a primary residence can be modeled as a simple windfall deposited to your bank account, since no tax is paid on the capital gain when you sell your home. From there, the cash can be transferred into an investment account to buy securities.

There are two distinct types of scenarios:

• those with precisely predictable cash flows (OAS, CPP, GIS, annuities, pensions)
• those without precisely predictable cash flows (assets vary in value with the market price)

Examples of approximations made by the tool:

• stock prices are updated just once a year (using a policy you define)
• stocks pay eligible dividends only
• GICs are always held in the account until they are redeemed
• the tax return is calculated and applied simply at the end of the year, and not later in the following year
• OAS clawbacks are applied (for high income earners) all in one year; in reality, the clawback is applied over 2 calendar years
• the life-table stats from Statistics Canada are for the Canada-wide case, not for the specific province

Example Scenarios

When creating your own scenario, it's always best to start with a working example. Then you gradually change the scenario, step by step, to get closer to your own case. As you make a small edit, you save your changes and test them by running the tool, to see if everything still works. You keep repeating this until you get to your desired final scenario. This is the safest way of proceeding.

Note that the .ini file is the scenario file, and the remaining files in the directory are outputs that result from executing the scenario. The provincial tax return is for PE, Prince Edward Island, simply because that's where the author resides. The tool allows for all other provinces as well.

General Syntax

It's almost always best to start with an example scenario file that is closest to your situation. Then you gradually modify it, one piece at a time.

Note that:

• a leading # character means that following text is a comment
• usually, the order of items in the file is fixed
• an exception is the transactions block at the end. Separate transactions in the transactions block can appear in any order.

The on statement

There's a special on syntax for controlling when transactions are applied, and it occurs in various places. Examples:

bank-withdrawal 925.00 on *-01

on 2027-11-25

on *-11-25

on *-03-01,*-06-01,*-09-01,*-12-01

sell 6.0% on *-11-26 | 2027-01-01..2034-12-31

# start-date and end-date:
sell 6.0% on *-11-26 | 2027-01-01..2034-12-31  
# only start-date:
sell 6.0% on *-11-26 | 2027-01-01..           
 # only end-date:
sell 6.0% on *-11-26 | ..2034-12-31

buy-gic rif "Cda Trust" 5700.00 2.5% 1-year : 2024-06-21

Description of Snippets

Some examples have various alternatives. One of the alternatives will be the active one, while the others are all commented out because the line starts with a '#' sign. This lets you quickly change alternatives, by commenting out everything except the one you really want.

Outside of the transactions block, items are usually required. Any optional items are indicated as such below.

syntax-version = v1.0.0

description = "101.6: Fixed 3% growth in stock prices..."

number-of-iterations = 1

simulation-start-date = 2022-01-01
simulation-end-date = 2042-12-31

date-of-birth = 1962-05-21
annual-test-for-survival
sex = male

year-zero-amounts {
  net-income-before-adjustments = 15180.00  # line 23400
  net-income = 15180.00 # line 23600
  oas-income = 0.00
  employment-income = 0.00  
}

oas {
  monthly-amount-at-65 = 648.67 # as of 2022-06
  start-month = 2027-06  # month of first payment 
  payment-day = 28 # day of the month; never more than 28
  
  clawback-threshold = 81761.00 # line 23400 of tax return
  clawback-percent = 15%
  monthly-reward = 0.7% # for every month delayed past 65
  boost-age = 75 # the age at which OAS is boosted by 10%
  boost-percent = 10%
  start-window-begin = 65 
  start-window-end = 70
  gis-employment-exemption = 5000.00
}

For both OAS and CPP, there are (in a sense) two start-months. One is used to calculate the amount of the payment, and the other (1 month later) is the month you actually receive the first payment.

cpp { 
  # can be used for QPP as well, since they 
  # have nearly the same core logic
  nominal-monthly-amount = 850.00 # if starts at age 65
  start-month = 2022-06           # month of 1st payment 
  payment-day = 28   # day of the month
  
  monthly-reward = 0.7%   # every month delayed past 65
  monthly-penalty = 0.6%  # every month started before 65
  start-window-begin = 60 
  start-nominal = 65
  start-window-end = 70
  survivor-benefit-amount = 1000.00    # optional
  survivor-benefit-start = 2030-02-25  # optional
}

rif-minimum-withdrawals {
 # Applied to the market value of the RIF at 
 # the start of each year.
 # The left-hand side is your age on Jan 1. 
 # For ages outside this range, a formula applies
 71 = 5.28%
 72 = 5.40%
 ...elided for brevity...
 93 = 16.34%
 94 = 18.79%
}

lif-maximum-withdrawals {
  # WARNING: should be updated every year.
  # Applied to the market value of the LIF at the 
  # start of each year. No max for PE.
  # AGE, RIF-MIN, CA, MN-QC-NS, AB-BC-ON-NB-NL-SK
  55 2.86% 4.53% 6.40% 6.51%
  56 2.94% 4.58% 6.50% 6.57%
  57 3.03% 4.64% 6.50% 6.63%
  ...elided for brevity...
  93 16.34% 100.00% 20.00% 100.00%
  94 18.79% 100.00% 20.00% 100.00%
  95 20.00% 100.00% 20.00% 100.00%
  # older: just use the last row
}

federal-tax {
  # Tax return settings.
  # These numbers are for 2021. 
  # Update them each year.
  # Must agree with simulation-start-date: 
  initial-year = 2022 
  personal-amount = 12241.00  # Worksheet for line 30000
  personal-amount-additional = 1387.00
  personal-amount-threshold = 151978.00_216511.00
  age-amount = 7713.00 # Worksheet line 30100
  age-amount-threshold = 38893.00
  pension-income-max = 2000.00 # line 31400
  tax-brackets {
    15.00% : 49020.00    
    20.50% : 98040.00    
    26.00% : 151978.00   
    29.00% : 216511.00   
    33.00% : 100000000.00
  }
  rif-withholding-tax-brackets {
    # these amounts are above the rif's 
    # minimum withdrawal for that year
    10.00% : 5000.00    
    20.00% : 15000.00    
    30.00% : 100000000.00
  }
  standard-retirement-age = 65
  taxable-capital-gain-fraction = 0.5D
  dividend-tax-credit-numer = 6 
  dividend-tax-credit-denom = 11 
}

provincial-tax {
  # Usually there are significant differences 
  # between jurisdictions!
  # Each jurisdiction has its own set of fields.
  # Numbers from 2021 
  jurisdiction = PE 
  tax-brackets {
    9.8% : 31984.00    
    13.8% : 63969.00    
    16.7% : 100000000.00
  }
  personal-amount = 10500.00 # line 58040
  age-amount = 3764.00 # line 58080
  age-amount-threshold = 28019.00
  pension-income-max = 1000.00 # line 58360
  dividend-gross-up-mult = 10.5% # line 61520 worksheet
  low-income-basic = 350.00 # line 63370 
  low-income-age = 250.00 # line 63380
  low-income-threshold = 19000.00 # line 85
  low-income-rate = 5.00%
}

stocks {
  # Initial data on stocks
  # Not related to an account.
  # All stocks in the sim must be defined here, 
  # even those you don't own at the start.
  "ABC" {   
    price = 56.00
    dividend {
      on *-03-01,*-06-01,*-09-01,*-12-01
      amount = 0.86
      growth = 4.0%
    }
  }
  "XYZ" {
    price = 140.00
    dividend {
     on *-01-28,*-04-28,*-07-28,*-10-28
     amount = 1.61
     growth = 4.0%
    }
  }
}

#percent of the gross amount: 
stock-commission = fixed-percent 1.0%     
# some discount brokers have a flat rate:
# stock-commission = fixed-amount 10.50
# requires custom coding:    
# stock-commission = custom-schedule

stock-price-policy {
  on *-11-25 # when stock prices are to be updated
  # gaussian mean = 5.0%  std-dev = 5.0% 
  # range = -5%_10%
  fixed = 3% # no randomness here
  # in order of year; recycles if end is reached:
  # explicit-list = 5%,5%,5%,5%,5%,-7% 
}

tfsa-room {
  initial-room = 18500.00  
  yearly-limit = 6000.00
}

accounts { 
  # Initial account holdings.
  # In this simulation, you can have only up to 
  # 1 account of each account-type.
  # Only the bank account is required. 
  # The others are optional.
  bank {
    cash = 10000.00
    small-balance-limit = 4000.00
  }
  rif {
    convert-rsp-to-rif = 2018-05-01
    cash = 0.00
    stock-positions {
      2000 "ABC"
      800 "XYZ"
      900 "CLU"
    }
  }
  lif {
    convert-lira-to-lif = 2018-05-01
    jurisdiction = ON
    cash = 10.00
    stock-positions {
      50 "ENB"
      100 "CM"
      150 "XEG"
    }
    gic-positions {
     "Canada Trust" 1500.00 2.25% 2-year matures 2023-03-15
    }
  }
  tfsa {
    cash = 0.00
    stock-positions {
      1000 "ABC"
      200 "XYZ"
    }
  }
  nra {
    cash = 283.90
    stock-positions {
      340 "ABC"
      290 "XYZ"
    }
    gic-positions {
     "Home Trust" 7500.00 2.35% 2-year matures 2023-03-15
    }
    stock-book-values {
      33000.00 "XYZ"
      15000.00 "ABC"
    }
  }
}

sequential-liquidation {
  avoid-downturn-years = 2 
  account-sequence = rif,nra,tfsa
  stock-sequence = "clu,xyz,abc"
  sell 6.0% on *-11-26 | 2027-01-01..2034-12-31 
  sell 3.0% on *-11-26 | 2035-01-01.. 
}

annual-tfsa-top-up {
  account-sequence = rif,nra
  stock-sequence = "abc,xyz"
  on *-01-03                
}

small-paycheck 50.00 on *-15 | 2024-01-01..2026-12-31
small-paycheck 150.00 on *-15 | 2026-01-01..2027-12-31

Description of Snippets - Transactions Block

transactions {
  # Transactions in your accounts, 
  # not yet defined implicitly.
  ...
}

• they can appear in any order
• they are all optional
• they can appear 0, 1, or N times

bank-deposit 925.00 on *-01 
bank-withdrawal 105.25 on 2027-05-01

move-cash from nra to bank 1500.00 on *-01
move-cash from rif to bank on *-06-01,*-12-01

spend-bank-balance-above 5000.00 on *-15

sell-stock rif 952 shares "ABC" on 2022-06-20
buy-stock rif 952 shares "ABC" on 2022-06-20

buy-gic rif "Home Trust" 7500.00 2.5% 1-year : 2022-06-21

transfer-stock-in tfsa 100 shares "ABC" on 2027-05-15 
transfer-stock-out rif 1500.00 "ABC" on 2027-05-15

move-stock from rif to tfsa 100 shares "ABC" on 2027-05-15
move-stock from rif to tfsa 7500.00 "ABC" on 2027-05-15

annuity-payment 2000.00 on *-25 | 2027-05-25..

stock-split 2-to-1 "ABC" on 2027-05-12