monteplan 0.5.0__py3-none-any.whl

monteplan/__init__.py

@@ -0,0 +1,23 @@
+"""monteplan — Monte Carlo financial planning simulator."""
+
+__version__ = "0.5.0"
+
+from monteplan.analytics.swr import SWRResult as SWRResult
+from monteplan.analytics.swr import find_safe_withdrawal_rate as find_safe_withdrawal_rate
+from monteplan.config.defaults import default_market as default_market
+from monteplan.config.defaults import default_plan as default_plan
+from monteplan.config.defaults import default_policies as default_policies
+from monteplan.config.defaults import default_sim_config as default_sim_config
+from monteplan.config.schema import AccountConfig as AccountConfig
+from monteplan.config.schema import AssetClass as AssetClass
+from monteplan.config.schema import DiscreteEvent as DiscreteEvent
+from monteplan.config.schema import GlidePath as GlidePath
+from monteplan.config.schema import GuaranteedIncomeStream as GuaranteedIncomeStream
+from monteplan.config.schema import MarketAssumptions as MarketAssumptions
+from monteplan.config.schema import PlanConfig as PlanConfig
+from monteplan.config.schema import PolicyBundle as PolicyBundle
+from monteplan.config.schema import RothConversionConfig as RothConversionConfig
+from monteplan.config.schema import SimulationConfig as SimulationConfig
+from monteplan.config.schema import SpendingPolicyConfig as SpendingPolicyConfig
+from monteplan.core.engine import SimulationResult as SimulationResult
+from monteplan.core.engine import simulate as simulate

monteplan/analytics/metrics.py

