fundedness 0.2.2__py3-none-any.whl

fundedness/withdrawals/base.py

@@ -0,0 +1,116 @@
+"""Base classes for withdrawal strategies."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import numpy as np
+
+
+@dataclass
+class WithdrawalContext:
+    """Context information for making a withdrawal decision."""
+
+    current_wealth: float | np.ndarray
+    initial_wealth: float
+    year: int
+    age: int | None = None
+    inflation_cumulative: float = 1.0  # Cumulative inflation since start
+    previous_spending: float | np.ndarray | None = None
+    market_return_ytd: float | None = None  # Year-to-date market return
+
+
+@dataclass
+class WithdrawalDecision:
+    """Result of a withdrawal decision."""
+
+    amount: float | np.ndarray
+    is_floor_breach: bool | np.ndarray = False
+    is_ceiling_hit: bool | np.ndarray = False
+    notes: str = ""
+
+
+class WithdrawalPolicy(Protocol):
+    """Protocol defining the interface for withdrawal strategies."""
+
+    @property
+    def name(self) -> str:
+        """Human-readable name for the strategy."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Brief description of how the strategy works."""
+        ...
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate the withdrawal amount for the given context.
+
+        Args:
+            context: Current state information
+
+        Returns:
+            WithdrawalDecision with amount and metadata
+        """
+        ...
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate the first year's withdrawal.
+
+        Args:
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            First year withdrawal amount
+        """
+        ...
+
+
+@dataclass
+class BaseWithdrawalPolicy:
+    """Base class with common functionality for withdrawal policies."""
+
+    floor_spending: float | None = None
+    ceiling_spending: float | None = None
+
+    def apply_guardrails(
+        self,
+        amount: float | np.ndarray,
+        wealth: float | np.ndarray,
+    ) -> tuple[float | np.ndarray, bool | np.ndarray, bool | np.ndarray]:
+        """Apply floor and ceiling guardrails to withdrawal amount.
+
+        Args:
+            amount: Proposed withdrawal amount
+            wealth: Current wealth
+
+        Returns:
+            Tuple of (adjusted_amount, is_floor_breach, is_ceiling_hit)
+        """
+        is_floor_breach = False
+        is_ceiling_hit = False
+
+        # Apply floor
+        if self.floor_spending is not None:
+            if isinstance(amount, np.ndarray):
+                is_floor_breach = amount < self.floor_spending
+                amount = np.maximum(amount, self.floor_spending)
+            else:
+                is_floor_breach = amount < self.floor_spending
+                amount = max(amount, self.floor_spending)
+
+        # Apply ceiling
+        if self.ceiling_spending is not None:
+            if isinstance(amount, np.ndarray):
+                is_ceiling_hit = amount > self.ceiling_spending
+                amount = np.minimum(amount, self.ceiling_spending)
+            else:
+                is_ceiling_hit = amount > self.ceiling_spending
+                amount = min(amount, self.ceiling_spending)
+
+        # Can't withdraw more than we have
+        if isinstance(amount, np.ndarray) or isinstance(wealth, np.ndarray):
+            amount = np.minimum(amount, np.maximum(wealth, 0))
+        else:
+            amount = min(amount, max(wealth, 0))
+
+        return amount, is_floor_breach, is_ceiling_hit

fundedness/withdrawals/comparison.py

