manyfutures 0.1.0__py3-none-any.whl

manyfutures/__init__.py

@@ -0,0 +1,32 @@
+"""A household's retirement plan run over many simulated futures.
+
+The Scenario seam (``manyfutures.scenario``): a ``Scenario``, the household's decisions, is run from a ``Start``, its
+Position on a date and the market's returns, on ``Assumptions``, the household's facts and the model's constants, and
+gives an ``Outcome``. ``run`` runs one Scenario, ``return_band`` runs it with every year's return a point either side
+(a ``ReturnBand``), ``compare`` runs it in every city, and ``inputs_that_matter`` moves one hand-set input at a time.
+The engine's other modules keep their own names: ``manyfutures.models``, ``manyfutures.simulation`` and the rest.
+"""
+
+from manyfutures.scenario import (
+    Assumptions,
+    Outcome,
+    ReturnBand,
+    Scenario,
+    Start,
+    compare,
+    inputs_that_matter,
+    return_band,
+    run,
+)
+
+__all__ = [
+    "Assumptions",
+    "Outcome",
+    "ReturnBand",
+    "Scenario",
+    "Start",
+    "compare",
+    "inputs_that_matter",
+    "return_band",
+    "run",
+]

manyfutures/analytics.py

@@ -0,0 +1,96 @@
+"""The two measures over a run's futures: the liquid portfolio's percentiles at each age, and the Sustainable rule's
+spending by age (the comparison lives in ``scenario``).
+
+Both give plain records, one per age; a caller that shows them as a table builds the table itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+
+import numpy as np
+
+from manyfutures.models import PortfolioAtAge, SimConfig, SpendingAtAge
+from manyfutures.simulation import compute_downsize_year_index
+
+__all__ = ["spending_by_age", "summarise"]
+
+
+def summarise(
+    values: np.ndarray,
+    config: SimConfig,
+    *,
+    net_equities: np.ndarray | None = None,
+    current_age: int,
+    downsize_failed_mask: np.ndarray | None = None,
+    alive: np.ndarray | None = None,
+) -> tuple[tuple[PortfolioAtAge, ...], tuple[PortfolioAtAge, ...], float]:
+    """Return (liquid, total, success_rate): the liquid portfolio's record at each age, the same with the home's net
+    equity added (the liquid records themselves without ``net_equities``), and the share never depleted in retirement.
+
+    One record per age, at the end of each model year. Its percentiles are over the paths alive at that age (`alive`,
+    shape (n, T), the year loop's mask; None means every path lasts to the last age), so a path frozen after the
+    year its End Age falls in leaves the records past it, and `share_alive` is how many of all the paths are alive
+    there (decision 26). An age no path reaches has no percentiles.
+
+    `downsize_failed_mask` (shape (n,)) excludes paths whose new mortgage would have exceeded
+    100% LTV from the post-move records, so failure-flagged paths don't blend silently
+    with successful ones, unless every path alive at that age failed. Pre-move records use every path alive.
+    """
+    n_paths, total_years = values.shape[0], config.accumulation_years + config.drawdown_years
+    downsize_idx = compute_downsize_year_index(config)
+    affordable = None if downsize_failed_mask is None else ~downsize_failed_mask
+    liquid_rows: list[PortfolioAtAge] = []
+    total_rows: list[PortfolioAtAge] = []
+    for t in range(total_years):
+        counted = np.ones(n_paths, dtype=bool) if alive is None else alive[:, t]
+        share_alive = float(counted.mean())
+        if affordable is not None and downsize_idx is not None and t > downsize_idx and (counted & affordable).any():
+            counted = counted & affordable
+        percentiles = _percentiles_over(values[:, t], counted, (10, 25, 50, 75, 90))
+        age, phase = current_age + t + 1, "accumulation" if t < config.accumulation_years else "drawdown"
+        liquid_rows.append(_row(age, phase, percentiles, share_alive))
+        if net_equities is not None:
+            equity = float(net_equities[t])
+            with_equity = [None if p is None else p + equity for p in percentiles]
+            total_rows.append(_row(age, phase, with_equity, share_alive))
+        else:
+            total_rows.append(liquid_rows[-1])
+
+    drawdown_values = values[:, config.accumulation_years :]
+    depleted = (drawdown_values == 0).any(axis=1)
+    success_rate = float(1 - depleted.mean())
+    return tuple(liquid_rows), tuple(total_rows), success_rate
+
+
+def _row(
+    age: int, phase: Literal["accumulation", "drawdown"], percentiles: Sequence[float | None], share_alive: float
+) -> PortfolioAtAge:
+    p10, p25, p50, p75, p90 = percentiles
+    return PortfolioAtAge(age=age, phase=phase, p10=p10, p25=p25, p50=p50, p75=p75, p90=p90, share_alive=share_alive)
+
+
+def _percentiles_over(year: np.ndarray, counted: np.ndarray, levels: Sequence[int]) -> list[float | None]:
+    """The percentiles ``levels`` (10, ...) of one year's (n,) values over the futures ``counted`` (n,) at it, the
+    ones alive at that age; None for each when none is (decision 26)."""
+    values = year[counted]
+    if not values.size:
+        return [None] * len(levels)
+    return [float(p) for p in np.percentile(values, list(levels))]
+
+
+def spending_by_age(
+    spending_level: np.ndarray, alive: np.ndarray, *, current_age: int, retired_from: int
+) -> tuple[SpendingAtAge, ...]:
+    """The Sustainable rule's level by age from Retirement: p10, p50 and p90 over the futures alive at each age.
+
+    ``spending_level`` and ``alive`` are the year loop's (n, T) arrays, the level in today's € before cost of living,
+    the age band and noise (decision 28). One record per model year from ``retired_from``, the first
+    retired one, at the age the year ends at; an age no future reaches has no percentiles.
+    """
+    records = []
+    for t in range(retired_from, spending_level.shape[1]):
+        p10, p50, p90 = _percentiles_over(spending_level[:, t], alive[:, t], (10, 50, 90))
+        records.append(SpendingAtAge(age=current_age + t + 1, p10=p10, p50=p50, p90=p90))
+    return tuple(records)

manyfutures/constants.py

@@ -0,0 +1,96 @@
+"""The engine's model constants: the defaults of the Assumptions' model constants and the engine's own settings.
+
+No household's facts are here: the Assumptions require them of the caller (decision 9).
+"""
+
+from __future__ import annotations
+
+# The loan a downsize takes on the new home is an annuity over this many years, the longest whose interest is
+# deductible in the Netherlands; its rate is that of the mortgage the household has (decision 9)
+DOWNSIZE_MORTGAGE_TERM = 30
+
+# Ages
+PENSION_AGE = 67  # the state-pension age, from which the pension is paid
+MAX_MODEL_AGE = 100
+AOW_AGE = 67  # NL state-pension age; below this, Box 1 bracket-1 includes ~27.65% premies
+GBP_EUR_FIXED_RATE = 1.15  # GBP→EUR spot, 2026-05-12 (poundsterlinglive.com)
+
+# Simulation assumptions
+INFLATION_RATE = 0.025
+EXPENSE_RATIO = 0.0035
+BLOCK_LENGTH = 5
+PROPERTY_TAX_RATE = 0.005
+MAINTENANCE_RATE = 0.01
+N_SIMS_DRAFT = 5_000
+N_SIMS_FULL = 25_000
+_Z_90 = 1.2815515655446004  # scipy.stats.norm.ppf(0.90)
+
+# Child cost brackets (Nibud, annual €, today's money)
+CHILD_COSTS: list[tuple[int, int, float]] = [(0, 3, 7_000), (4, 11, 9_000), (12, 17, 11_000), (18, 21, 13_000)]
+CHILD_CASH_RESERVE_STEP = 7_000
+
+# Property assumptions
+PROPERTY_APPRECIATION_RATE = 0.035  # 3.5%/yr nominal, the deterministic mortgage schedule's
+REAL_HOME_APPRECIATION = 0.01  # 1%/yr above CPI: the target each path's home value reverts to
+# After a Last-resort Sale the household rents at this share of the sold home's value a year, rising with the path's
+# CPI from the sale (decision 33).
+RENT_RATE = 0.04
+
+# The long-life line gives the headline's readouts over the futures whose End Age is this age or later
+# (decision 29): what a long life looks like.
+LONG_LIFE_AGE = 95
+
+# A year is Running Short when more than this share of its Must-have Spending goes unfunded (decision 27):
+# less left unfunded is within ordinary spending noise.
+RUNNING_SHORT_THRESHOLD = 0.10
+
+# The Return Band (decision 32): the headline is also run with every year's return this much lower and
+# this much higher, on the same random futures.
+RETURN_BAND_WIDTH = 0.01
+
+# The Sustainable Spending Rule (decision 28): each retired year it spends what the money can carry to
+# the planning age at the planning rate (real), moving at most a tenth a year and never above the ceiling times the
+# chosen annual spending. A fall in its level of the cut threshold or more is a cut.
+SUSTAINABLE_PLANNING_AGE = 95
+SUSTAINABLE_PLANNING_RATE = 0.02
+SUSTAINABLE_MAX_CHANGE = 0.10
+SUSTAINABLE_CEILING = 1.5
+SUSTAINABLE_CUT_THRESHOLD = 0.05
+
+# Retirement real-spending multipliers by age band (applied to baseline household spending only).
+RETIREMENT_SPENDING_BANDS: list[tuple[int, int, float]] = [
+    (0, 66, 1.00),
+    (67, 74, 0.90),
+    (75, 84, 0.80),
+    (85, 200, 0.85),
+]
+
+__all__ = [
+    "AOW_AGE",
+    "BLOCK_LENGTH",
+    "CHILD_CASH_RESERVE_STEP",
+    "CHILD_COSTS",
+    "DOWNSIZE_MORTGAGE_TERM",
+    "EXPENSE_RATIO",
+    "GBP_EUR_FIXED_RATE",
+    "INFLATION_RATE",
+    "LONG_LIFE_AGE",
+    "MAINTENANCE_RATE",
+    "MAX_MODEL_AGE",
+    "N_SIMS_DRAFT",
+    "N_SIMS_FULL",
+    "PENSION_AGE",
+    "PROPERTY_APPRECIATION_RATE",
+    "PROPERTY_TAX_RATE",
+    "REAL_HOME_APPRECIATION",
+    "RENT_RATE",
+    "RETIREMENT_SPENDING_BANDS",
+    "RETURN_BAND_WIDTH",
+    "RUNNING_SHORT_THRESHOLD",
+    "SUSTAINABLE_CEILING",
+    "SUSTAINABLE_CUT_THRESHOLD",
+    "SUSTAINABLE_MAX_CHANGE",
+    "SUSTAINABLE_PLANNING_AGE",
+    "SUSTAINABLE_PLANNING_RATE",
+    "_Z_90",
+]

manyfutures/data.py

@@ -0,0 +1,127 @@
+"""The engine's data: the bundled life table and US inflation, and the type of the return history a Start carries.
+
+Only readers of the files bundled beside this module: nothing here fetches. The caller fetches the market's returns
+and hands them to the engine as ``AnnualReturns``.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from datetime import date
+from functools import cache
+from pathlib import Path
+from typing import get_args
+
+import numpy as np
+
+from manyfutures.models import InflationHistory, LifeSeries, LifeTable
+
+__all__ = [
+    "AnnualReturns",
+    "inflation_history",
+    "life_table",
+    "parse_inflation_history",
+]
+
+
+@dataclass(frozen=True, eq=False)
+class AnnualReturns:
+    """Calendar-year returns, each labelled by its year: ``returns[i]`` is the change over ``years[i]``.
+
+    A year's return is its last close over the year before's, price-only (no dividends). The current year is
+    included while it is still partial; a run leaves it out, with every year that has no US inflation, and takes
+    each other year's real return with that year's own inflation (decision 2).
+    """
+
+    years: np.ndarray  # int, ascending
+    returns: np.ndarray  # float, one per year
+
+
+_LIFE_TABLE = Path(__file__).with_name("life_table.csv")
+
+
+@cache
+def life_table() -> LifeTable:
+    """The bundled life table End Ages are drawn from: CBS's projected chances of dying, for men and for women, at
+    every age in every year from 2025 to 2070 (decision 26).
+
+    The file's ``# source_url:`` and ``# source_date:`` header lines fill those fields; its other header lines are
+    the notes: what was taken, how it was reduced, and the licence. Every series must give a chance at every age
+    from 0 and in every year from the first, and nothing else.
+    """
+    header, notes, rows = _commented_csv(_LIFE_TABLE.read_text(encoding="utf-8"))
+    chances: dict[tuple[str, int, int], float] = {}
+    for row in csv.DictReader(rows):
+        key = (row["series"], int(row["age"]), int(row["year"]))
+        if key in chances:
+            raise ValueError(f"{_LIFE_TABLE.name}: two chances for {key}")  # noqa: TRY003
+        chances[key] = float(row["death_probability"])
+    ages = range(max(age for _, age, _ in chances) + 1)
+    years = range(min(year for *_, year in chances), max(year for *_, year in chances) + 1)
+    every_series = get_args(LifeSeries)
+    if len(chances) != len(every_series) * len(ages) * len(years) or {s for s, *_ in chances} != set(every_series):
+        raise ValueError(f"{_LIFE_TABLE.name}: not one chance for each series at every age in every year")  # noqa: TRY003
+    return LifeTable(
+        source_url=header["source_url"],
+        source_date=header["source_date"],
+        notes=" ".join(notes),
+        first_year=years.start,
+        chances={
+            series: tuple(tuple(chances[series, age, year] for year in years) for age in ages)
+            for series in every_series
+        },
+    )
+
+
+def _commented_csv(text: str) -> tuple[dict[str, str], list[str], list[str]]:
+    """A bundled CSV's ``# source_url:`` and ``# source_date:`` header lines, its other header lines, and its rows."""
+    header: dict[str, str] = {}
+    notes: list[str] = []
+    rows: list[str] = []
+    for line in text.splitlines():
+        if not line.startswith("#"):
+            rows.append(line)
+            continue
+        key, sep, value = line.removeprefix("#").strip().partition(": ")
+        if sep and key in ("source_url", "source_date"):
+            header[key] = value
+        else:
+            notes.append(line.removeprefix("#").strip())
+    return header, notes, rows
+
+
+_US_CPI = Path(__file__).with_name("us_cpi.csv")
+
+
+@cache
+def inflation_history() -> InflationHistory:
+    """The bundled US inflation each year's real return is taken with: the CPI-U's December-to-December change in
+    every year from 1928 to the latest complete year (decision 2)."""
+    return parse_inflation_history(_US_CPI.read_text(encoding="utf-8"))
+
+
+def parse_inflation_history(cpi_csv: str) -> InflationHistory:
+    """FRED's ``observation_date,CPIAUCNS`` rows → each calendar year's December-to-December inflation.
+
+    Only each December's index is read, so another month, missing or blank, changes nothing; a year has inflation
+    when its December and the December before it both have a value. The ``# source_url:`` and ``# source_date:``
+    header lines fill those fields and the other header lines are the notes.
+    """
+    header, notes, rows = _commented_csv(cpi_csv)
+    december: dict[int, float] = {}
+    for row in csv.DictReader(rows):
+        observed, value = date.fromisoformat(row["observation_date"]), row["CPIAUCNS"].strip()
+        if observed.month != 12 or not value:
+            continue
+        if observed.year in december:
+            raise ValueError(f"Two December values for {observed.year}")  # noqa: TRY003
+        december[observed.year] = float(value)
+    years = tuple(year for year in sorted(december) if year - 1 in december)
+    return InflationHistory(
+        source_url=header["source_url"],
+        source_date=header["source_date"],
+        notes=" ".join(notes),
+        years=years,
+        inflation=tuple(december[year] / december[year - 1] - 1 for year in years),
+    )