@@ -0,0 +1,169 @@
+"""Simulation result metrics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class SimulationMetrics:
+    """Computed metrics from a simulation run."""
+
+    success_probability: float
+    terminal_wealth_p5: float
+    terminal_wealth_p25: float
+    terminal_wealth_p50: float
+    terminal_wealth_p75: float
+    terminal_wealth_p95: float
+    mean_terminal_wealth: float
+    mean_shortfall: float
+    shortfall_probability: float
+
+
+def compute_metrics(
+    wealth_history: np.ndarray,
+    retirement_step: int,
+) -> SimulationMetrics:
+    """Compute simulation metrics from wealth history.
+
+    Args:
+        wealth_history: (n_paths, n_steps+1) array of total wealth at each step.
+        retirement_step: Step index when retirement begins.
+
+    Returns:
+        SimulationMetrics with success/failure statistics.
+    """
+    retirement_wealth = wealth_history[:, retirement_step:]
+
+    # Success = never ran out during retirement
+    success_mask = np.all(retirement_wealth > 0, axis=1)
+    success_probability = float(success_mask.mean())
+
+    # Terminal wealth
+    terminal = wealth_history[:, -1]
+    pcts = np.percentile(terminal, [5, 25, 50, 75, 95])
+
+    # Shortfall: paths where terminal wealth is 0
+    failed_mask = ~success_mask
+    shortfall_probability = float(failed_mask.mean())
+
+    if failed_mask.any():
+        # Mean number of months with zero wealth across failed paths
+        zero_months = (retirement_wealth[failed_mask] <= 0).sum(axis=1)
+        mean_shortfall = float(zero_months.mean())
+    else:
+        mean_shortfall = 0.0
+
+    return SimulationMetrics(
+        success_probability=success_probability,
+        terminal_wealth_p5=float(pcts[0]),
+        terminal_wealth_p25=float(pcts[1]),
+        terminal_wealth_p50=float(pcts[2]),
+        terminal_wealth_p75=float(pcts[3]),
+        terminal_wealth_p95=float(pcts[4]),
+        mean_terminal_wealth=float(terminal.mean()),
+        mean_shortfall=mean_shortfall,
+        shortfall_probability=shortfall_probability,
+    )
+
+
+def max_drawdown_distribution(
+    wealth_history: np.ndarray,
+) -> dict[str, float]:
+    """Compute per-path maximum drawdown and return percentiles.
+
+    Maximum drawdown = largest peak-to-trough decline as a fraction.
+
+    Args:
+        wealth_history: (n_paths, n_steps+1) array of total wealth.
+
+    Returns:
+        Dict with p5, p25, p50, p75, p95, mean of max drawdown (as fractions).
+    """
+    # Running maximum along the time axis
+    running_max = np.maximum.accumulate(wealth_history, axis=1)
+    safe_max = np.where(running_max > 0, running_max, 1.0)
+    drawdowns = (running_max - wealth_history) / safe_max
+    # Per-path max drawdown
+    max_dd = drawdowns.max(axis=1)
+
+    pcts = np.percentile(max_dd, [5, 25, 50, 75, 95])
+    return {
+        "p5": float(pcts[0]),
+        "p25": float(pcts[1]),
+        "p50": float(pcts[2]),
+        "p75": float(pcts[3]),
+        "p95": float(pcts[4]),
+        "mean": float(max_dd.mean()),
+    }
+
+
+def spending_volatility(
+    spending_history: np.ndarray,
+    retirement_step: int,
+) -> dict[str, float]:
+    """Compute per-path spending volatility during retirement.
+
+    Volatility = standard deviation of month-over-month spending changes
+    divided by mean spending (coefficient of variation of changes).
+
+    Args:
+        spending_history: (n_paths, n_steps) array of monthly spending.
+        retirement_step: Step index when retirement begins.
+
+    Returns:
+        Dict with p50 and mean of spending volatility across paths.
+    """
+    retirement_spending = spending_history[:, retirement_step:]
+
+    # Month-over-month changes
+    if retirement_spending.shape[1] < 2:
+        return {"p50": 0.0, "mean": 0.0}
+
+    changes = np.diff(retirement_spending, axis=1)
+    mean_spending = retirement_spending[:, :-1].mean(axis=1)
+    safe_mean = np.where(mean_spending > 0, mean_spending, 1.0)
+
+    # Per-path coefficient of variation of changes
+    change_std = changes.std(axis=1)
+    cv = change_std / safe_mean
+
+    return {
+        "p50": float(np.median(cv)),
+        "mean": float(cv.mean()),
+    }
+
+
+def ruin_by_age(
+    wealth_history: np.ndarray,
+    retirement_step: int,
+    current_age: int,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute fraction of paths depleted at each age.
+
+    Args:
+        wealth_history: (n_paths, n_steps+1) array of total wealth.
+        retirement_step: Step index when retirement begins.
+        current_age: Starting age.
+
+    Returns:
+        Tuple of (ages, ruin_fractions) arrays.
+    """
+    n_paths, n_time = wealth_history.shape
+    # Check depletion at each step from retirement onward
+    retired_wealth = wealth_history[:, retirement_step:]
+    depleted = retired_wealth <= 0  # (n_paths, n_retirement_steps)
+    # Cumulative: once depleted, stays depleted
+    cumulative_depleted = np.maximum.accumulate(depleted.astype(int), axis=1)
+    ruin_fractions = cumulative_depleted.mean(axis=0)
+
+    # Ages for each step
+    n_retirement_steps = retired_wealth.shape[1]
+    ages = np.linspace(
+        current_age + retirement_step / 12.0,
+        current_age + (retirement_step + n_retirement_steps - 1) / 12.0,
+        n_retirement_steps,
+    )
+    return ages, ruin_fractions

monteplan/analytics/sensitivity.py