@@ -0,0 +1,230 @@
+"""Withdrawal strategy comparison framework."""
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from fundedness.models.simulation import SimulationConfig
+from fundedness.simulate import SimulationResult, generate_returns
+from fundedness.withdrawals.base import WithdrawalContext, WithdrawalPolicy
+
+
+@dataclass
+class StrategyComparisonResult:
+    """Results from comparing multiple withdrawal strategies."""
+
+    strategy_names: list[str]
+    results: dict[str, SimulationResult]
+    metrics: dict[str, dict[str, Any]]
+
+    def get_summary_table(self) -> dict[str, list]:
+        """Get a summary table of key metrics across strategies."""
+        return {
+            "Strategy": self.strategy_names,
+            "Success Rate": [
+                self.metrics[name]["success_rate"] for name in self.strategy_names
+            ],
+            "Median Terminal Wealth": [
+                self.metrics[name]["median_terminal_wealth"] for name in self.strategy_names
+            ],
+            "Median Spending (Year 1)": [
+                self.metrics[name]["median_initial_spending"] for name in self.strategy_names
+            ],
+            "Spending Volatility": [
+                self.metrics[name]["spending_volatility"] for name in self.strategy_names
+            ],
+            "Floor Breach Rate": [
+                self.metrics[name]["floor_breach_rate"] for name in self.strategy_names
+            ],
+        }
+
+
+def run_strategy_simulation(
+    policy: WithdrawalPolicy,
+    initial_wealth: float,
+    config: SimulationConfig,
+    stock_weight: float = 0.6,
+    starting_age: int = 65,
+    spending_floor: float | None = None,
+) -> SimulationResult:
+    """Run a Monte Carlo simulation with a specific withdrawal strategy.
+
+    Args:
+        policy: Withdrawal policy to use
+        initial_wealth: Starting portfolio value
+        config: Simulation configuration
+        stock_weight: Asset allocation to stocks
+        starting_age: Starting age for age-based strategies
+        spending_floor: Minimum acceptable spending
+
+    Returns:
+        SimulationResult with paths and metrics
+    """
+    n_sim = config.n_simulations
+    n_years = config.n_years
+    seed = config.random_seed
+
+    # Generate returns
+    returns = generate_returns(
+        n_simulations=n_sim,
+        n_years=n_years,
+        market_model=config.market_model,
+        stock_weight=stock_weight,
+        random_seed=seed,
+    )
+
+    # Initialize paths
+    wealth_paths = np.zeros((n_sim, n_years + 1))
+    wealth_paths[:, 0] = initial_wealth
+    spending_paths = np.zeros((n_sim, n_years))
+
+    time_to_ruin = np.full(n_sim, np.inf)
+    time_to_floor_breach = np.full(n_sim, np.inf) if spending_floor else None
+
+    previous_spending = None
+
+    # Simulate year by year
+    for year in range(n_years):
+        current_wealth = wealth_paths[:, year]
+
+        # Create context
+        context = WithdrawalContext(
+            current_wealth=current_wealth,
+            initial_wealth=initial_wealth,
+            year=year,
+            age=starting_age + year,
+            previous_spending=previous_spending,
+        )
+
+        # Get withdrawal decision
+        decision = policy.calculate_withdrawal(context)
+        spending = decision.amount
+
+        spending_paths[:, year] = spending
+        previous_spending = spending
+
+        # Track floor breach
+        if time_to_floor_breach is not None and spending_floor:
+            floor_breach_mask = (spending < spending_floor) & np.isinf(time_to_floor_breach)
+            time_to_floor_breach[floor_breach_mask] = year
+
+        # Update wealth
+        wealth_after_spending = np.maximum(current_wealth - spending, 0)
+        wealth_paths[:, year + 1] = wealth_after_spending * (1 + returns[:, year])
+
+        # Track ruin
+        ruin_mask = (wealth_paths[:, year + 1] <= 0) & np.isinf(time_to_ruin)
+        time_to_ruin[ruin_mask] = year + 1
+
+    # Calculate percentiles
+    wealth_percentiles = {}
+    spending_percentiles = {}
+
+    for p in config.percentiles:
+        key = f"P{p}"
+        wealth_percentiles[key] = np.percentile(wealth_paths[:, 1:], p, axis=0)
+        spending_percentiles[key] = np.percentile(spending_paths, p, axis=0)
+
+    terminal_wealth = wealth_paths[:, -1]
+
+    return SimulationResult(
+        wealth_paths=wealth_paths[:, 1:],
+        spending_paths=spending_paths,
+        time_to_ruin=time_to_ruin,
+        time_to_floor_breach=time_to_floor_breach,
+        wealth_percentiles=wealth_percentiles,
+        spending_percentiles=spending_percentiles,
+        success_rate=np.mean(np.isinf(time_to_ruin)),
+        floor_breach_rate=np.mean(~np.isinf(time_to_floor_breach)) if time_to_floor_breach is not None else 0.0,
+        median_terminal_wealth=np.median(terminal_wealth),
+        mean_terminal_wealth=np.mean(terminal_wealth),
+        n_simulations=n_sim,
+        n_years=n_years,
+        random_seed=seed,
+    )
+
+
+def compare_strategies(
+    policies: list[WithdrawalPolicy],
+    initial_wealth: float,
+    config: SimulationConfig,
+    stock_weight: float = 0.6,
+    starting_age: int = 65,
+    spending_floor: float | None = None,
+) -> StrategyComparisonResult:
+    """Compare multiple withdrawal strategies using the same random draws.
+
+    Args:
+        policies: List of withdrawal policies to compare
+        initial_wealth: Starting portfolio value
+        config: Simulation configuration
+        stock_weight: Asset allocation to stocks
+        starting_age: Starting age for age-based strategies
+        spending_floor: Minimum acceptable spending
+
+    Returns:
+        StrategyComparisonResult with all results and metrics
+    """
+    strategy_names = [p.name for p in policies]
+    results = {}
+    metrics = {}
+
+    # Use same seed for all strategies for fair comparison
+    base_seed = config.random_seed or 42
+
+    for i, policy in enumerate(policies):
+        # Use same seed for reproducibility
+        config_copy = SimulationConfig(
+            n_simulations=config.n_simulations,
+            n_years=config.n_years,
+            random_seed=base_seed,
+            market_model=config.market_model,
+            tax_model=config.tax_model,
+            utility_model=config.utility_model,
+            percentiles=config.percentiles,
+        )
+
+        result = run_strategy_simulation(
+            policy=policy,
+            initial_wealth=initial_wealth,
+            config=config_copy,
+            stock_weight=stock_weight,
+            starting_age=starting_age,
+            spending_floor=spending_floor,
+        )
+
+        results[policy.name] = result
+
+        # Calculate additional metrics
+        spending_paths = result.spending_paths
+        if spending_paths is not None:
+            # Spending volatility (coefficient of variation of spending changes)
+            spending_changes = np.diff(spending_paths, axis=1) / spending_paths[:, :-1]
+            spending_volatility = np.nanstd(spending_changes)
+
+            # Median initial spending
+            median_initial_spending = np.median(spending_paths[:, 0])
+
+            # Average spending
+            avg_spending = np.mean(spending_paths)
+        else:
+            spending_volatility = 0
+            median_initial_spending = 0
+            avg_spending = 0
+
+        metrics[policy.name] = {
+            "success_rate": result.success_rate,
+            "floor_breach_rate": result.floor_breach_rate,
+            "median_terminal_wealth": result.median_terminal_wealth,
+            "mean_terminal_wealth": result.mean_terminal_wealth,
+            "median_initial_spending": median_initial_spending,
+            "average_spending": avg_spending,
+            "spending_volatility": spending_volatility,
+        }
+
+    return StrategyComparisonResult(
+        strategy_names=strategy_names,
+        results=results,
+        metrics=metrics,
+    )

