fundedness 0.2.2__py3-none-any.whl

fundedness/__init__.py

@@ -0,0 +1,71 @@
+"""Fundedness: A Python financial planning toolkit.
+
+This package provides tools for:
+- CEFR (Certainty-Equivalent Funded Ratio) calculations
+- Monte Carlo retirement simulations
+- Withdrawal strategy comparison
+- Utility-optimal spending and allocation (Merton framework)
+- Beautiful Plotly visualizations
+"""
+
+__version__ = "0.2.2"
+
+from fundedness.cefr import CEFRResult, compute_cefr
+from fundedness.merton import (
+    MertonOptimalResult,
+    calculate_merton_optimal,
+    certainty_equivalent_return,
+    merton_optimal_allocation,
+    merton_optimal_spending_rate,
+    optimal_allocation_by_wealth,
+    optimal_spending_by_age,
+    wealth_adjusted_optimal_allocation,
+)
+from fundedness.models import (
+    Asset,
+    BalanceSheet,
+    Household,
+    Liability,
+    MarketModel,
+    Person,
+    SimulationConfig,
+    TaxModel,
+    UtilityModel,
+)
+from fundedness.simulate import (
+    SimulationResult,
+    run_simulation,
+    run_simulation_with_policy,
+    run_simulation_with_utility,
+)
+
+__all__ = [
+    "__version__",
+    # CEFR
+    "compute_cefr",
+    "CEFRResult",
+    # Merton optimal
+    "calculate_merton_optimal",
+    "certainty_equivalent_return",
+    "merton_optimal_allocation",
+    "merton_optimal_spending_rate",
+    "MertonOptimalResult",
+    "optimal_allocation_by_wealth",
+    "optimal_spending_by_age",
+    "wealth_adjusted_optimal_allocation",
+    # Simulation
+    "run_simulation",
+    "run_simulation_with_policy",
+    "run_simulation_with_utility",
+    "SimulationResult",
+    # Models
+    "Asset",
+    "BalanceSheet",
+    "Household",
+    "Liability",
+    "MarketModel",
+    "Person",
+    "SimulationConfig",
+    "TaxModel",
+    "UtilityModel",
+]

fundedness/allocation/__init__.py

@@ -0,0 +1,20 @@
+"""Asset allocation strategy implementations."""
+
+from fundedness.allocation.base import AllocationPolicy
+from fundedness.allocation.constant import ConstantAllocationPolicy
+from fundedness.allocation.glidepath import AgeBasedGlidepathPolicy, RisingEquityGlidepathPolicy
+from fundedness.allocation.merton_optimal import (
+    FloorProtectionAllocationPolicy,
+    MertonOptimalAllocationPolicy,
+    WealthBasedAllocationPolicy,
+)
+
+__all__ = [
+    "AllocationPolicy",
+    "AgeBasedGlidepathPolicy",
+    "ConstantAllocationPolicy",
+    "FloorProtectionAllocationPolicy",
+    "MertonOptimalAllocationPolicy",
+    "RisingEquityGlidepathPolicy",
+    "WealthBasedAllocationPolicy",
+]

fundedness/allocation/base.py

@@ -0,0 +1,32 @@
+"""Base class for allocation policies."""
+
+from typing import Protocol
+
+import numpy as np
+
+
+class AllocationPolicy(Protocol):
+    """Protocol defining the interface for allocation strategies."""
+
+    @property
+    def name(self) -> str:
+        """Human-readable name for the strategy."""
+        ...
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float | np.ndarray:
+        """Get the stock allocation for the given context.
+
+        Args:
+            wealth: Current portfolio value(s)
+            year: Current year in simulation
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Stock allocation as decimal (0-1)
+        """
+        ...

fundedness/allocation/constant.py

@@ -0,0 +1,25 @@
+"""Constant allocation policy."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class ConstantAllocationPolicy:
+    """Maintain a constant stock/bond allocation."""
+
+    stock_weight: float = 0.6
+
+    @property
+    def name(self) -> str:
+        return f"{self.stock_weight:.0%} Stocks"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Return constant stock allocation."""
+        return self.stock_weight

fundedness/allocation/glidepath.py

