fundedness 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

fundedness/withdrawals/merton_optimal.py

@@ -0,0 +1,286 @@
+"""Merton optimal spending policy based on utility maximization."""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from fundedness.merton import (
+    merton_optimal_spending_rate,
+    certainty_equivalent_return,
+)
+from fundedness.models.market import MarketModel
+from fundedness.models.utility import UtilityModel
+from fundedness.withdrawals.base import (
+    BaseWithdrawalPolicy,
+    WithdrawalContext,
+    WithdrawalDecision,
+)
+
+
+@dataclass
+class MertonOptimalSpendingPolicy(BaseWithdrawalPolicy):
+    """Spending policy based on Merton optimal consumption theory.
+
+    This policy determines spending by applying the Merton optimal spending
+    rate to current wealth, adjusted for the remaining time horizon.
+
+    Key characteristics:
+    - Spending rate starts low (~2-3%) and rises with age
+    - Rate depends on risk aversion, time preference, and market assumptions
+    - Adapts to actual wealth (not locked to initial withdrawal amount)
+    - Optional smoothing to reduce year-to-year volatility
+
+    Attributes:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters including risk aversion
+        starting_age: Age at retirement/simulation start
+        end_age: Assumed maximum age for planning
+        smoothing_factor: Blend current with previous spending (0-1, 0=no smoothing)
+        min_spending_rate: Minimum spending rate floor
+        max_spending_rate: Maximum spending rate ceiling
+    """
+
+    market_model: MarketModel = field(default_factory=MarketModel)
+    utility_model: UtilityModel = field(default_factory=UtilityModel)
+    starting_age: int = 65
+    end_age: int = 100
+    smoothing_factor: float = 0.5
+    min_spending_rate: float = 0.02
+    max_spending_rate: float = 0.15
+
+    @property
+    def name(self) -> str:
+        return "Merton Optimal"
+
+    @property
+    def description(self) -> str:
+        gamma = self.utility_model.gamma
+        return f"Utility-optimal spending (gamma={gamma})"
+
+    def get_optimal_rate(self, remaining_years: float) -> float:
+        """Get the optimal spending rate for given remaining years.
+
+        Args:
+            remaining_years: Years until end of planning horizon
+
+        Returns:
+            Optimal spending rate as decimal
+        """
+        rate = merton_optimal_spending_rate(
+            market_model=self.market_model,
+            utility_model=self.utility_model,
+            remaining_years=remaining_years,
+        )
+        return np.clip(rate, self.min_spending_rate, self.max_spending_rate)
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate withdrawal using Merton optimal spending rate.
+
+        Args:
+            context: Current state information
+
+        Returns:
+            WithdrawalDecision with amount and metadata
+        """
+        # Determine current age
+        if context.age is not None:
+            current_age = context.age
+        else:
+            current_age = self.starting_age + context.year
+
+        remaining_years = max(1, self.end_age - current_age)
+
+        # Get optimal spending rate
+        rate = self.get_optimal_rate(remaining_years)
+
+        # Handle vectorized wealth
+        if isinstance(context.current_wealth, np.ndarray):
+            wealth = context.current_wealth
+        else:
+            wealth = context.current_wealth
+
+        # Calculate raw spending
+        raw_spending = wealth * rate
+
+        # Apply smoothing if we have previous spending
+        if self.smoothing_factor > 0 and context.previous_spending is not None:
+            # Adjust previous spending for inflation
+            prev_real = context.previous_spending / context.inflation_cumulative
+            smoothed = (
+                self.smoothing_factor * prev_real * context.inflation_cumulative
+                + (1 - self.smoothing_factor) * raw_spending
+            )
+            spending = smoothed
+        else:
+            spending = raw_spending
+
+        # Apply guardrails
+        amount, is_floor_breach, is_ceiling_hit = self.apply_guardrails(
+            spending, context.current_wealth
+        )
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Rate: {rate:.1%}, Remaining: {remaining_years}y",
+        )
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal.
+
+        Args:
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            First year withdrawal amount
+        """
+        remaining_years = self.end_age - self.starting_age
+        rate = self.get_optimal_rate(remaining_years)
+        return initial_wealth * rate
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending for simulation (vectorized interface).
+
+        This method is used by the Monte Carlo simulation engine.
+
+        Args:
+            wealth: Current portfolio values (n_simulations,)
+            year: Current simulation year
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Spending amounts for each simulation path
+        """
+        current_age = self.starting_age + year
+        remaining_years = max(1, self.end_age - current_age)
+        rate = self.get_optimal_rate(remaining_years)
+
+        spending = wealth * rate
+
+        # Ensure non-negative and bounded by wealth
+        spending = np.maximum(spending, 0)
+        spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        # Apply floor if set
+        if self.floor_spending is not None:
+            spending = np.maximum(spending, self.floor_spending)
+            # But still can't spend more than we have
+            spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        return spending
+
+
+@dataclass
+class SmoothedMertonPolicy(MertonOptimalSpendingPolicy):
+    """Merton optimal with aggressive smoothing for stable spending.
+
+    This variant applies stronger smoothing to reduce spending volatility,
+    trading off some optimality for a more stable spending experience.
+    """
+
+    smoothing_factor: float = 0.7
+    adaptation_rate: float = 0.1
+
+    @property
+    def name(self) -> str:
+        return "Smoothed Merton"
+
+    @property
+    def description(self) -> str:
+        return "Merton optimal with spending smoothing"
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get smoothed spending for simulation.
+
+        Uses exponential smoothing of the optimal spending amount.
+
+        Args:
+            wealth: Current portfolio values
+            year: Current simulation year
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Smoothed spending amounts
+        """
+        # Get raw Merton optimal spending
+        current_age = self.starting_age + year
+        remaining_years = max(1, self.end_age - current_age)
+        rate = self.get_optimal_rate(remaining_years)
+
+        optimal_spending = wealth * rate
+
+        # For first year or if tracking isn't set up, use optimal directly
+        # In practice, smoothing would be applied via simulation state
+        spending = optimal_spending
+
+        # Apply floor if set
+        if self.floor_spending is not None:
+            spending = np.maximum(spending, self.floor_spending)
+            spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        return spending
+
+
+@dataclass
+class FloorAdjustedMertonPolicy(MertonOptimalSpendingPolicy):
+    """Merton optimal that accounts for subsistence floor in spending.
+
+    This variant only applies the optimal rate to wealth above the
+    floor-supporting level, ensuring floor spending is always protected.
+    """
+
+    years_of_floor_to_protect: int = 5
+
+    @property
+    def name(self) -> str:
+        return "Floor-Protected Merton"
+
+    @property
+    def description(self) -> str:
+        return f"Merton optimal protecting {self.years_of_floor_to_protect}y floor"
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending that protects floor for several years.
+
+        Args:
+            wealth: Current portfolio values
+            year: Current simulation year
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Floor-protected spending amounts
+        """
+        current_age = self.starting_age + year
+        remaining_years = max(1, self.end_age - current_age)
+        rate = self.get_optimal_rate(remaining_years)
+
+        floor = self.utility_model.subsistence_floor
+        protected_wealth = floor * self.years_of_floor_to_protect
+
+        # Only apply rate to wealth above protected level
+        excess_wealth = np.maximum(wealth - protected_wealth, 0)
+        flex_spending = excess_wealth * rate
+
+        # Total spending = floor + flexible portion
+        spending = floor + flex_spending
+
+        # Can't spend more than we have
+        spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        return spending

{fundedness-0.1.0.dist-info → fundedness-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fundedness
-Version: 0.1.0
+Version: 0.2.1
 Summary: A Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful visualizations
 Project-URL: Homepage, https://github.com/engineerinvestor/financial-health-calculator
 Project-URL: Documentation, https://engineerinvestor.github.io/financial-health-calculator/
@@ -54,15 +54,22 @@ Description-Content-Type: text/markdown
 
 # Financial Health Calculator
 
-A comprehensive Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful Plotly visualizations.
-
+[![PyPI version](https://img.shields.io/pypi/v/fundedness.svg)](https://pypi.org/project/fundedness/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fundedness.svg)](https://pypi.org/project/fundedness/)
+[![CI](https://github.com/engineerinvestor/financial-health-calculator/actions/workflows/ci.yml/badge.svg)](https://github.com/engineerinvestor/financial-health-calculator/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/engineerinvestor/financial-health-calculator/branch/main/graph/badge.svg)](https://codecov.io/gh/engineerinvestor/financial-health-calculator)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://engineerinvestor.github.io/financial-health-calculator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/01_cefr_basics.ipynb)
 
+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, and RMD-style
+- **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
@@ -72,12 +79,12 @@ A comprehensive Python financial planning toolkit with CEFR calculations, Monte
 ### Installation
 
 ```bash
-pip install git+https://github.com/engineerinvestor/financial-health-calculator.git
+pip install fundedness
 ```
 
 For development with all extras:
 ```bash
-pip install "git+https://github.com/engineerinvestor/financial-health-calculator.git#egg=fundedness[all]"
+pip install "fundedness[all]"
 ```
 
 ### Basic Usage
@@ -176,6 +183,22 @@ Where τ = tax rate, λ = liquidity factor, ρ = reliability factor
 | 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<sup>[1]</sup>:
+
+- **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
 
@@ -207,13 +230,16 @@ financial-health-calculator/
 ├── fundedness/           # Core Python package
 │   ├── models/           # Pydantic data models
 │   ├── viz/              # Plotly visualizations
-│   ├── withdrawals/      # Withdrawal strategies
-│   ├── allocation/       # Asset allocation strategies
+│   ├── withdrawals/      # Withdrawal strategies (SWR, guardrails, VPW, Merton)
+│   ├── allocation/       # Asset allocation strategies (constant, glidepath, Merton)
 │   ├── cefr.py           # CEFR calculation
-│   ├── simulate.py       # Monte Carlo engine
+│   ├── 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
 ```
@@ -228,6 +254,12 @@ financial-health-calculator/
 
 MIT License
 
+## References
+
+1. Haghani, V., & White, J. (2023). *The Missing Billionaires: A Guide to Better Financial Decisions*. Wiley. See also [Elm Wealth](https://elmwealth.com/) 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.
+
 ## Disclaimer
 
 This tool is for educational purposes only and does not constitute financial advice. Consult a qualified financial advisor for personalized recommendations.

{fundedness-0.1.0.dist-info → fundedness-0.2.1.dist-info}/RECORD

@@ -1,14 +1,17 @@
-fundedness/__init__.py,sha256=P8LNYSUUlk4-8Wa34FlhCyA_echWenZvg1hk7ccdK58,735
+fundedness/__init__.py,sha256=7cGKTGVcoHzzjwZDy5yZ0N1bmDAXCFjWjf133dlVknQ,1678
 fundedness/cefr.py,sha256=hCImRrjz-DCPJsuF3HShDZK5tw1vslakh-DrNBHsh2k,7728
 fundedness/liabilities.py,sha256=uKvEV6JQnQdrd7b6VsCc2qf9S2DJdK0XhEX9qwca2Ws,6662
 fundedness/liquidity.py,sha256=ncZF70AfgoVoYZnozpA_CHemfaHmI4KKCe3vITp5ljM,1713
+fundedness/merton.py,sha256=VUKVxkNimoI0gsQJROb1wrO-SW4ubiNvcYDL2aH69AU,9218
+fundedness/optimize.py,sha256=21ksSkNgtDY_UGTub0KRlIvfaFA363csfSfHnLJrmJs,15567
 fundedness/policies.py,sha256=pyIYz86Z3sMYAW2rNhPLnXQ3PQCDCa-oxf9NhWyawy8,5854
 fundedness/risk.py,sha256=Lpls6Q2wVq5SX4p9ZQwCtTM73AcqrGCm3hE2QcgKuq0,2750
-fundedness/simulate.py,sha256=JOZeFx6oyOY2nyzejMgwPKnbNvzQZfYdslN-CwnxfwM,13769
-fundedness/allocation/__init__.py,sha256=6cYoAK3xbC6WphbAQ33XtHILCOY59NfXebpDXNeND18,408
+fundedness/simulate.py,sha256=A0_ZScMTF8YJcjVHys_nmxMG4x-c81sU_W8iMApscNE,19678
+fundedness/allocation/__init__.py,sha256=5p85uRFltSfEwXjengr56FNY1s4KvcMMxuH05I_Omfs,677
 fundedness/allocation/base.py,sha256=kDypu2t86fsn2DyL5an1fPjbPbQWNmqydz3axWUgjLI,763
 fundedness/allocation/constant.py,sha256=6QcUJ0aBQcJcRJtOMhs7uUu13wJtgcPU7ToQzQZhcgw,531
 fundedness/allocation/glidepath.py,sha256=-q6Jb5WpRuZjJ68akT5WgeRIx3QSIDtlNih0_Iz-_cc,3440
+fundedness/allocation/merton_optimal.py,sha256=krRd7sKbvXXxfewLJuF9RWbMLYUHbehvdbdYSjwnczk,7702
 fundedness/models/__init__.py,sha256=EyW6tGUI9T6QMbIfzsG3igqg5--DtZHSTAuMX6foOiA,874
 fundedness/models/assets.py,sha256=ZKgxl4YaqdRVfDErL9weRhh4St_azo8ruN4g15T3IsQ,5013
 fundedness/models/household.py,sha256=t64FjvO0uQJemddLtCPpK3NNYdZCXU6KjA1VZshaqEk,4671
@@ -17,22 +20,24 @@ fundedness/models/market.py,sha256=c3jskREsB7m_mjzuBwJ7oo6hlvLmR423t0JT8_a50eg,5
 fundedness/models/simulation.py,sha256=0jtIJWISDL-TlKVjr6KxcRfAj5Mrbp-VNyA4Bu7IUfU,2224
 fundedness/models/tax.py,sha256=0XhoBNZqfRqF1_acakrkYgMS5L6Pknq-TloQQBrFw1U,3859
 fundedness/models/utility.py,sha256=0AoJdccTb2hKBrTz5LExm8SrSsaWhhBf7y2NNaUzWQ0,4678
-fundedness/viz/__init__.py,sha256=PRP4PtkBr8PlO4Rz3AUPjj6dKL6168_0ogM8qSqoi-Q,687
+fundedness/viz/__init__.py,sha256=Om8qlI13w13MfDmyB_xeR6hgr7LpWX1tjAf_x3eDbEQ,1168
 fundedness/viz/colors.py,sha256=kbYyCLvLARoIAMztHjnJZDxMGF9-an5z4obORa6JFEU,3204
 fundedness/viz/comparison.py,sha256=DoQW6xr0r2ko55qyli4ue8ndj__opun97brbbHSnKVA,8530
 fundedness/viz/fan_chart.py,sha256=GqdrOKdW12K7Y8sFQJ853QbYG3ASxvEzfY9cC-EKK70,6102
 fundedness/viz/histogram.py,sha256=i56g330-S84WxUU8GGya40yNUQbnAI2D0vzUbFy51DI,6784
+fundedness/viz/optimal.py,sha256=w5vI2O-4O6F1Dobsfg55pznlfD100SRnSgZqLIpcT9c,16056
 fundedness/viz/survival.py,sha256=xtaAHkJ3jlTUCYnLrTvwWlOlfLao6NC5cRxT5XKWrxM,6515
 fundedness/viz/tornado.py,sha256=1dZzAfKTDCcyyfbDUBE39f44e6k48yviF8kTRee-pwQ,6684
 fundedness/viz/waterfall.py,sha256=6LD0SbZDUzJrA0Zh1Y1qDx0I4BM5ZN_f2eVCXNK5HRc,5586
-fundedness/withdrawals/__init__.py,sha256=v5wKqet3lNMr9UDMZC4d3UPOrRPbzQ6VvdP-ADAiBrg,646
+fundedness/withdrawals/__init__.py,sha256=FiXfK7QBzUp4Iwf25VK0jbZyguF8bLlZAWWMjg8tFPo,886
 fundedness/withdrawals/base.py,sha256=WXBuo-tJtp4V2Ottp2PC2YtyK3mGVJ9Cgq21zGUWObg,3472
 fundedness/withdrawals/comparison.py,sha256=eiobGMHmeQpGnr0_HcY_EKrv5_Nu7EaVf5Y9DdDNAyg,7833
-fundedness/withdrawals/fixed_swr.py,sha256=jwbVZHJuVzaSfDCpo-Zp6wdJmI-RzHvg46s1PFxhfA4,3639
+fundedness/withdrawals/fixed_swr.py,sha256=2ZgkQ_xZakpcdZQIop46TAFML7ESz7nyTVdVfI-1Z18,5469
 fundedness/withdrawals/guardrails.py,sha256=rZKVojKbl9LLJLi9LlK1I2JXb537MN_AbZfn4hIU8is,5468
+fundedness/withdrawals/merton_optimal.py,sha256=mSxRAKGx8sr_YdlhQMtIvnojqfuG0MiYtBp18xboLHs,9269
 fundedness/withdrawals/rmd_style.py,sha256=E5FfrUYxFJwULKxzxbtZFLoLspLzUUomTQRUWLGLDpg,6373
 fundedness/withdrawals/vpw.py,sha256=aajHLAkHfsxh33uGRgzv0ozVuZREG-EmARJgWOU6mis,4389
-fundedness-0.1.0.dist-info/METADATA,sha256=MLUiTj3UTO7RUaUhgbHk3ObQb173X44gpP6N9iK8tyM,8092
-fundedness-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fundedness-0.1.0.dist-info/entry_points.txt,sha256=Oh-Hg08i044YHuSHViCdfoD8CenIGcKrVuUVysvN9sY,51
-fundedness-0.1.0.dist-info/RECORD,,
+fundedness-0.2.1.dist-info/METADATA,sha256=Lg-LFdrLs2mcL9oyBjk3-X1qt9bB7U-K01zFHJXY6eI,10381
+fundedness-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fundedness-0.2.1.dist-info/entry_points.txt,sha256=Oh-Hg08i044YHuSHViCdfoD8CenIGcKrVuUVysvN9sY,51
+fundedness-0.2.1.dist-info/RECORD,,