End Game: Personal finance simulator for retired Canadians

End Game - Personal Finance Simulator for Retired Canadians

The main documentation is here.

Getting Started

This is a guide for running the code using the Eclipse tool. You only have to do these steps once. It takes about 20 minutes.

Step 1 - Folders and Source Code

First, create a workspace folder on your machine.

When you launch Eclipse, you need to point to a workspace folder. A workspace folder contains project folders. Each project folder contains the source code for a project.

These instructions will use a workspace named:

C:\myworkspace\

An example setup:

C:\myworkspace\            [the workspace folder]
  C:\myworkspace\end-game  [the project folder for end-game]
    ./settings
    docs            
    input             
    lib               [the various files and folders in the end-game project]
    scenario
    src
    .classpath
    .gitignore
    .project
    LICENSE.txt
    README.md

Your setup will be similar, except you can replace C:\myworkspace\ with something else, if you wish.

Next, you need to put the source code into the above folder structure:

go to the github repository
click on the Code button
click on Download ZIP
copy the end-game-master.zip file to your workspace folder
unzip the file
change the name of the new folder from end-game-master to end-game
your folders should now follow the pattern shown above!

Step 2 - Install and Run Eclipse

Install and run Eclipse, following these steps:

Download the Eclipse installer.

Run the installer, and select Eclipse IDE for Java Developers (if it it prompts you about licenses, just accept the license):

Install Eclipse to a convenient location on your computer:

Launch Eclipse, and point it to the workspace directory you created earlier:

The first time you launch Eclipse, it will show you a welcome screen. Close the welcome screen:

Now you will see the main Eclipse window:

Step 3 - Import the end-game Project into Eclipse

Now that you have Eclipse running, it's time to point it to the end-game project and its source code.

Click on Import Projects. Or, from the menu, select File -> Import...

Choose General -> Existing Projects into Workspace:

Point to the end-game project folder:

The result should look like this:

Step 4 - Run an Example Scenario

On the left, open the src folder, and then the endgame folder. Double click on the RunSimulation file (this is called a class in Java). This is the main class that launches the tool. The task is to point it to a given scenario file. To get started, we'll point it to an existing scenario file that comes with the source code.

There are two ways of pointing to the scenario file. The easiest way is Style #1. If your workspace is different from C:\workspace\, then you will need to change one line to point to your actual workspace, and then save the change using the menu, File -> Save.

Finally, to run the scenario and generate its output, in the menu select Run -> Run As... -> Java application. That will generate logging output to something called the Console window. It will also generate new .csv files that summarize the results. The log file and .csv files are saved to the same directory as the scenario itself.

Once you have run RunSimulation the first time, there are shortcuts for re-running the most recent execution:

hit the green button in the tool bar at the top
hit the two keys Ctrl and F11 at the same time

The RunMultipleSimulations class works in a similar way. The only difference is that it is passed a top-level folder that contains multiple scenario folders.

Step 5 - Create your own Scenario

Now you are ready to experiment with your own scenarios. You can place the scenario file anywhere you want. But most will find it convenient to follow the existing structure established with the example scenarios, all located under the scenario folder in the project. The idea is simple: you just create a new folder for each scenario.

Of course, in order to run your new scenario, you will need to point the RunSimulation class to the scenario file, using the method described above.

Common Kinds of Errors

There are two common kinds of error you may see. First, take the case of a syntax error in the scenario file, where you have mistakenly typed:

ban-withdrawal 925.00 on *-02

which should be:

bank-withdrawal 925.00 on *-02

When you try to run the code using that scenario file, you'll see an error message in the Console window, and it will tell you the exact location of the problem (in this case, line 230 and column 6 of the scenario file):

endgame.input.syntax.TokenMgrError: Lexical error at line 230, column 6.  Encountered: "-" (45), after : "ban"
  at endgame.input.syntax.ScenarioParserTokenManager.getNextToken(ScenarioParserTokenManager.java:4529)
  at endgame.input.syntax.ScenarioParser.jj_ntk(ScenarioParser.java:1910)
  at endgame.input.syntax.ScenarioParser.transactions(ScenarioParser.java:1284)
  at endgame.input.syntax.ScenarioParser.all(ScenarioParser.java:194)
  at endgame.input.syntax.ScenarioParser.parseInput(ScenarioParser.java:70)
  at endgame.input.syntax.ScenarioParser.parse(ScenarioParser.java:55)
  at endgame.RunSimulation.readInputFile(RunSimulation.java:168)
  at endgame.RunSimulation.run(RunSimulation.java:105)
  at endgame.RunSimulation.main(RunSimulation.java:71)

This is called a stack trace.

A different sort of error can occur later, after the scenario file has been successfully read and parsed. An example is an operation that's not allowed for some reason. For instance, if you try to withdraw too much money from your bank account, you'll see this error message in the Console window:

java.lang.RuntimeException: You're trying to withdraw 85000.00 but you only have 7130.27.
  at endgame.bank.BankAccount.withdrawCash(BankAccount.java:32)
  at endgame.bank.BankDepositWithdrawal.execute(BankDepositWithdrawal.java:30)
  at endgame.transaction.Transactional.executeOnDate(Transactional.java:34)
  at endgame.RunSimulation.transactionsUpdateThe(RunSimulation.java:240)
  at endgame.RunSimulation.run(RunSimulation.java:123)
  at endgame.RunSimulation.main(RunSimulation.java:71)

Step 6 (Optional) - Install the JavaCC plugin

You can skip this if you wish. It's for advanced users. The JavaCC tool lets you change ScenarioParser.jj, which defines the syntax of the scenario file. When you save changes to that file, JavaCC will automatically generate a number of Java classes. Those classes do the actual parsing of the scenario file.

To install the JavaCC plugin into Eclipse:

from the menu, select Help -> Eclipse Marketplace
in the Find box, enter javacc and hit Enter
click the Install button for the JavaCC plugin

Updating the Code

You may wish to get an updated version of the code. To do that, just repeat the process described above, but use a different zip name and project name, for example end-game-02. This will ensure you don't accidentally overwrite the previous version. It's especially important to not lose or overwrite any scenario files you have made.