@@ -0,0 +1,486 @@
+"""One-at-a-time (OAT) sensitivity analysis for simulation parameters."""
+
+from __future__ import annotations
+
+import concurrent.futures
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from monteplan.config.schema import (
+    AssetClass,
+    MarketAssumptions,
+    PlanConfig,
+    PolicyBundle,
+    SimulationConfig,
+)
+from monteplan.core.engine import simulate
+
+# Type aliases for getter/setter callables
+_Getter = Callable[..., float]
+_Setter = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class SensitivityResult:
+    """Result of perturbing a single parameter."""
+
+    parameter_name: str
+    base_value: float
+    low_value: float
+    high_value: float
+    base_success: float
+    low_success: float
+    high_success: float
+    impact: float  # high_success - low_success
+
+
+@dataclass
+class SensitivityReport:
+    """Full report of one-at-a-time sensitivity analysis."""
+
+    results: list[SensitivityResult] = field(default_factory=list)
+    base_success_probability: float = 0.0
+
+
+@dataclass(frozen=True)
+class HeatmapResult:
+    """Result of a 2D sensitivity grid analysis."""
+
+    x_param_name: str
+    y_param_name: str
+    x_values: list[float]
+    y_values: list[float]
+    success_grid: list[list[float]]  # [y_idx][x_idx]
+    base_x_value: float
+    base_y_value: float
+    base_success: float
+
+
+@dataclass
+class _ParamSpec:
+    """Internal spec for a perturbable parameter."""
+
+    getter: _Getter
+    setter: _Setter
+    is_additive: bool = False
+    additive_delta: float = 0.0
+    target: str = "market"  # "market", "plan", or "policies"
+
+
+def _make_market_return_setter(idx: int) -> _Setter:
+    def setter(m: MarketAssumptions, val: float) -> MarketAssumptions:
+        new_returns = list(m.expected_annual_returns)
+        new_returns[idx] = val
+        return m.model_copy(update={"expected_annual_returns": new_returns})
+
+    return setter
+
+
+def _make_market_vol_setter(idx: int) -> _Setter:
+    def setter(m: MarketAssumptions, val: float) -> MarketAssumptions:
+        new_vols = list(m.annual_volatilities)
+        new_vols[idx] = val
+        return m.model_copy(update={"annual_volatilities": new_vols})
+
+    return setter
+
+
+def _make_contribution_setter(idx: int) -> _Setter:
+    def setter(p: PlanConfig, val: float) -> PlanConfig:
+        new_accounts = list(p.accounts)
+        new_accounts[idx] = new_accounts[idx].model_copy(
+            update={"annual_contribution": max(0.0, val)}
+        )
+        return p.model_copy(update={"accounts": new_accounts})
+
+    return setter
+
+
+def _stock_allocation_setter(m: MarketAssumptions, val: float) -> MarketAssumptions:
+    """Set stock allocation weight (first asset), adjusting second asset to keep sum=1."""
+    clamped = max(0.0, min(1.0, val))
+    new_assets = list(m.assets)
+    new_assets[0] = AssetClass(name=new_assets[0].name, weight=clamped)
+    if len(new_assets) > 1:
+        new_assets[1] = AssetClass(name=new_assets[1].name, weight=1.0 - clamped)
+    return m.model_copy(update={"assets": new_assets})
+
+
+def _build_param_registry(
+    plan: PlanConfig,
+    market: MarketAssumptions,
+    policies: PolicyBundle | None = None,
+) -> dict[str, _ParamSpec]:
+    """Build the full registry of perturbable parameters."""
+    all_params: dict[str, _ParamSpec] = {}
+    n_assets = len(market.assets)
+
+    for i in range(n_assets):
+        asset_name = market.assets[i].name
+        all_params[f"{asset_name} Return"] = _ParamSpec(
+            getter=lambda m, idx=i: m.expected_annual_returns[idx],
+            setter=_make_market_return_setter(i),
+            is_additive=False,
+        )
+        all_params[f"{asset_name} Volatility"] = _ParamSpec(
+            getter=lambda m, idx=i: m.annual_volatilities[idx],
+            setter=_make_market_vol_setter(i),
+            is_additive=False,
+        )
+
+    all_params["Inflation Rate"] = _ParamSpec(
+        getter=lambda m: m.inflation_mean,
+        setter=lambda m, v: m.model_copy(update={"inflation_mean": v}),
+        is_additive=False,
+    )
+
+    all_params["Monthly Spending"] = _ParamSpec(
+        getter=lambda p: p.monthly_spending,
+        setter=lambda p, v: p.model_copy(update={"monthly_spending": v}),
+        is_additive=False,
+        target="plan",
+    )
+
+    all_params["Retirement Age"] = _ParamSpec(
+        getter=lambda p: float(p.retirement_age),
+        setter=lambda p, v: p.model_copy(update={"retirement_age": int(round(v))}),
+        is_additive=True,
+        additive_delta=2.0,
+        target="plan",
+    )
+
+    for i, acct in enumerate(plan.accounts):
+        if acct.annual_contribution > 0:
+            all_params[f"{acct.account_type.title()} Contribution"] = _ParamSpec(
+                getter=lambda p, idx=i: p.accounts[idx].annual_contribution,
+                setter=_make_contribution_setter(i),
+                is_additive=False,
+                target="plan",
+            )
+
+    # Stock allocation (first asset weight)
+    if n_assets >= 2:
+        all_params["Stock Allocation"] = _ParamSpec(
+            getter=lambda m: m.assets[0].weight,
+            setter=_stock_allocation_setter,
+            is_additive=False,
+        )
+
+    # State tax rate (only register when non-zero)
+    if policies is not None and policies.state_tax_rate > 0:
+        all_params["State Tax Rate"] = _ParamSpec(
+            getter=lambda p: p.state_tax_rate,
+            setter=lambda p, v: p.model_copy(update={"state_tax_rate": max(0.0, min(0.15, v))}),
+            is_additive=True,
+            additive_delta=0.02,
+            target="policies",
+        )
+
+    return all_params
+
+
+def _run_one(
+    plan: PlanConfig,
+    market: MarketAssumptions,
+    policies: PolicyBundle,
+    sim_config: SimulationConfig,
+) -> float:
+    """Run a single simulation and return success probability.
+
+    Top-level function so it is picklable for ProcessPoolExecutor.
+    """
+    try:
+        result = simulate(plan, market, policies, sim_config)
+        return result.success_probability
+    except Exception:
+        return -1.0  # sentinel for failure
+
+
+def run_sensitivity(
+    plan: PlanConfig,
+    market: MarketAssumptions,
+    policies: PolicyBundle,
+    sim_config: SimulationConfig,
+    perturbation_pct: float = 0.10,
+    parameters: list[str] | None = None,
+    max_workers: int | None = None,
+) -> SensitivityReport:
+    """Run OAT sensitivity analysis.
+
+    Perturbs each parameter by ±perturbation_pct (or additive for ages)
+    and measures the impact on success probability.
+
+    Args:
+        plan: Financial plan configuration.
+        market: Market assumptions.
+        policies: Policy bundle.
+        sim_config: Simulation config (n_paths capped at 2000 for speed).
+        perturbation_pct: Fractional perturbation (default 10%).
+        parameters: Optional list of parameter names to vary. If None,
+            uses all default parameters.
+        max_workers: Maximum number of parallel workers. ``None`` uses
+            all available cores; ``1`` forces sequential execution.
+
+    Returns:
+        SensitivityReport with per-parameter results.
+    """
+    # Cap paths for speed
+    capped_paths = min(sim_config.n_paths, 2000)
+    base_sim = sim_config.model_copy(update={"n_paths": capped_paths, "preset": None})
+
+    # Base run
+    base_result = simulate(plan, market, policies, base_sim)
+    base_success = base_result.success_probability
+
+    # Define all perturbable parameters
+    all_params = _build_param_registry(plan, market, policies)
+
+    # Filter to requested parameters
+    if parameters is not None:
+        param_set = {k: v for k, v in all_params.items() if k in parameters}
+    else:
+        param_set = all_params
+
+    # Build all perturbation jobs upfront (picklable tuples)
+    # Each job: (param_name, direction, plan, market, policies, sim_config)
+    jobs: list[tuple[str, str, PlanConfig, MarketAssumptions, PolicyBundle, SimulationConfig]] = []
+    param_vals: dict[str, tuple[float, float, float]] = {}  # name -> (base, low, high)
+
+    for param_name, spec in param_set.items():
+        if spec.target == "plan":
+            target_obj: PlanConfig | MarketAssumptions | PolicyBundle = plan
+        elif spec.target == "policies":
+            target_obj = policies
+        else:
+            target_obj = market
+        base_val: float = spec.getter(target_obj)
+
+        if spec.is_additive:
+            delta = spec.additive_delta
+            low_val = base_val - delta
+            high_val = base_val + delta
+        else:
+            low_val = base_val * (1.0 - perturbation_pct)
+            high_val = base_val * (1.0 + perturbation_pct)
+
+        param_vals[param_name] = (base_val, low_val, high_val)
+
+        # Build low perturbation config
+        if spec.target == "plan":
+            try:
+                low_plan: PlanConfig = spec.setter(plan, low_val)
+                jobs.append((param_name, "low", low_plan, market, policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "low_fail", plan, market, policies, base_sim))
+        elif spec.target == "policies":
+            try:
+                low_policies: PolicyBundle = spec.setter(policies, low_val)
+                jobs.append((param_name, "low", plan, market, low_policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "low_fail", plan, market, policies, base_sim))
+        else:
+            try:
+                low_market: MarketAssumptions = spec.setter(market, low_val)
+                jobs.append((param_name, "low", plan, low_market, policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "low_fail", plan, market, policies, base_sim))
+
+        # Build high perturbation config
+        if spec.target == "plan":
+            try:
+                high_plan: PlanConfig = spec.setter(plan, high_val)
+                jobs.append((param_name, "high", high_plan, market, policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "high_fail", plan, market, policies, base_sim))
+        elif spec.target == "policies":
+            try:
+                high_policies: PolicyBundle = spec.setter(policies, high_val)
+                jobs.append((param_name, "high", plan, market, high_policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "high_fail", plan, market, policies, base_sim))
+        else:
+            try:
+                high_market: MarketAssumptions = spec.setter(market, high_val)
+                jobs.append((param_name, "high", plan, high_market, policies, base_sim))
+            except Exception:
+                jobs.append((param_name, "high_fail", plan, market, policies, base_sim))
+
+    # Run all perturbation simulations
+    results_map: dict[tuple[str, str], float] = {}
+
+    if max_workers == 1:
+        # Sequential execution
+        for param_name, direction, j_plan, j_market, j_policies, j_sim in jobs:
+            if direction.endswith("_fail"):
+                results_map[(param_name, direction.replace("_fail", ""))] = base_success
+            else:
+                results_map[(param_name, direction)] = _run_one(
+                    j_plan, j_market, j_policies, j_sim
+                )
+    else:
+        # Parallel execution
+        with concurrent.futures.ProcessPoolExecutor(max_workers=max_workers) as executor:
+            future_to_key: dict[concurrent.futures.Future[float], tuple[str, str]] = {}
+            for param_name, direction, j_plan, j_market, j_policies, j_sim in jobs:
+                if direction.endswith("_fail"):
+                    results_map[(param_name, direction.replace("_fail", ""))] = base_success
+                else:
+                    future = executor.submit(_run_one, j_plan, j_market, j_policies, j_sim)
+                    future_to_key[future] = (param_name, direction)
+
+            for future in concurrent.futures.as_completed(future_to_key):
+                key = future_to_key[future]
+                success = future.result()
+                if success < 0:
+                    # Sentinel: simulation failed, use base success
+                    results_map[key] = base_success
+                else:
+                    results_map[key] = success
+
+    # Assemble report in original parameter order
+    report = SensitivityReport(base_success_probability=base_success)
+
+    for param_name in param_set:
+        base_val, low_val, high_val = param_vals[param_name]
+        low_success = results_map.get((param_name, "low"), base_success)
+        high_success = results_map.get((param_name, "high"), base_success)
+
+        report.results.append(
+            SensitivityResult(
+                parameter_name=param_name,
+                base_value=base_val,
+                low_value=low_val,
+                high_value=high_val,
+                base_success=base_success,
+                low_success=low_success,
+                high_success=high_success,
+                impact=high_success - low_success,
+            )
+        )
+
+    return report
+
+
+def run_2d_sensitivity(
+    plan: PlanConfig,
+    market: MarketAssumptions,
+    policies: PolicyBundle,
+    sim_config: SimulationConfig,
+    x_param: str,
+    y_param: str,
+    x_range: tuple[float, float],
+    y_range: tuple[float, float],
+    x_steps: int = 12,
+    y_steps: int = 12,
+    max_workers: int | None = None,
+) -> HeatmapResult:
+    """Run a 2D grid sensitivity analysis.
+
+    Varies two parameters simultaneously and measures success probability
+    across an x_steps x y_steps grid.
+
+    Args:
+        plan: Financial plan configuration.
+        market: Market assumptions.
+        policies: Policy bundle.
+        sim_config: Simulation config (n_paths capped at 1000 for speed).
+        x_param: Name of the x-axis parameter.
+        y_param: Name of the y-axis parameter.
+        x_range: (min, max) range for x parameter.
+        y_range: (min, max) range for y parameter.
+        x_steps: Number of grid points along x-axis.
+        y_steps: Number of grid points along y-axis.
+        max_workers: Maximum number of parallel workers.
+
+    Returns:
+        HeatmapResult with the success probability grid.
+    """
+    # Cap paths for speed
+    capped_paths = min(sim_config.n_paths, 1000)
+    base_sim = sim_config.model_copy(update={"n_paths": capped_paths, "preset": None})
+
+    all_params = _build_param_registry(plan, market, policies)
+
+    if x_param not in all_params:
+        raise ValueError(f"Unknown parameter: {x_param}")
+    if y_param not in all_params:
+        raise ValueError(f"Unknown parameter: {y_param}")
+
+    x_spec = all_params[x_param]
+    y_spec = all_params[y_param]
+
+    x_values = np.linspace(x_range[0], x_range[1], x_steps).tolist()
+    y_values = np.linspace(y_range[0], y_range[1], y_steps).tolist()
+
+    # Get base values
+    def _resolve_target(
+        spec: _ParamSpec,
+    ) -> PlanConfig | MarketAssumptions | PolicyBundle:
+        if spec.target == "plan":
+            return plan
+        if spec.target == "policies":
+            return policies
+        return market
+
+    base_x = x_spec.getter(_resolve_target(x_spec))
+    base_y = y_spec.getter(_resolve_target(y_spec))
+
+    # Base run
+    base_result = simulate(plan, market, policies, base_sim)
+    base_success = base_result.success_probability * 100
+
+    # Build all grid jobs
+    jobs: list[tuple[int, int, PlanConfig, MarketAssumptions, PolicyBundle, SimulationConfig]] = []
+    for yi, yv in enumerate(y_values):
+        for xi, xv in enumerate(x_values):
+            cur_plan = plan
+            cur_market = market
+            cur_policies = policies
+            # Apply x parameter
+            if x_spec.target == "plan":
+                cur_plan = x_spec.setter(cur_plan, xv)
+            elif x_spec.target == "policies":
+                cur_policies = x_spec.setter(cur_policies, xv)
+            else:
+                cur_market = x_spec.setter(cur_market, xv)
+            # Apply y parameter
+            if y_spec.target == "plan":
+                cur_plan = y_spec.setter(cur_plan, yv)
+            elif y_spec.target == "policies":
+                cur_policies = y_spec.setter(cur_policies, yv)
+            else:
+                cur_market = y_spec.setter(cur_market, yv)
+            jobs.append((yi, xi, cur_plan, cur_market, cur_policies, base_sim))
+
+    # Run all jobs
+    grid: list[list[float]] = [[0.0] * x_steps for _ in range(y_steps)]
+
+    if max_workers == 1:
+        for yi, xi, j_plan, j_market, j_policies, j_sim in jobs:
+            success = _run_one(j_plan, j_market, j_policies, j_sim)
+            grid[yi][xi] = max(success, 0.0) * 100
+    else:
+        with concurrent.futures.ProcessPoolExecutor(max_workers=max_workers) as executor:
+            future_to_idx: dict[concurrent.futures.Future[float], tuple[int, int]] = {}
+            for yi, xi, j_plan, j_market, j_policies, j_sim in jobs:
+                future = executor.submit(_run_one, j_plan, j_market, j_policies, j_sim)
+                future_to_idx[future] = (yi, xi)
+
+            for future in concurrent.futures.as_completed(future_to_idx):
+                yi, xi = future_to_idx[future]
+                success = future.result()
+                grid[yi][xi] = max(success, 0.0) * 100
+
+    return HeatmapResult(
+        x_param_name=x_param,
+        y_param_name=y_param,
+        x_values=x_values,
+        y_values=y_values,
+        success_grid=grid,
+        base_x_value=base_x,
+        base_y_value=base_y,
+        base_success=base_success,
+    )