monteplan

Monte Carlo financial planning simulator

Live App | PyPI | Documentation | Technical Paper | Notebooks | Try in Colab

monteplan models accumulation and decumulation with realistic taxes, multiple spending policies, multi-asset correlated portfolios, and professional reporting. Use it as a Python library, CLI tool, or interactive Streamlit web app.

Features

• Monte Carlo Engine -- Vectorized numpy simulation with monthly time steps and deterministic seeding
• 4 Return Models -- Multivariate normal, Student-t (fat tails), historical block bootstrap, Markov regime switching
• 5 Spending Policies -- Constant real, percent-of-portfolio, Guyton-Klinger guardrails, VPW, floor-and-ceiling
• Tax-Aware Withdrawals -- US federal progressive brackets, LTCG rates, RMD enforcement, configurable withdrawal ordering
• Multi-Account Support -- Taxable, traditional (401k/IRA), and Roth accounts with distinct tax treatment
• Guaranteed Income -- Social Security, pensions, and annuities with COLA adjustments
• Stress Testing -- Market crashes, lost decades, high inflation, and sequence-of-returns risk scenarios
• Sensitivity Analysis -- One-at-a-time tornado charts and 2D heatmaps with parallel execution
• Antithetic Variates -- Variance reduction for tighter confidence intervals
• Glide Paths -- Age-based target allocation shifts
• Investment Fees -- Expense ratios, AUM fees, and advisory fees as monthly drag
• Streamlit App -- Interactive web UI with Plotly charts, scenario comparison, and CSV export

Example Output

Quick Start

Python Library

from monteplan import simulate, default_plan, default_market, default_policies, default_sim_config

result = simulate(default_plan(), default_market(), default_policies(), default_sim_config())
print(f"Success probability: {result.success_probability:.1%}")

CLI

monteplan run --paths 10000 --seed 42

Streamlit App

Try the live app or run locally:

pip install monteplan[app]
streamlit run app/Home.py

Try It Now

Installation

Install from PyPI:

pip install monteplan

Or install from source:

git clone https://github.com/engineerinvestor/monteplan.git
cd monteplan
pip install -e ".[dev]"

Architecture

monteplan separates computation from presentation:

• Engine (src/monteplan/) -- Pure Python package with no UI dependencies
• App (app/) -- Streamlit web UI that imports the engine as a library
• Plugin-style models -- Return models, spending policies, and tax models are swappable via protocols

See the documentation for the full user guide, API reference, and mathematical details.

Disclaimer

This is an educational tool for exploring financial planning concepts. It is not financial advice. Results are simulations based on simplified models and assumptions. Consult a qualified financial advisor for real planning decisions.

License

Apache-2.0