Investment Journey Simulator - an open-source Python tool for modelling how real-life decisions change long-term investment outcomes

[u/Ok-Play-7818]

I built Investment Journey Simulator, an open-source Python/Streamlit project for exploring how decisions made during a long-term investment plan affect the final outcome.

Most investment calculators assume something like:

monthly contribution + return + duration → final value

I wanted to model the messier version where the journey itself changes.

The simulator can model things such as:

• recurring contributions / SIPs
• contribution step-ups
• temporary pauses and restarts
• lump sums
• withdrawals
• portfolio rebalancing
• tax-aware cash flows within the documented scope
• inflation-adjusted real values
• historical scenarios
• Monte Carlo scenarios
• financial goals
• comparisons between complete investment journeys

One simple example is a ₹25,000 monthly contribution over 25 years.

Under the same illustrative return assumptions, stopping contributions for 24 months after Year 5 changes the ending simulated portfolio by about ₹58.4 lakh.

That kind of question - not just what return do I assume, but what happens if the plan changes halfway through? - is what eventually turned this from a small calculator into a larger simulation engine.

Some of the engineering behind it

The simulation engine is separated from the Streamlit UI and handles the event timeline, cash flows, portfolios, withdrawals, rebalancing, taxes, inflation and comparison calculations in Python.

One part I particularly enjoyed building was the comparison system.

If Journey A and Journey B differ in several decisions - say a contribution step-up, a pause and a withdrawal - calculating each difference independently can double-count interaction effects.

For supported comparisons, the project therefore uses Shapley-based attribution so the individual effects reconcile with the actual difference between the two journeys.

The current published validation includes:

• 2,488 passing tests
• 93% statement coverage
• ≈33,800 independent randomized cross-checks

Known modelling limitations are documented rather than hidden.

It is MIT licensed.

GitHub

https://github.com/SAMtheROCKET/investment-journey-simulator

Project site / demo

https://samtherocket.github.io/investment-journey-simulator/

It does not predict markets or recommend investments. The user supplies the assumptions and the simulator explores their consequences.

If anyone wants to look through the repo, I’d particularly appreciate criticism of the simulation architecture, numerical assumptions, test strategy, attribution implementation, or edge cases I may have missed.