fundedness 0.2.4__py3-none-any.whl

fundedness/merton.py

@@ -0,0 +1,289 @@
+"""Merton optimal consumption and portfolio choice formulas.
+
+Implements the analytical solutions from Robert Merton's continuous-time
+portfolio optimization framework for retirement planning.
+
+References:
+- Merton, R.C. (1969). Lifetime Portfolio Selection under Uncertainty.
+- Haghani, V. & White, J. (2023). The Missing Billionaires. Wiley.
+
+Key formulas:
+- Optimal equity allocation: k* = (mu - r) / (gamma * sigma^2)
+- Certainty equivalent return: rce = r + k*(mu - r) - gamma*k^2*sigma^2/2
+- Optimal spending rate: c* = rce - (rce - rtp) / gamma
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fundedness.models.market import MarketModel
+from fundedness.models.utility import UtilityModel
+
+
+@dataclass
+class MertonOptimalResult:
+    """Results from Merton optimal calculations."""
+
+    optimal_equity_allocation: float
+    certainty_equivalent_return: float
+    optimal_spending_rate: float
+    wealth_adjusted_allocation: float
+    risk_premium: float
+    portfolio_volatility: float
+
+
+def merton_optimal_allocation(
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+) -> float:
+    """Calculate Merton optimal equity allocation.
+
+    The Merton formula gives the optimal fraction to invest in risky assets:
+    k* = (mu - r) / (gamma * sigma^2)
+
+    Args:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters including risk aversion
+
+    Returns:
+        Optimal equity allocation as decimal (can exceed 1.0 for leveraged)
+    """
+    mu = market_model.stock_return
+    r = market_model.bond_return
+    gamma = utility_model.gamma
+    sigma = market_model.stock_volatility
+
+    if sigma == 0 or gamma == 0:
+        return 0.0
+
+    k_star = (mu - r) / (gamma * sigma**2)
+
+    return k_star
+
+
+def certainty_equivalent_return(
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    equity_allocation: float | None = None,
+) -> float:
+    """Calculate certainty equivalent return for a portfolio.
+
+    The certainty equivalent return is the guaranteed return that provides
+    the same expected utility as the risky portfolio:
+    rce = r + k*(mu - r) - gamma*k^2*sigma^2/2
+
+    Args:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters including risk aversion
+        equity_allocation: Equity allocation (uses optimal if None)
+
+    Returns:
+        Certainty equivalent return as decimal
+    """
+    if equity_allocation is None:
+        equity_allocation = merton_optimal_allocation(market_model, utility_model)
+
+    mu = market_model.stock_return
+    r = market_model.bond_return
+    gamma = utility_model.gamma
+    sigma = market_model.stock_volatility
+
+    k = equity_allocation
+    risk_premium = k * (mu - r)
+    risk_penalty = gamma * k**2 * sigma**2 / 2
+
+    rce = r + risk_premium - risk_penalty
+
+    return rce
+
+
+def merton_optimal_spending_rate(
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    remaining_years: float | None = None,
+) -> float:
+    """Calculate Merton optimal spending rate.
+
+    The optimal spending rate for an infinite horizon is:
+    c* = rce - (rce - rtp) / gamma
+
+    For finite horizons, the rate is adjusted upward as horizon shortens.
+
+    Args:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters including risk aversion and time preference
+        remaining_years: Years until planning horizon ends (None for infinite)
+
+    Returns:
+        Optimal spending rate as decimal (e.g., 0.03 = 3%)
+    """
+    rce = certainty_equivalent_return(market_model, utility_model)
+    rtp = utility_model.time_preference
+    gamma = utility_model.gamma
+
+    if gamma == 1.0:
+        # Log utility special case
+        c_star = rtp
+    else:
+        c_star = rce - (rce - rtp) / gamma
+
+    # Finite horizon adjustment
+    if remaining_years is not None and remaining_years > 0:
+        # Use annuity factor to increase spending rate for finite horizon
+        # c_finite = c_infinite + 1 / remaining_years (approximate)
+        if rce > 0:
+            # Annuity present value factor
+            pv_factor = (1 - (1 + rce) ** (-remaining_years)) / rce
+            if pv_factor > 0:
+                annuity_rate = 1 / pv_factor
+                c_star = max(c_star, annuity_rate)
+        else:
+            # With non-positive returns, simple 1/N rule
+            c_star = max(c_star, 1 / remaining_years)
+
+    return max(c_star, 0.0)  # Can't have negative spending
+
+
+def wealth_adjusted_optimal_allocation(
+    wealth: float,
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    min_allocation: float = 0.0,
+    max_allocation: float = 1.0,
+) -> float:
+    """Calculate wealth-adjusted optimal equity allocation.
+
+    Near the subsistence floor, the optimal allocation approaches zero
+    because the investor cannot afford to take risk. As wealth rises
+    above the floor, allocation approaches the unconstrained Merton optimal.
+
+    The formula is:
+    k_adjusted = k* * (W - F) / W
+
+    Where W is wealth and F is the subsistence floor.
+
+    Args:
+        wealth: Current portfolio value
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters
+        min_allocation: Minimum equity allocation (floor)
+        max_allocation: Maximum equity allocation (ceiling)
+
+    Returns:
+        Adjusted equity allocation as decimal, bounded by min/max
+    """
+    k_star = merton_optimal_allocation(market_model, utility_model)
+    floor = utility_model.subsistence_floor
+
+    if wealth <= floor:
+        return min_allocation
+
+    # Scale by distance from floor
+    wealth_ratio = (wealth - floor) / wealth
+    k_adjusted = k_star * wealth_ratio
+
+    # Apply bounds
+    return np.clip(k_adjusted, min_allocation, max_allocation)
+
+
+def calculate_merton_optimal(
+    wealth: float,
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    remaining_years: float | None = None,
+) -> MertonOptimalResult:
+    """Calculate all Merton optimal values for given wealth.
+
+    This is the main entry point for getting all optimal policy parameters.
+
+    Args:
+        wealth: Current portfolio value
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters
+        remaining_years: Years until planning horizon ends
+
+    Returns:
+        MertonOptimalResult with all optimal values
+    """
+    k_star = merton_optimal_allocation(market_model, utility_model)
+    rce = certainty_equivalent_return(market_model, utility_model)
+    c_star = merton_optimal_spending_rate(market_model, utility_model, remaining_years)
+    k_adjusted = wealth_adjusted_optimal_allocation(wealth, market_model, utility_model)
+
+    risk_premium = market_model.stock_return - market_model.bond_return
+    portfolio_vol = k_star * market_model.stock_volatility
+
+    return MertonOptimalResult(
+        optimal_equity_allocation=k_star,
+        certainty_equivalent_return=rce,
+        optimal_spending_rate=c_star,
+        wealth_adjusted_allocation=k_adjusted,
+        risk_premium=risk_premium,
+        portfolio_volatility=portfolio_vol,
+    )
+
+
+def optimal_spending_by_age(
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    starting_age: int,
+    end_age: int = 100,
+) -> dict[int, float]:
+    """Calculate optimal spending rates for each age.
+
+    Spending rate increases with age as the remaining horizon shortens.
+
+    Args:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters
+        starting_age: Current age
+        end_age: Assumed maximum age
+
+    Returns:
+        Dictionary mapping age to optimal spending rate
+    """
+    rates = {}
+    for age in range(starting_age, end_age + 1):
+        remaining_years = end_age - age
+        if remaining_years <= 0:
+            rates[age] = 1.0  # Spend everything at end
+        else:
+            rates[age] = merton_optimal_spending_rate(
+                market_model, utility_model, remaining_years
+            )
+    return rates
+
+
+def optimal_allocation_by_wealth(
+    market_model: MarketModel,
+    utility_model: UtilityModel,
+    wealth_levels: np.ndarray,
+    min_allocation: float = 0.0,
+    max_allocation: float = 1.0,
+) -> np.ndarray:
+    """Calculate optimal allocation for a range of wealth levels.
+
+    Useful for generating allocation curves showing how equity percentage
+    should vary with distance from subsistence floor.
+
+    Args:
+        market_model: Market return and risk assumptions
+        utility_model: Utility parameters
+        wealth_levels: Array of wealth values to calculate for
+        min_allocation: Minimum equity allocation
+        max_allocation: Maximum equity allocation
+
+    Returns:
+        Array of optimal allocations corresponding to wealth_levels
+    """
+    allocations = np.zeros_like(wealth_levels, dtype=float)
+    for i, wealth in enumerate(wealth_levels):
+        allocations[i] = wealth_adjusted_optimal_allocation(
+            wealth=wealth,
+            market_model=market_model,
+            utility_model=utility_model,
+            min_allocation=min_allocation,
+            max_allocation=max_allocation,
+        )
+    return allocations

fundedness/models/__init__.py

@@ -0,0 +1,35 @@
+"""Pydantic data models for the fundedness package."""
+
+from fundedness.models.assets import (
+    AccountType,
+    Asset,
+    AssetClass,
+    BalanceSheet,
+    ConcentrationLevel,
+    LiquidityClass,
+)
+from fundedness.models.household import Household, Person
+from fundedness.models.liabilities import InflationLinkage, Liability, LiabilityType
+from fundedness.models.market import MarketModel
+from fundedness.models.simulation import SimulationConfig
+from fundedness.models.tax import TaxModel
+from fundedness.models.utility import UtilityModel
+
+__all__ = [
+    "AccountType",
+    "Asset",
+    "AssetClass",
+    "BalanceSheet",
+    "ConcentrationLevel",
+    "Household",
+    "InflationLinkage",
+    "Liability",
+    "LiabilityClass",
+    "LiabilityType",
+    "LiquidityClass",
+    "MarketModel",
+    "Person",
+    "SimulationConfig",
+    "TaxModel",
+    "UtilityModel",
+]

fundedness/models/assets.py

@@ -0,0 +1,148 @@
+"""Asset and balance sheet models."""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class AccountType(str, Enum):
+    """Tax treatment of an account."""
+
+    TAXABLE = "taxable"
+    TAX_DEFERRED = "tax_deferred"  # Traditional IRA, 401(k)
+    TAX_EXEMPT = "tax_exempt"  # Roth IRA, Roth 401(k)
+    HSA = "hsa"
+
+
+class AssetClass(str, Enum):
+    """Broad asset class categories."""
+
+    CASH = "cash"
+    BONDS = "bonds"
+    STOCKS = "stocks"
+    REAL_ESTATE = "real_estate"
+    ALTERNATIVES = "alternatives"
+
+
+class LiquidityClass(str, Enum):
+    """Liquidity classification for assets."""
+
+    CASH = "cash"  # Immediate liquidity
+    TAXABLE_INDEX = "taxable_index"  # Public securities in taxable accounts
+    RETIREMENT = "retirement"  # Tax-advantaged retirement accounts
+    HOME_EQUITY = "home_equity"  # Primary residence equity
+    PRIVATE_BUSINESS = "private_business"  # Illiquid business interests
+    RESTRICTED = "restricted"  # Restricted stock, vesting schedules
+
+
+class ConcentrationLevel(str, Enum):
+    """Concentration/diversification level."""
+
+    DIVERSIFIED = "diversified"  # Broad index funds
+    SECTOR = "sector"  # Sector-specific concentration
+    SINGLE_STOCK = "single_stock"  # Individual company stock
+    STARTUP = "startup"  # Early-stage company equity
+
+
+class Asset(BaseModel):
+    """A single asset holding."""
+
+    name: str = Field(..., description="Descriptive name for the asset")
+    value: float = Field(..., ge=0, description="Current market value in dollars")
+    account_type: AccountType = Field(
+        default=AccountType.TAXABLE,
+        description="Tax treatment of the account",
+    )
+    asset_class: AssetClass = Field(
+        default=AssetClass.STOCKS,
+        description="Broad asset class category",
+    )
+    liquidity_class: LiquidityClass = Field(
+        default=LiquidityClass.TAXABLE_INDEX,
+        description="Liquidity classification",
+    )
+    concentration_level: ConcentrationLevel = Field(
+        default=ConcentrationLevel.DIVERSIFIED,
+        description="Concentration/diversification level",
+    )
+    cost_basis: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Cost basis for tax calculations (taxable accounts only)",
+    )
+    expected_return: Optional[float] = Field(
+        default=None,
+        description="Override expected return (annual, decimal)",
+    )
+    volatility: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Override volatility (annual standard deviation, decimal)",
+    )
+
+    @field_validator("cost_basis")
+    @classmethod
+    def validate_cost_basis(cls, v: Optional[float], info) -> Optional[float]:
+        """Warn if cost basis exceeds value (unrealized loss)."""
+        return v
+
+    @property
+    def unrealized_gain(self) -> Optional[float]:
+        """Calculate unrealized gain/loss if cost basis is known."""
+        if self.cost_basis is None:
+            return None
+        return self.value - self.cost_basis
+
+
+class BalanceSheet(BaseModel):
+    """Collection of assets representing a household's balance sheet."""
+
+    assets: list[Asset] = Field(default_factory=list, description="List of asset holdings")
+
+    @property
+    def total_value(self) -> float:
+        """Total market value of all assets."""
+        return sum(asset.value for asset in self.assets)
+
+    @property
+    def by_account_type(self) -> dict[AccountType, float]:
+        """Total value by account type."""
+        result: dict[AccountType, float] = {}
+        for asset in self.assets:
+            result[asset.account_type] = result.get(asset.account_type, 0) + asset.value
+        return result
+
+    @property
+    def by_asset_class(self) -> dict[AssetClass, float]:
+        """Total value by asset class."""
+        result: dict[AssetClass, float] = {}
+        for asset in self.assets:
+            result[asset.asset_class] = result.get(asset.asset_class, 0) + asset.value
+        return result
+
+    @property
+    def by_liquidity_class(self) -> dict[LiquidityClass, float]:
+        """Total value by liquidity class."""
+        result: dict[LiquidityClass, float] = {}
+        for asset in self.assets:
+            result[asset.liquidity_class] = result.get(asset.liquidity_class, 0) + asset.value
+        return result
+
+    def get_stock_allocation(self) -> float:
+        """Calculate percentage allocated to stocks."""
+        if self.total_value == 0:
+            return 0.0
+        stock_value = sum(
+            asset.value for asset in self.assets if asset.asset_class == AssetClass.STOCKS
+        )
+        return stock_value / self.total_value
+
+    def get_bond_allocation(self) -> float:
+        """Calculate percentage allocated to bonds."""
+        if self.total_value == 0:
+            return 0.0
+        bond_value = sum(
+            asset.value for asset in self.assets if asset.asset_class == AssetClass.BONDS
+        )
+        return bond_value / self.total_value

