https://github.com/policyengine/finsim
Financial simulation tool for comparing annuities, investments, and retirement strategies with tax-aware Monte Carlo modeling
https://github.com/policyengine/finsim
Last synced: 7 months ago
JSON representation
Financial simulation tool for comparing annuities, investments, and retirement strategies with tax-aware Monte Carlo modeling
- Host: GitHub
- URL: https://github.com/policyengine/finsim
- Owner: PolicyEngine
- Created: 2025-08-09T10:10:37.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-08-19T09:44:24.000Z (8 months ago)
- Last Synced: 2025-08-27T20:31:49.906Z (7 months ago)
- Language: Python
- Size: 1.62 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# FinSim by PolicyEngine
A comprehensive financial simulation tool for comparing annuities with index fund investments, accounting for taxes, Social Security benefits, and mortality risk.
## Features
- **Annuity Analysis**: Compare multiple annuity proposals with IRR calculations
- **Monte Carlo Simulation**: Model index fund performance with customizable parameters
- **Tax Integration**: Uses PolicyEngine-US for accurate federal and state tax calculations
- **Social Security**: Includes COLA adjustments based on SSA uprating factors
- **Interactive Visualizations**: Portfolio paths, depletion probabilities, and tax impacts
## Installation
Using [uv](https://github.com/astral-sh/uv) (recommended):
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/PolicyEngine/finsim
cd finsim
# Create virtual environment and install
uv venv
uv pip install -e ".[app]"
```
Or with pip:
```bash
pip install finsim
# For the Streamlit app:
pip install "finsim[app]"
```
## Usage
### Important: Always Use `uv run`
⚠️ **Always use `uv run` to execute Python commands** to ensure the correct environment and dependencies:
```bash
# ✅ Correct
uv run streamlit run app.py
uv run python script.py
uv run pytest tests/
# ❌ Wrong - may cause numpy/PolicyEngine compatibility issues
streamlit run app.py
python script.py
pytest tests/
```
Run the Streamlit app:
```bash
uv run streamlit run app.py
```
## Components
### 1. Monte Carlo Simulator (`monte_carlo.py`)
- Simulates index fund performance (default: VT Total World Stock)
- Configurable returns, volatility, and dividend yields
- Calculates depletion probabilities and portfolio percentiles
- Supports dividend reinvestment strategies
### 2. Tax Calculator (`tax_calculator.py`)
- Integrates PolicyEngine-US for precise tax modeling
- Handles:
- Long-term capital gains with basis tracking
- Social Security benefit taxation
- OBBBA senior deduction ($6,000 for 2025)
- Federal and state taxes
- Projects SS benefits with COLA adjustments
### 3. Annuity Calculator (`annuity.py`)
- Calculates internal rate of return (IRR)
- Supports both fixed-term and life-contingent annuities
- Uses CDC mortality tables for survival weighting
- Handles taxable vs. tax-free (§104(a)(2)) annuities
### 4. Streamlit Interface (`app.py`)
- Input forms for:
- Personal information (age, state, filing status)
- Settlement amount
- Social Security benefits
- Multiple annuity proposals
- Interactive visualizations:
- Monte Carlo simulation paths with percentile bands
- Distribution of final portfolio values
- Tax impact analysis
- Capital gains inclusion ratio over time
## Key Assumptions
- **Default Index Fund**: VT (Vanguard Total World Stock)
- Expected return: 8% annually
- Volatility: 15.8% annually
- Dividend yield: 2% annually
- **Tax Treatment**:
- Personal injury settlements under IRC §104(a)(2) are tax-free
- Index fund gains start at ~20% taxable fraction, increasing over time
- California state tax applies; no tax on Social Security benefits
- **Social Security**:
- Annual COLA adjustments based on CPI-W
- Up to 85% taxable at federal level depending on income
## Example Scenarios
### Your Father's Case
- Age: 65
- Settlement: $527,530
- Social Security: $2,000/month
- State: California
- Three annuity proposals with varying terms and IRRs
The tool shows:
- Proposal A (life contingent): Lower monthly payment but longevity protection
- Proposal B (15-year certain): Higher IRR, fixed term
- Proposal C (10-year certain): Highest monthly payment, shortest term
- Index fund alternative: Higher expected return but ~20-35% depletion risk
## Data Tracking
The simulation maintains complete arrays for every simulation path and year:
- **Portfolio Evolution**: Start/end values, cost basis tracking
- **Income Components**: Dividends, capital gains, Social Security (with COLA), pensions, annuities
- **Withdrawal Mechanics**: Gross withdrawals, taxable portions, net after-tax amounts
- **Tax Tracking**: Taxes owed (current year) vs. paid (prior year liability)
- **Life Events**: Mortality status, portfolio depletion year, estate values
- **Inflation Adjustments**: SSA COLA (CPI-W) for Social Security, C-CPI-U for consumption
This comprehensive tracking enables detailed analysis of success rates, tax efficiency, and withdrawal strategies across thousands of Monte Carlo scenarios.
## Limitations
- Mortality tables are simplified (CDC averages, not personalized)
- Tax calculations assume current law continues
- Market return assumptions based on historical data
- Does not model healthcare costs or long-term care needs
- State tax calculations limited to major states
## Contributing
Feel free to submit issues or pull requests to improve the tool.
## License
MIT