fundedness/withdrawals/fixed_swr.py

@@ -0,0 +1,174 @@
+"""Fixed Safe Withdrawal Rate (SWR) policy."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fundedness.withdrawals.base import (
+    BaseWithdrawalPolicy,
+    WithdrawalContext,
+    WithdrawalDecision,
+)
+
+
+@dataclass
+class FixedRealSWRPolicy(BaseWithdrawalPolicy):
+    """Classic fixed real (inflation-adjusted) withdrawal strategy.
+
+    The "4% rule" approach: withdraw a fixed percentage of initial portfolio,
+    then adjust for inflation each year.
+    """
+
+    withdrawal_rate: float = 0.04  # 4% default
+    inflation_rate: float = 0.025  # 2.5% expected inflation
+
+    @property
+    def name(self) -> str:
+        return f"Fixed {self.withdrawal_rate:.1%} SWR"
+
+    @property
+    def description(self) -> str:
+        return (
+            f"Withdraw {self.withdrawal_rate:.1%} of initial portfolio in year 1, "
+            f"then adjust for {self.inflation_rate:.1%} inflation annually."
+        )
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        return initial_wealth * self.withdrawal_rate
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate inflation-adjusted withdrawal.
+
+        Args:
+            context: Current state including initial wealth and year
+
+        Returns:
+            WithdrawalDecision with fixed real amount
+        """
+        # Base withdrawal from initial wealth
+        base_amount = context.initial_wealth * self.withdrawal_rate
+
+        # Adjust for cumulative inflation
+        inflation_factor = (1 + self.inflation_rate) ** context.year
+        nominal_amount = base_amount * inflation_factor
+
+        # Apply guardrails and wealth cap
+        amount, is_floor_breach, is_ceiling_hit = self.apply_guardrails(
+            nominal_amount, context.current_wealth
+        )
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Year {context.year}: base ${base_amount:,.0f} × {inflation_factor:.3f} inflation",
+        )
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending for simulation (vectorized interface).
+
+        Args:
+            wealth: Current portfolio values (n_simulations,)
+            year: Current simulation year
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Spending amounts for each simulation path
+        """
+        # Base withdrawal from initial wealth
+        base_amount = initial_wealth * self.withdrawal_rate
+
+        # Adjust for cumulative inflation
+        inflation_factor = (1 + self.inflation_rate) ** year
+        spending = np.full_like(wealth, base_amount * inflation_factor)
+
+        # Apply floor if set
+        if self.floor_spending is not None:
+            spending = np.maximum(spending, self.floor_spending)
+
+        # Can't spend more than we have
+        spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        return spending
+
+
+@dataclass
+class PercentOfPortfolioPolicy(BaseWithdrawalPolicy):
+    """Withdraw a fixed percentage of current portfolio value each year.
+
+    More volatile than fixed SWR but automatically adjusts to portfolio performance.
+    """
+
+    withdrawal_rate: float = 0.04
+    floor: float | None = None
+
+    @property
+    def name(self) -> str:
+        return f"{self.withdrawal_rate:.1%} of Portfolio"
+
+    @property
+    def description(self) -> str:
+        return f"Withdraw {self.withdrawal_rate:.1%} of current portfolio value each year."
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        return initial_wealth * self.withdrawal_rate
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate percentage-of-portfolio withdrawal.
+
+        Args:
+            context: Current state including current wealth
+
+        Returns:
+            WithdrawalDecision based on current portfolio value
+        """
+        if isinstance(context.current_wealth, np.ndarray):
+            amount = context.current_wealth * self.withdrawal_rate
+        else:
+            amount = context.current_wealth * self.withdrawal_rate
+
+        # 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,
+        )
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending for simulation (vectorized interface).
+
+        Args:
+            wealth: Current portfolio values (n_simulations,)
+            year: Current simulation year
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Spending amounts for each simulation path
+        """
+        spending = wealth * self.withdrawal_rate
+
+        # Apply floor if set
+        floor = self.floor or self.floor_spending
+        if floor is not None:
+            spending = np.maximum(spending, floor)
+
+        # Can't spend more than we have
+        spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        return spending

fundedness/withdrawals/guardrails.py

@@ -0,0 +1,136 @@
+"""Guardrails withdrawal strategy (Guyton-Klinger style)."""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from fundedness.withdrawals.base import (
+    BaseWithdrawalPolicy,
+    WithdrawalContext,
+    WithdrawalDecision,
+)
+
+
+@dataclass
+class GuardrailsPolicy(BaseWithdrawalPolicy):
+    """Guyton-Klinger style guardrails withdrawal strategy.
+
+    Start with initial withdrawal rate, then adjust based on portfolio performance:
+    - If withdrawal rate rises above upper guardrail, cut spending
+    - If withdrawal rate falls below lower guardrail, increase spending
+    - Otherwise, adjust previous spending for inflation
+    """
+
+    initial_rate: float = 0.05  # Starting withdrawal rate (5%)
+    upper_guardrail: float = 0.06  # Cut spending if rate exceeds this
+    lower_guardrail: float = 0.04  # Raise spending if rate falls below this
+    cut_amount: float = 0.10  # Cut spending by 10% when hitting upper rail
+    raise_amount: float = 0.10  # Raise spending by 10% when hitting lower rail
+    inflation_rate: float = 0.025
+    no_raise_in_down_year: bool = True  # Don't raise spending after negative returns
+
+    _initial_spending: float = field(default=0.0, init=False, repr=False)
+
+    @property
+    def name(self) -> str:
+        return "Guardrails"
+
+    @property
+    def description(self) -> str:
+        return (
+            f"Start at {self.initial_rate:.1%}, adjust for inflation, but cut by "
+            f"{self.cut_amount:.0%} if rate > {self.upper_guardrail:.1%} or raise by "
+            f"{self.raise_amount:.0%} if rate < {self.lower_guardrail:.1%}."
+        )
+
+    def get_initial_withdrawal(self, initial_wealth: float) -> float:
+        """Calculate first year withdrawal."""
+        self._initial_spending = initial_wealth * self.initial_rate
+        return self._initial_spending
+
+    def calculate_withdrawal(self, context: WithdrawalContext) -> WithdrawalDecision:
+        """Calculate guardrails-adjusted withdrawal.
+
+        Args:
+            context: Current state including previous spending and market returns
+
+        Returns:
+            WithdrawalDecision with guardrail-adjusted amount
+        """
+        # Get previous spending (or calculate initial)
+        if context.previous_spending is None or context.year == 0:
+            if isinstance(context.current_wealth, np.ndarray):
+                base_spending = np.full_like(
+                    context.current_wealth,
+                    context.initial_wealth * self.initial_rate,
+                )
+            else:
+                base_spending = context.initial_wealth * self.initial_rate
+        else:
+            # Inflation-adjust previous spending
+            base_spending = context.previous_spending * (1 + self.inflation_rate)
+
+        # Calculate current withdrawal rate
+        if isinstance(context.current_wealth, np.ndarray):
+            current_rate = np.where(
+                context.current_wealth > 0,
+                base_spending / context.current_wealth,
+                np.inf,
+            )
+        else:
+            current_rate = (
+                base_spending / context.current_wealth
+                if context.current_wealth > 0
+                else float("inf")
+            )
+
+        # Apply guardrails
+        amount = base_spending
+
+        if isinstance(current_rate, np.ndarray):
+            # Vectorized guardrail logic
+            # Cut spending if above upper guardrail
+            above_upper = current_rate > self.upper_guardrail
+            amount = np.where(above_upper, amount * (1 - self.cut_amount), amount)
+
+            # Raise spending if below lower guardrail (unless down year rule)
+            below_lower = current_rate < self.lower_guardrail
+            if self.no_raise_in_down_year and context.market_return_ytd is not None:
+                below_lower = below_lower & (context.market_return_ytd >= 0)
+            amount = np.where(below_lower, amount * (1 + self.raise_amount), amount)
+
+            is_ceiling_hit = below_lower  # Hit ceiling = spending was raised
+            is_floor_breach = above_upper  # Hit floor = spending was cut
+        else:
+            is_floor_breach = False
+            is_ceiling_hit = False
+
+            if current_rate > self.upper_guardrail:
+                amount = amount * (1 - self.cut_amount)
+                is_floor_breach = True
+            elif current_rate < self.lower_guardrail:
+                can_raise = True
+                if self.no_raise_in_down_year and context.market_return_ytd is not None:
+                    can_raise = context.market_return_ytd >= 0
+                if can_raise:
+                    amount = amount * (1 + self.raise_amount)
+                    is_ceiling_hit = True
+
+        # Apply absolute floor/ceiling
+        amount, floor_breach, ceiling_hit = self.apply_guardrails(
+            amount, context.current_wealth
+        )
+
+        if isinstance(is_floor_breach, np.ndarray):
+            is_floor_breach = is_floor_breach | floor_breach
+            is_ceiling_hit = is_ceiling_hit | ceiling_hit
+        else:
+            is_floor_breach = is_floor_breach or floor_breach
+            is_ceiling_hit = is_ceiling_hit or ceiling_hit
+
+        return WithdrawalDecision(
+            amount=amount,
+            is_floor_breach=is_floor_breach,
+            is_ceiling_hit=is_ceiling_hit,
+            notes=f"Current rate: {np.mean(current_rate) if isinstance(current_rate, np.ndarray) else current_rate:.2%}",
+        )