@@ -0,0 +1,111 @@
+"""Glidepath allocation policies."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class AgeBasedGlidepathPolicy:
+    """Traditional declining equity glidepath based on age.
+
+    Classic approach: reduce equity allocation as you age to reduce
+    sequence-of-returns risk.
+    """
+
+    initial_stock_weight: float = 0.7
+    final_stock_weight: float = 0.3
+    years_to_final: int = 30
+
+    @property
+    def name(self) -> str:
+        return f"Glidepath ({self.initial_stock_weight:.0%} → {self.final_stock_weight:.0%})"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate stock allocation based on years into retirement."""
+        progress = min(year / self.years_to_final, 1.0)
+        stock_weight = self.initial_stock_weight - progress * (
+            self.initial_stock_weight - self.final_stock_weight
+        )
+        return stock_weight
+
+
+@dataclass
+class RisingEquityGlidepathPolicy:
+    """Rising equity glidepath (bonds-first approach).
+
+    Start conservative, increase equity over time as sequence-of-returns
+    risk decreases and remaining lifespan shortens.
+
+    Based on research by Wade Pfau and Michael Kitces showing that
+    rising equity glidepaths can improve outcomes in some scenarios.
+    """
+
+    initial_stock_weight: float = 0.3
+    final_stock_weight: float = 0.7
+    years_to_final: int = 20
+
+    @property
+    def name(self) -> str:
+        return f"Rising Equity ({self.initial_stock_weight:.0%} → {self.final_stock_weight:.0%})"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate stock allocation - increasing over time."""
+        progress = min(year / self.years_to_final, 1.0)
+        stock_weight = self.initial_stock_weight + progress * (
+            self.final_stock_weight - self.initial_stock_weight
+        )
+        return stock_weight
+
+
+@dataclass
+class VShapedGlidepathPolicy:
+    """V-shaped glidepath: reduce then increase equity.
+
+    Start moderate, reduce equity in early retirement (highest sequence risk),
+    then increase equity as the portfolio stabilizes and remaining horizon shortens.
+    """
+
+    initial_stock_weight: float = 0.5
+    minimum_stock_weight: float = 0.3
+    final_stock_weight: float = 0.6
+    years_to_minimum: int = 10
+    years_to_final: int = 30
+
+    @property
+    def name(self) -> str:
+        return "V-Shaped Glidepath"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate V-shaped stock allocation."""
+        if year <= self.years_to_minimum:
+            # Declining phase
+            progress = year / self.years_to_minimum
+            stock_weight = self.initial_stock_weight - progress * (
+                self.initial_stock_weight - self.minimum_stock_weight
+            )
+        else:
+            # Rising phase
+            years_in_rising = year - self.years_to_minimum
+            years_remaining = self.years_to_final - self.years_to_minimum
+            progress = min(years_in_rising / years_remaining, 1.0)
+            stock_weight = self.minimum_stock_weight + progress * (
+                self.final_stock_weight - self.minimum_stock_weight
+            )
+
+        return stock_weight

fundedness/allocation/merton_optimal.py

