fundedness 0.2.4__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/withdrawals/rmd_style.py

@@ -0,0 +1,203 @@
+"""RMD-style withdrawal strategy."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fundedness.withdrawals.base import (
+    BaseWithdrawalPolicy,
+    WithdrawalContext,
+    WithdrawalDecision,
+)
+
+
+# IRS Uniform Lifetime Table (2024)
+# Maps age to distribution period (divisor)
+RMD_TABLE = {
+    72: 27.4, 73: 26.5, 74: 25.5, 75: 24.6, 76: 23.7,
+    77: 22.9, 78: 22.0, 79: 21.1, 80: 20.2, 81: 19.4,
+    82: 18.5, 83: 17.7, 84: 16.8, 85: 16.0, 86: 15.2,
+    87: 14.4, 88: 13.7, 89: 12.9, 90: 12.2, 91: 11.5,
+    92: 10.8, 93: 10.1, 94: 9.5, 95: 8.9, 96: 8.4,
+    97: 7.8, 98: 7.3, 99: 6.8, 100: 6.4, 101: 6.0,
+    102: 5.6, 103: 5.2, 104: 4.9, 105: 4.6, 106: 4.3,
+    107: 4.1, 108: 3.9, 109: 3.7, 110: 3.5, 111: 3.4,
+    112: 3.3, 113: 3.1, 114: 3.0, 115: 2.9, 116: 2.8,
+    117: 2.7, 118: 2.5, 119: 2.3, 120: 2.0,
+}
+
+
+def get_rmd_divisor(age: int) -> float:
+    """Get RMD distribution period for given age.
+
+    Args:
+        age: Current age
+
+    Returns:
+        Distribution period (divisor)
+    """
+    if age < 72:
+        # Extrapolate backwards (not actual RMD, but useful for strategy)
+        return 27.4 + (72 - age) * 1.0  # Approximate slope
+    elif age > 120:
+        return 2.0
+    else:
+        return RMD_TABLE.get(age, 2.0)
+
+
+@dataclass
+class RMDStylePolicy(BaseWithdrawalPolicy):
+    """RMD-style withdrawal strategy.
+
+    Uses IRS Required Minimum Distribution table to determine withdrawals.
+    Withdrawal = Portfolio Value / Distribution Period
+
+    This approach automatically increases withdrawal rate as you age,
+    similar to how RMDs work for tax-deferred accounts.
+    """
+
+    starting_age: int = 65
+    multiplier: float = 1.0  # Scale factor (1.0 = exact RMD, 1.5 = 150% of RMD)
+    start_before_72: bool = True  # Apply RMD-style before actual RMD age
+
+    @property
+    def name(self) -> str:
+        mult_str = f" × {self.multiplier}" if self.multiplier != 1.0 else ""
+        return f"RMD-Style{mult_str}"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Withdraw based on IRS RMD table divisors. "
+            "Withdrawal rate automatically increases with age."
+        )
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        divisor = get_rmd_divisor(self.starting_age)
+        return (initial_wealth / divisor) * self.multiplier
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate RMD-style withdrawal.
+
+        Args:
+            context: Current state including age or year
+
+        Returns:
+            WithdrawalDecision based on RMD table
+        """
+        # Determine current age
+        if context.age is not None:
+            current_age = context.age
+        else:
+            current_age = self.starting_age + context.year
+
+        # Get divisor
+        divisor = get_rmd_divisor(current_age)
+
+        # Calculate withdrawal
+        if isinstance(context.current_wealth, np.ndarray):
+            amount = (context.current_wealth / divisor) * self.multiplier
+        else:
+            amount = (context.current_wealth / divisor) * self.multiplier
+
+        # Apply guardrails
+        amount, is_floor_breach, is_ceiling_hit = self.apply_guardrails(
+            amount, context.current_wealth
+        )
+
+        withdrawal_rate = 1 / divisor * self.multiplier
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Age {current_age}, divisor: {divisor:.1f}, rate: {withdrawal_rate:.2%}",
+        )
+
+
+@dataclass
+class AmortizationPolicy(BaseWithdrawalPolicy):
+    """Amortization-based withdrawal strategy.
+
+    Treats the portfolio like a mortgage in reverse - calculates the level
+    payment that would exhaust the portfolio over the planning horizon
+    given expected returns.
+    """
+
+    starting_age: int = 65
+    planning_age: int = 95  # Age to plan to
+    expected_return: float = 0.04  # Expected real return
+    recalculate_annually: bool = True  # Recalculate each year
+
+    @property
+    def name(self) -> str:
+        return "Amortization"
+
+    @property
+    def description(self) -> str:
+        return (
+            f"Calculate level payment to exhaust portfolio by age {self.planning_age} "
+            f"assuming {self.expected_return:.1%} real return."
+        )
+
+    def _calculate_pmt(self, wealth: float, years_remaining: int) -> float:
+        """Calculate amortization payment.
+
+        PMT = PV * r / (1 - (1+r)^-n)
+        """
+        if years_remaining <= 0:
+            return wealth  # Spend it all
+
+        r = self.expected_return
+        n = years_remaining
+
+        if r == 0:
+            return wealth / n
+
+        # Standard amortization formula
+        pmt = wealth * r / (1 - (1 + r) ** (-n))
+        return pmt
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        years = self.planning_age - self.starting_age
+        return self._calculate_pmt(initial_wealth, years)
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate amortization-based withdrawal.
+
+        Args:
+            context: Current state
+
+        Returns:
+            WithdrawalDecision based on amortization formula
+        """
+        # Determine current age and years remaining
+        if context.age is not None:
+            current_age = context.age
+        else:
+            current_age = self.starting_age + context.year
+
+        years_remaining = max(1, self.planning_age - current_age)
+
+        # Calculate payment
+        if isinstance(context.current_wealth, np.ndarray):
+            amount = np.array([
+                self._calculate_pmt(w, years_remaining)
+                for w in context.current_wealth
+            ])
+        else:
+            amount = self._calculate_pmt(context.current_wealth, years_remaining)
+
+        # Apply guardrails
+        amount, is_floor_breach, is_ceiling_hit = self.apply_guardrails(
+            amount, context.current_wealth
+        )
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Years remaining: {years_remaining}",
+        )

fundedness/withdrawals/vpw.py

@@ -0,0 +1,136 @@
+"""Variable Percentage Withdrawal (VPW) strategy."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fundedness.withdrawals.base import (
+    BaseWithdrawalPolicy,
+    WithdrawalContext,
+    WithdrawalDecision,
+)
+
+
+# VPW percentage table based on age and asset allocation
+# Source: Bogleheads VPW methodology
+# These are the percentages of portfolio to withdraw at each age
+VPW_TABLE = {
+    # Age: {stock_pct: withdrawal_pct}
+    # Simplified table - in practice would interpolate
+    60: {0: 0.037, 25: 0.039, 50: 0.042, 75: 0.046, 100: 0.051},
+    65: {0: 0.041, 25: 0.044, 50: 0.047, 75: 0.052, 100: 0.058},
+    70: {0: 0.047, 25: 0.050, 50: 0.054, 75: 0.060, 100: 0.068},
+    75: {0: 0.054, 25: 0.058, 50: 0.064, 75: 0.071, 100: 0.081},
+    80: {0: 0.064, 25: 0.069, 50: 0.076, 75: 0.086, 100: 0.099},
+    85: {0: 0.078, 25: 0.084, 50: 0.093, 75: 0.106, 100: 0.124},
+    90: {0: 0.097, 25: 0.106, 50: 0.118, 75: 0.135, 100: 0.160},
+    95: {0: 0.127, 25: 0.139, 50: 0.156, 75: 0.180, 100: 0.214},
+}
+
+
+def get_vpw_rate(age: int, stock_allocation: int = 50) -> float:
+    """Get VPW withdrawal rate for given age and allocation.
+
+    Args:
+        age: Current age
+        stock_allocation: Stock allocation as integer percentage (0-100)
+
+    Returns:
+        Withdrawal rate as decimal
+    """
+    # Find bracketing ages
+    ages = sorted(VPW_TABLE.keys())
+
+    if age <= ages[0]:
+        age_key = ages[0]
+    elif age >= ages[-1]:
+        age_key = ages[-1]
+    else:
+        # Find closest age
+        age_key = min(ages, key=lambda x: abs(x - age))
+
+    # Find closest allocation
+    allocations = sorted(VPW_TABLE[age_key].keys())
+    if stock_allocation <= allocations[0]:
+        alloc_key = allocations[0]
+    elif stock_allocation >= allocations[-1]:
+        alloc_key = allocations[-1]
+    else:
+        alloc_key = min(allocations, key=lambda x: abs(x - stock_allocation))
+
+    return VPW_TABLE[age_key][alloc_key]
+
+
+@dataclass
+class VPWPolicy(BaseWithdrawalPolicy):
+    """Variable Percentage Withdrawal (VPW) strategy.
+
+    Withdrawal rate varies based on age and remaining life expectancy.
+    Uses actuarial tables to determine appropriate withdrawal percentage.
+    """
+
+    starting_age: int = 65
+    stock_allocation: int = 50  # As integer percentage
+    smoothing_factor: float = 0.0  # 0 = pure VPW, 1 = fully smoothed
+
+    @property
+    def name(self) -> str:
+        return "VPW"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Variable Percentage Withdrawal based on age and life expectancy. "
+            "Withdrawal rate increases as you age."
+        )
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        rate = get_vpw_rate(self.starting_age, self.stock_allocation)
+        return initial_wealth * rate
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate VPW withdrawal.
+
+        Args:
+            context: Current state including age or year
+
+        Returns:
+            WithdrawalDecision based on VPW table
+        """
+        # Determine current age
+        if context.age is not None:
+            current_age = context.age
+        else:
+            current_age = self.starting_age + context.year
+
+        # Get VPW rate for current age
+        vpw_rate = get_vpw_rate(current_age, self.stock_allocation)
+
+        # Calculate base withdrawal
+        if isinstance(context.current_wealth, np.ndarray):
+            base_amount = context.current_wealth * vpw_rate
+        else:
+            base_amount = context.current_wealth * vpw_rate
+
+        # Apply smoothing if requested
+        if self.smoothing_factor > 0 and context.previous_spending is not None:
+            smoothed = (
+                self.smoothing_factor * context.previous_spending
+                + (1 - self.smoothing_factor) * base_amount
+            )
+            amount = smoothed
+        else:
+            amount = base_amount
+
+        # Apply guardrails
+        amount, is_floor_breach, is_ceiling_hit = self.apply_guardrails(
+            amount, context.current_wealth
+        )
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Age {current_age}, VPW rate: {vpw_rate:.2%}",
+        )