fundedness 0.2.3

A Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful visualizations

Financial Health Calculator

A comprehensive Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful Plotly visualizations.

Features

• CEFR (Certainty-Equivalent Funded Ratio): A fundedness metric that accounts for taxes, liquidity, and concentration risk
• Monte Carlo Simulations: Project retirement outcomes with configurable market assumptions
• Withdrawal Strategy Lab: Compare strategies including fixed SWR, guardrails, VPW, RMD-style, and Merton optimal
• Utility Optimization: Merton optimal spending and allocation based on lifetime utility maximization
• Beautiful Visualizations: Interactive Plotly charts with fan charts, waterfalls, and survival curves
• REST API: FastAPI backend for programmatic access
• Streamlit App: User-friendly web interface

Quick Start

Installation

pip install fundedness

For development with all extras:

pip install "fundedness[all]"

Basic Usage

from fundedness import Asset, BalanceSheet, Liability, compute_cefr
from fundedness.models.assets import AccountType, LiquidityClass, ConcentrationLevel

# Define your assets
assets = [
    Asset(
        name="401(k)",
        value=500_000,
        account_type=AccountType.TAX_DEFERRED,
        liquidity_class=LiquidityClass.RETIREMENT,
        concentration_level=ConcentrationLevel.DIVERSIFIED,
    ),
    Asset(
        name="Roth IRA",
        value=200_000,
        account_type=AccountType.TAX_EXEMPT,
        liquidity_class=LiquidityClass.RETIREMENT,
        concentration_level=ConcentrationLevel.DIVERSIFIED,
    ),
]

# Define your spending
liabilities = [
    Liability(name="Living Expenses", annual_amount=50_000, is_essential=True),
    Liability(name="Travel", annual_amount=20_000, is_essential=False),
]

# Calculate CEFR
result = compute_cefr(
    balance_sheet=BalanceSheet(assets=assets),
    liabilities=liabilities,
    planning_horizon=30,
)

print(f"CEFR: {result.cefr:.2f}")
print(f"Funded: {result.is_funded}")
print(result.get_interpretation())

Tutorials

• CEFR Basics - Introduction to the CEFR metric
• Time Distribution Analysis - Monte Carlo simulations
• Withdrawal Strategy Comparison - Compare different approaches

Running the Apps

Streamlit Web App

streamlit run streamlit_app/app.py

FastAPI REST API

uvicorn api.main:app --reload

API documentation available at http://localhost:8000/docs

Key Concepts

CEFR (Certainty-Equivalent Funded Ratio)

CEFR measures how well-funded your retirement is after accounting for:

• Tax Haircuts: What you'll owe when withdrawing from different account types
• Liquidity Haircuts: How easily you can access your assets
• Reliability Haircuts: Risk from concentrated positions

Formula:

CEFR = Σ(Asset × (1-τ) × λ × ρ) / PV(Liabilities)

Where τ = tax rate, λ = liquidity factor, ρ = reliability factor

Interpretation:

• CEFR ≥ 2.0: Excellent - Very well-funded
• CEFR 1.5-2.0: Strong - Well-funded with margin
• CEFR 1.0-1.5: Adequate - Fully funded
• CEFR < 1.0: Underfunded - Action needed

Withdrawal Strategies

Strategy	Description	Best For
Fixed SWR	4% of initial portfolio, adjusted for inflation	Predictability
% of Portfolio	Fixed % of current value	Market adaptation
Guardrails	Adjustable with floor/ceiling	Balance
VPW	Age-based variable percentage	Maximizing spending
RMD-Style	IRS distribution table based	Tax efficiency
Merton Optimal	Utility-maximizing spending rate	Optimality

Utility Optimization

The toolkit includes Merton's optimal consumption and portfolio choice framework, as applied in modern retirement planning research^[1]:

• Optimal Equity Allocation: k* = (μ - r) / (γ × σ²)
• Wealth-Adjusted Allocation: Reduces equity as wealth approaches subsistence floor
• Optimal Spending Rate: Increases with age as horizon shortens
• Expected Lifetime Utility: Track utility across Monte Carlo paths

Key insights from this methodology:

1. Optimal spending starts low (~2-3%) and rises with age
2. Allocation should decrease as wealth approaches the floor
3. Risk aversion (gamma) is the critical input parameter
4. The 4% rule is suboptimal from a utility perspective

Development

Setup

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

Running Tests

pytest

Code Quality

ruff check .
mypy fundedness

Project Structure

financial-health-calculator/
├── fundedness/           # Core Python package
│   ├── models/           # Pydantic data models
│   ├── viz/              # Plotly visualizations
│   ├── withdrawals/      # Withdrawal strategies (SWR, guardrails, VPW, Merton)
│   ├── allocation/       # Asset allocation strategies (constant, glidepath, Merton)
│   ├── cefr.py           # CEFR calculation
│   ├── simulate.py       # Monte Carlo engine with utility tracking
│   ├── merton.py         # Merton optimal formulas
│   ├── optimize.py       # Policy parameter optimization
│   └── policies.py       # Spending/allocation policies
├── api/                  # FastAPI REST API
├── streamlit_app/        # Streamlit web application
│   └── pages/            # Includes Utility Optimization page
├── examples/             # Jupyter notebooks
└── tests/                # pytest tests

Contact

• Twitter: @egr_investor
• GitHub: engineerinvestor
• Email: [e-mail]

License

MIT License

References

1. Haghani, V., & White, J. (2023). The Missing Billionaires: A Guide to Better Financial Decisions. Wiley. See also Elm Wealth for related research on optimal spending and allocation.

2. Merton, R. C. (1969). Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case. The Review of Economics and Statistics, 51(3), 247-257.

Citation

If you use this package in academic work, please cite:

@software{fundedness,
  title = {Fundedness: A Python Financial Planning Toolkit},
  author = {Engineer Investor},
  year = {2024},
  url = {https://github.com/engineerinvestor/financial-health-calculator},
  version = {0.2.1}
}

For the underlying methodology, please also cite:

@article{merton1969lifetime,
  title = {Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case},
  author = {Merton, Robert C.},
  journal = {The Review of Economics and Statistics},
  volume = {51},
  number = {3},
  pages = {247--257},
  year = {1969},
  publisher = {MIT Press}
}

@book{haghani2023missing,
  title = {The Missing Billionaires: A Guide to Better Financial Decisions},
  author = {Haghani, Victor and White, James},
  year = {2023},
  publisher = {Wiley}
}

Disclaimer

This tool is for educational purposes only and does not constitute financial advice. Consult a qualified financial advisor for personalized recommendations.