@@ -0,0 +1,220 @@
+"""Merton optimal allocation policy based on utility maximization."""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from fundedness.merton import (
+    merton_optimal_allocation,
+    wealth_adjusted_optimal_allocation,
+)
+from fundedness.models.market import MarketModel
+from fundedness.models.utility import UtilityModel
+
+
+@dataclass
+class MertonOptimalAllocationPolicy:
+    """Allocation policy based on Merton optimal portfolio theory.
+
+    This policy determines equity allocation using the Merton formula,
+    with adjustments for wealth level relative to subsistence floor.
+
+    Key characteristics:
+    - Base allocation from Merton: k* = (mu - r) / (gamma * sigma^2)
+    - Allocation decreases as wealth approaches subsistence floor
+    - Configurable bounds to prevent extreme positions
+
+    Attributes:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters including risk aversion
+        min_equity: Minimum equity allocation
+        max_equity: Maximum equity allocation
+        use_wealth_adjustment: Whether to reduce allocation near floor
+    """
+
+    market_model: MarketModel = field(default_factory=MarketModel)
+    utility_model: UtilityModel = field(default_factory=UtilityModel)
+    min_equity: float = 0.0
+    max_equity: float = 1.0
+    use_wealth_adjustment: bool = True
+
+    @property
+    def name(self) -> str:
+        k_star = merton_optimal_allocation(self.market_model, self.utility_model)
+        return f"Merton Optimal ({k_star:.0%})"
+
+    def get_unconstrained_allocation(self) -> float:
+        """Get the unconstrained Merton optimal allocation.
+
+        Returns:
+            Optimal equity allocation (may exceed bounds)
+        """
+        return merton_optimal_allocation(self.market_model, self.utility_model)
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float | np.ndarray:
+        """Get the optimal stock allocation.
+
+        Args:
+            wealth: Current portfolio value(s)
+            year: Current year in simulation (not used but required by interface)
+            initial_wealth: Starting portfolio value (not used but required)
+
+        Returns:
+            Stock allocation as decimal (0-1), scalar or array matching wealth
+        """
+        if not self.use_wealth_adjustment:
+            # Use fixed Merton optimal allocation
+            k_star = merton_optimal_allocation(self.market_model, self.utility_model)
+            return np.clip(k_star, self.min_equity, self.max_equity)
+
+        # Apply wealth-adjusted allocation
+        if isinstance(wealth, np.ndarray):
+            allocations = np.zeros_like(wealth, dtype=float)
+            for i, w in enumerate(wealth):
+                allocations[i] = wealth_adjusted_optimal_allocation(
+                    wealth=w,
+                    market_model=self.market_model,
+                    utility_model=self.utility_model,
+                    min_allocation=self.min_equity,
+                    max_allocation=self.max_equity,
+                )
+            return allocations
+        else:
+            return wealth_adjusted_optimal_allocation(
+                wealth=wealth,
+                market_model=self.market_model,
+                utility_model=self.utility_model,
+                min_allocation=self.min_equity,
+                max_allocation=self.max_equity,
+            )
+
+
+@dataclass
+class WealthBasedAllocationPolicy:
+    """Allocation that varies with wealth relative to floor.
+
+    This is a simplified version that linearly interpolates between
+    a minimum allocation at the floor and maximum at a target wealth.
+
+    More intuitive than full Merton but captures the key insight that
+    risk capacity depends on distance from subsistence.
+
+    Attributes:
+        floor_wealth: Wealth level at which equity is at minimum
+        target_wealth: Wealth level at which equity reaches maximum
+        min_equity: Equity allocation at floor
+        max_equity: Equity allocation at target and above
+    """
+
+    floor_wealth: float = 500_000
+    target_wealth: float = 2_000_000
+    min_equity: float = 0.2
+    max_equity: float = 0.8
+
+    @property
+    def name(self) -> str:
+        return f"Wealth-Based ({self.min_equity:.0%}-{self.max_equity:.0%})"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float | np.ndarray:
+        """Get allocation based on current wealth level.
+
+        Args:
+            wealth: Current portfolio value(s)
+            year: Current year (not used)
+            initial_wealth: Starting value (not used)
+
+        Returns:
+            Stock allocation interpolated by wealth
+        """
+        # Linear interpolation between floor and target
+        wealth_range = self.target_wealth - self.floor_wealth
+        equity_range = self.max_equity - self.min_equity
+
+        if isinstance(wealth, np.ndarray):
+            progress = (wealth - self.floor_wealth) / wealth_range
+            progress = np.clip(progress, 0, 1)
+            return self.min_equity + progress * equity_range
+        else:
+            progress = (wealth - self.floor_wealth) / wealth_range
+            progress = max(0, min(1, progress))
+            return self.min_equity + progress * equity_range
+
+
+@dataclass
+class FloorProtectionAllocationPolicy:
+    """Allocation that increases equity as wealth grows above floor.
+
+    Inspired by CPPI (Constant Proportion Portfolio Insurance), this
+    policy allocates equity as a multiple of the "cushion" (wealth above
+    the floor-protection level).
+
+    Attributes:
+        utility_model: For subsistence floor value
+        multiplier: Equity = multiplier * (wealth - floor_reserve) / wealth
+        floor_years: Years of floor spending to protect
+        min_equity: Minimum equity allocation
+        max_equity: Maximum equity allocation
+    """
+
+    utility_model: UtilityModel = field(default_factory=UtilityModel)
+    multiplier: float = 3.0
+    floor_years: int = 10
+    min_equity: float = 0.1
+    max_equity: float = 0.9
+
+    @property
+    def name(self) -> str:
+        return f"Floor Protection (m={self.multiplier})"
+
+    def get_floor_reserve(self) -> float:
+        """Get the wealth level that protects floor spending.
+
+        Returns:
+            Wealth needed to fund floor spending for floor_years
+        """
+        return self.utility_model.subsistence_floor * self.floor_years
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float | np.ndarray:
+        """Get allocation based on cushion above floor reserve.
+
+        Args:
+            wealth: Current portfolio value(s)
+            year: Current year (not used)
+            initial_wealth: Starting value (not used)
+
+        Returns:
+            Stock allocation based on cushion
+        """
+        floor_reserve = self.get_floor_reserve()
+
+        if isinstance(wealth, np.ndarray):
+            cushion = np.maximum(wealth - floor_reserve, 0)
+            # Equity = multiplier * cushion / wealth
+            # But avoid division by zero
+            allocation = np.where(
+                wealth > 0,
+                self.multiplier * cushion / wealth,
+                0.0,
+            )
+            return np.clip(allocation, self.min_equity, self.max_equity)
+        else:
+            if wealth <= 0:
+                return self.min_equity
+            cushion = max(wealth - floor_reserve, 0)
+            allocation = self.multiplier * cushion / wealth
+            return max(self.min_equity, min(self.max_equity, allocation))