fundedness/models/household.py

@@ -0,0 +1,153 @@
+"""Household and person models."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+from fundedness.models.assets import BalanceSheet
+from fundedness.models.liabilities import Liability
+
+
+class Person(BaseModel):
+    """An individual person in the household."""
+
+    name: str = Field(..., description="Person's name")
+    age: int = Field(..., ge=0, le=120, description="Current age")
+    retirement_age: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=120,
+        description="Expected retirement age (None if already retired)",
+    )
+    life_expectancy: int = Field(
+        default=95,
+        ge=0,
+        le=120,
+        description="Planning life expectancy",
+    )
+    social_security_age: int = Field(
+        default=67,
+        ge=62,
+        le=70,
+        description="Age to claim Social Security",
+    )
+    social_security_annual: float = Field(
+        default=0,
+        ge=0,
+        description="Expected annual Social Security benefit at claiming age (today's dollars)",
+    )
+    pension_annual: float = Field(
+        default=0,
+        ge=0,
+        description="Expected annual pension benefit (today's dollars)",
+    )
+    pension_start_age: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=120,
+        description="Age when pension payments begin",
+    )
+    is_primary: bool = Field(
+        default=True,
+        description="Whether this is the primary earner/planner",
+    )
+
+    @model_validator(mode="after")
+    def validate_ages(self) -> "Person":
+        """Validate age relationships."""
+        if self.retirement_age is not None and self.retirement_age < self.age:
+            # Already past retirement age, treat as retired
+            self.retirement_age = None
+        if self.life_expectancy < self.age:
+            raise ValueError("Life expectancy must be greater than current age")
+        return self
+
+    @property
+    def years_to_retirement(self) -> int:
+        """Years until retirement (0 if already retired)."""
+        if self.retirement_age is None:
+            return 0
+        return max(0, self.retirement_age - self.age)
+
+    @property
+    def years_in_retirement(self) -> int:
+        """Expected years in retirement."""
+        retirement_age = self.retirement_age or self.age
+        return max(0, self.life_expectancy - retirement_age)
+
+    @property
+    def planning_horizon(self) -> int:
+        """Total years in planning horizon."""
+        return max(0, self.life_expectancy - self.age)
+
+
+class Household(BaseModel):
+    """A household unit for financial planning."""
+
+    name: str = Field(
+        default="My Household",
+        description="Household name",
+    )
+    members: list[Person] = Field(
+        default_factory=list,
+        description="Household members",
+    )
+    balance_sheet: BalanceSheet = Field(
+        default_factory=BalanceSheet,
+        description="Household balance sheet",
+    )
+    liabilities: list[Liability] = Field(
+        default_factory=list,
+        description="Future spending obligations",
+    )
+    state: str = Field(
+        default="CA",
+        description="State of residence (for tax calculations)",
+    )
+    filing_status: str = Field(
+        default="married_filing_jointly",
+        description="Tax filing status",
+    )
+
+    @property
+    def primary_member(self) -> Optional[Person]:
+        """Get the primary household member."""
+        for member in self.members:
+            if member.is_primary:
+                return member
+        return self.members[0] if self.members else None
+
+    @property
+    def planning_horizon(self) -> int:
+        """Planning horizon based on longest-lived member."""
+        if not self.members:
+            return 30  # Default
+        return max(member.planning_horizon for member in self.members)
+
+    @property
+    def total_assets(self) -> float:
+        """Total asset value."""
+        return self.balance_sheet.total_value
+
+    @property
+    def essential_spending(self) -> float:
+        """Total annual essential spending."""
+        return sum(
+            liability.annual_amount
+            for liability in self.liabilities
+            if liability.is_essential
+        )
+
+    @property
+    def discretionary_spending(self) -> float:
+        """Total annual discretionary spending."""
+        return sum(
+            liability.annual_amount
+            for liability in self.liabilities
+            if not liability.is_essential
+        )
+
+    @property
+    def total_spending(self) -> float:
+        """Total annual spending target."""
+        return self.essential_spending + self.discretionary_spending