glidepath 0.2.0__py3-none-any.whl

glidepath/core/retirement.py

@@ -0,0 +1,291 @@
+"""The retirement-question solvers (roadmap 9.14, 9.25; planning §5.2).
+
+:func:`earliest_retirement_age` finds the earliest target retirement
+age at which the plan sustains a target retirement income — the age
+counterpart of :func:`~glidepath.core.montecarlo.sustainable_income`
+(roadmap 7.3): the same probe-plan-per-candidate search over runs,
+searching the retirement-age decision instead of the spending level.
+Where the spending search bisects a continuous bracket, the age domain
+is a few dozen whole years, so an ascending scan probes every
+candidate: the returned age is exactly the earliest succeeding one
+even when success is not monotone in age (a DB scheme's early-payment
+factors or a dated outflow can make it dip), and every answer was
+actually probed, never interpolated. A candidate whose retirement
+date falls at or past the run's horizon has no retired period to test
+the income in — it fails rather than succeeding vacuously.
+
+Each probe replaces the (v1 single) person's retirement-age decision
+with the candidate and the household's spending plan with the target
+income, then runs the plan under the given config. Under a
+deterministic config a candidate succeeds when no period's need goes
+unmet — the same per-period ``shortfall`` ruin signal the Monte Carlo
+metrics read (planning §5.2). Under a seeded Monte Carlo config the
+candidate's paths run through :func:`~glidepath.core.run_paths` and
+success means their success rate meets the search's target — "earliest
+age with ≥ N% Monte Carlo success". Every probe reuses the same config
+(common random numbers), so the search is reproducible from the seed
+alone (§4.6), and probe plans never leave the search.
+
+:func:`sustainable_income_at_age` is the same question asked the
+other way around (roadmap 9.25): "how much can I draw down if I
+retire at this age?" — the retirement-age decision is fixed at the
+chosen age and the spending level is searched, delegating to the
+7.3 income search under the same exposure gate: an age with no
+retired period inside the run's horizon has nothing to test the
+income in, so it answers ``None`` rather than succeeding vacuously.
+"""
+
+from dataclasses import dataclass, replace
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from glidepath.core.config import RunMode
+from glidepath.core.engine import run
+from glidepath.core.money import Money
+from glidepath.core.montecarlo import (
+    has_shortfall,
+    probe_with_spending,
+    run_paths,
+    sustainable_income,
+)
+from glidepath.core.periods import date_age_attained, is_age_attained_by_period_start
+from glidepath.core.provenance import AssumptionKey, int_assumption_value
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from glidepath.core.config import RunConfig
+    from glidepath.core.entities import Household, Person
+    from glidepath.core.montecarlo import PathParallelism, SustainableIncomeSearch
+    from glidepath.core.periods import Period
+    from glidepath.core.provenance import AssumptionSet
+    from glidepath.core.region import Region
+
+_ZERO = Money(Decimal(0))
+_ONE = Decimal(1)
+
+
+@dataclass(frozen=True, slots=True)
+class RetirementAgeSearch:
+    """The parameters of one earliest-retirement-age search (9.14).
+
+    ``target_income`` is the real (today's money) net annual retirement
+    income the plan must sustain — the replacement-rate target the app
+    layer derives from employment income. Candidate ages run from
+    ``minimum_age`` to ``maximum_age`` inclusive; a candidate at or
+    below the person's current age simply retires the plan from its
+    first period (the engine's §4.1 gate convention), so "retire now"
+    is an ordinary probe. ``paths`` and ``target_success_rate`` apply
+    only under a Monte Carlo config: a candidate succeeds when at least
+    the target fraction of its seeded paths avoid ruin. A deterministic
+    probe ignores them — success is one run with no unmet need, the
+    single-path equivalent of a 100% target.
+    """
+
+    target_income: Money
+    minimum_age: int
+    maximum_age: int
+    paths: int = 1
+    target_success_rate: Decimal = _ONE
+
+    def __post_init__(self) -> None:
+        """Reject an empty target, a backwards bracket, or off-range knobs."""
+        if self.target_income <= _ZERO:
+            msg = "target_income must be positive"
+            raise ValueError(msg)
+        if self.minimum_age < 0:
+            msg = f"minimum_age must be non-negative, got {self.minimum_age}"
+            raise ValueError(msg)
+        if self.maximum_age < self.minimum_age:
+            msg = (
+                f"maximum_age {self.maximum_age} precedes"
+                f" minimum_age {self.minimum_age}"
+            )
+            raise ValueError(msg)
+        if self.paths < 1:
+            msg = f"paths must be positive, got {self.paths}"
+            raise ValueError(msg)
+        if not Decimal(0) < self.target_success_rate <= _ONE:
+            msg = (
+                "target_success_rate must lie in (0, 1],"
+                f" got {self.target_success_rate}"
+            )
+            raise ValueError(msg)
+
+
+def earliest_retirement_age(
+    plan: Household,
+    assumptions: AssumptionSet,
+    region: Region,
+    config: RunConfig,
+    search: RetirementAgeSearch,
+    *,
+    parallelism: PathParallelism | None = None,
+) -> int | None:
+    """The earliest retirement age sustaining the target income (9.14).
+
+    Probes every age in the search bracket in ascending order and
+    returns the first that succeeds — exactly the earliest, whatever
+    the success shape over ages (module docstring) — or ``None`` when
+    no age in the bracket does. A candidate with no *retirement
+    exposure* — no projected period opening the plan retired under the
+    §4.1 gate convention, because its retirement date falls at or past
+    the run's horizon — never tests the target income at all, so it
+    fails rather than succeeding vacuously; such candidates are never
+    probed. The plan's stated retirement age and spending level are
+    irrelevant to the search: each probe carries the candidate age and
+    the target income instead, everything else unchanged, and
+    re-running the plan at the returned age with the target income as
+    its spending reproduces the success. ``parallelism`` spreads each
+    Monte Carlo candidate's paths over its executor
+    (:class:`~glidepath.core.montecarlo.PathParallelism` — results
+    identical to a serial search); pass one executor for the whole
+    search so candidates share it rather than paying process startup
+    per age.
+
+    Raises:
+        EngineError: If a probe is rejected by the engine — including a
+            Monte Carlo config without a seed (planning §5.2).
+    """
+    date_of_birth = plan.persons[0].date_of_birth.value
+    periods = _projected_periods(plan, assumptions, region, config)
+
+    def has_retired_period(age: int) -> bool:
+        """Whether any projected period opens the plan retired (§4.1)."""
+        return any(
+            is_age_attained_by_period_start(date_of_birth, age, period)
+            for period in periods
+        )
+
+    def meets(age: int) -> bool:
+        """Whether retiring at ``age`` sustains the target income."""
+        probe = _with_retirement_age(
+            probe_with_spending(plan, search.target_income, config), age
+        )
+        if config.mode is RunMode.MONTE_CARLO:
+            result = run_paths(
+                probe,
+                assumptions,
+                region,
+                config,
+                paths=search.paths,
+                parallelism=parallelism,
+            )
+            return result.success_rate >= search.target_success_rate
+        return not has_shortfall(run(probe, assumptions, region, config))
+
+    for age in range(search.minimum_age, search.maximum_age + 1):
+        if has_retired_period(age) and meets(age):
+            return age
+    return None
+
+
+def sustainable_income_at_age(
+    plan: Household,
+    assumptions: AssumptionSet,
+    region: Region,
+    config: RunConfig,
+    *,
+    age: int,
+    search: SustainableIncomeSearch,
+    parallelism: PathParallelism | None = None,
+) -> Money | None:
+    """The highest income sustainable when retiring at ``age`` (9.25).
+
+    The drawdown dual of :func:`earliest_retirement_age`: the (v1
+    single) person's retirement-age decision is replaced with ``age``
+    and the spending level is searched through
+    :func:`~glidepath.core.montecarlo.sustainable_income` — the same
+    scan-plus-bisection over the search's bracket, the same success
+    reading per probe (no unmet need under a deterministic config;
+    "success rate ≥ target" over the seeded paths under a Monte Carlo
+    one), and the same reproducibility: every probe reuses ``config``
+    unchanged, so the answer is reproducible from the recorded inputs
+    (and seed) alone (§4.6). The plan's stated retirement age and
+    spending level are both irrelevant — the probes carry the chosen
+    age and the candidate spending instead, everything else unchanged.
+
+    An ``age`` with no *retirement exposure* — no projected period
+    opening the plan retired under the §4.1 gate convention, because
+    its retirement date falls at or past the run's horizon — has no
+    retired period to test any income in: spending is modelled only in
+    retirement, so every level would succeed vacuously. It answers
+    ``None`` without probing, exactly as such candidates fail in the
+    age search. ``None`` otherwise means what the income search means
+    by it: not even zero spending survives the plan's outflows.
+
+    Raises:
+        ValueError: If ``age`` is negative.
+        EngineError: If a probe is rejected by the engine — including
+            a Monte Carlo config without a seed (planning §5.2).
+    """
+    if age < 0:
+        msg = f"age must be non-negative, got {age}"
+        raise ValueError(msg)
+    date_of_birth = plan.persons[0].date_of_birth.value
+    exposed = any(
+        is_age_attained_by_period_start(date_of_birth, age, period)
+        for period in _projected_periods(plan, assumptions, region, config)
+    )
+    if not exposed:
+        return None
+    return sustainable_income(
+        _with_retirement_age(plan, age),
+        assumptions,
+        region,
+        config,
+        search,
+        parallelism=parallelism,
+    )
+
+
+def _projected_periods(
+    plan: Household, assumptions: AssumptionSet, region: Region, config: RunConfig
+) -> tuple[Period, ...]:
+    """The periods a probe under ``config`` would project (§5.2).
+
+    What the solvers' exposure gates scan: the run's own calendar over
+    its own horizon, computed exactly as the engine would.
+    """
+    return tuple(
+        region.calendar.periods(config.today, _horizon_end(plan, assumptions, config))
+    )
+
+
+def _horizon_end(
+    plan: Household, assumptions: AssumptionSet, config: RunConfig
+) -> date:
+    """The run's horizon end: configured, or the planning-age default.
+
+    The same resolution the engine applies (planning §5.2), computed
+    here so the exposure gate can see the periods a probe would
+    project. v1 households hold one person (§4.4), whose date of birth
+    anchors the default.
+    """
+    if config.horizon_end is not None:
+        return config.horizon_end
+    planning_age = int_assumption_value(
+        assumptions.get(AssumptionKey.HORIZON_PLANNING_AGE)
+    )
+    return date_age_attained(plan.persons[0].date_of_birth.value, planning_age)
+
+
+def _with_retirement_age(plan: Household, age: int) -> Household:
+    """The plan with every person's retirement-age decision at ``age``.
+
+    v1 households hold one person (§4.4), so this is *the* person's
+    decision; the decision's recorded-on metadata carries over, exactly
+    as a scenario override resolves (§4.3). Couples activation (9.4)
+    will need a per-person target here.
+    """
+    persons = tuple(_person_at_retirement_age(person, age) for person in plan.persons)
+    changes: dict[str, Any] = {"persons": persons}
+    return replace(plan, **changes) if changes else plan
+
+
+def _person_at_retirement_age(person: Person, age: int) -> Person:
+    """One person with their retirement-age decision's value replaced."""
+    decision_changes: dict[str, Any] = {"value": age}
+    decision = replace(person.target_retirement_age, **decision_changes)
+    changes: dict[str, Any] = {"target_retirement_age": decision}
+    return replace(person, **changes) if changes else person

glidepath/core/returns.py

@@ -0,0 +1,312 @@
+"""Period returns and the return-model boundary (roadmap 4.1; planning §5.2).
+
+The engine applies one set of nominal asset-class returns and one CPI
+rate per period — "one inflation truth per run" (planning §5.2): the
+reporting layer (roadmap 4.4) deflates by the same CPI path the engine
+grew nominal figures with. A :class:`ReturnModel` supplies both
+together as a :class:`PeriodReturns`, so they cannot drift apart.
+
+The same step function runs under the deterministic and Monte Carlo
+modes; only the return model differs (planning §5.2, a design
+invariant). :class:`DeterministicReturnModel` turns the expected
+real-return assumptions plus the CPI assumption into the same nominal
+returns every period and every path. :class:`StochasticReturnModel`
+(roadmap 7.2) draws correlated lognormal nominal returns instead —
+seeded, pure per ``(seed, path, period)``, mean-matched to the
+deterministic composition — while CPI stays the assumed deterministic
+path on every Monte Carlo path, keeping the single-inflation-truth
+rule intact (stochastic inflation is out of v1 scope; the assumption
+catalogue prices no CPI volatility).
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING, Protocol
+
+from glidepath.core.investments import AssetReturns
+from glidepath.core.money import Rate
+from glidepath.core.provenance import AssumptionKey, decimal_assumption_value
+from glidepath.core.randomness import RandomSource, SeededRandomSource, derive_seed
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from glidepath.core.periods import Period
+    from glidepath.core.provenance import TrackedAssumptions
+
+_MINUS_ONE = Decimal(-1)
+_ZERO = Decimal(0)
+_ONE = Decimal(1)
+_TWO = Decimal(2)
+_ASSET_CLASS_COUNT = 3
+
+
+@dataclass(frozen=True, slots=True)
+class PeriodReturns:
+    """One period's nominal asset returns and CPI rate, together.
+
+    Keeping the two in one value enforces the single-inflation-truth
+    rule (planning §5.2): the CPI that built the nominal returns is the
+    CPI the reporting layer deflates by.
+    """
+
+    assets: AssetReturns
+    cpi: Rate
+
+    def __post_init__(self) -> None:
+        """Reject a CPI at or below -100%.
+
+        Exactly -1 is rejected too: it would zero the cumulative
+        inflation factor and turn an accepted assumption into a
+        runtime failure one period later.
+        """
+        if self.cpi.value <= _MINUS_ONE:
+            msg = "PeriodReturns.cpi must be greater than -1"
+            raise ValueError(msg)
+
+
+class ReturnModel(Protocol):
+    """Supplies each period's returns (planning §5.2).
+
+    The engine step function is mode-agnostic: deterministic and Monte
+    Carlo runs differ only in which implementation they inject. Data
+    parameters are positional-only so implementations that need neither
+    (the deterministic model) remain protocol-compatible.
+    """
+
+    def returns_for(self, period: Period, path: int, /) -> PeriodReturns:
+        """The nominal returns and CPI for ``period`` on ``path``."""
+        ...
+
+
+type ReturnModelFactory = Callable[[TrackedAssumptions], ReturnModel]
+"""Builds a run's return model from the run's tracked assumption view.
+
+The engine constructs its tracked view internally (every key read must
+land in the run's provenance), so an injected model — a scripted
+sequence fixture (roadmap 7.4), an alternative distribution — enters
+through this factory rather than as a finished instance. A factory must
+preserve the engine's purity (planning §4.6): the model it returns may
+depend on nothing but the view it is given and its own frozen state.
+"""
+
+
+def nominal_rate(real: Decimal, cpi: Decimal) -> Rate:
+    """Compose a real rate with CPI into a nominal rate (planning §5.2).
+
+    ``(1 + real) * (1 + cpi) - 1`` — the exact Fisher composition, kept
+    unquantized like every rate (planning §4.6).
+    """
+    return Rate((_ONE + real) * (_ONE + cpi) - _ONE)
+
+
+@dataclass(frozen=True, slots=True)
+class DeterministicReturnModel:
+    """Expected-return model: the same nominal returns every period.
+
+    Reads the expected real returns per asset class and the CPI
+    assumption through the run's tracked view (so every key lands in
+    the run's provenance) and composes them into nominal rates. Every
+    period and every path sees the same value (planning §5.2).
+    """
+
+    assumptions: TrackedAssumptions
+
+    def returns_for(self, _period: Period, _path: int, /) -> PeriodReturns:
+        """The nominal returns and CPI (identical for every argument)."""
+        cpi = decimal_assumption_value(
+            self.assumptions.get(AssumptionKey.INFLATION_CPI)
+        )
+        real_rates = (
+            decimal_assumption_value(self.assumptions.get(key))
+            for key in (
+                AssumptionKey.RETURNS_EQUITY_REAL,
+                AssumptionKey.RETURNS_BONDS_REAL,
+                AssumptionKey.RETURNS_CASH_REAL,
+            )
+        )
+        equity, bonds, cash = (nominal_rate(real, cpi) for real in real_rates)
+        return PeriodReturns(
+            assets=AssetReturns(equity=equity, bonds=bonds, cash=cash),
+            cpi=Rate(cpi),
+        )
+
+
+def cholesky_lower(
+    matrix: tuple[tuple[Decimal, ...], ...],
+) -> tuple[tuple[Decimal, ...], ...]:
+    """Lower-triangular Cholesky factor of a symmetric matrix, in ``Decimal``.
+
+    ``L`` such that ``L @ L.T`` reproduces ``matrix`` (to context
+    precision), computed entirely in ``Decimal`` — the correlation
+    transform of planning §5.2 never touches float.
+
+    Raises:
+        ValueError: If the matrix is not square, not symmetric, or not
+            positive definite (a pivot fails to stay positive).
+    """
+    size = len(matrix)
+    if any(len(row) != size for row in matrix):
+        msg = "matrix must be square"
+        raise ValueError(msg)
+    if any(matrix[i][j] != matrix[j][i] for i in range(size) for j in range(i)):
+        msg = "matrix must be symmetric"
+        raise ValueError(msg)
+    rows: list[list[Decimal]] = [[_ZERO] * size for _ in range(size)]
+    for i in range(size):
+        for j in range(i + 1):
+            partial = sum((rows[i][k] * rows[j][k] for k in range(j)), start=_ZERO)
+            if i == j:
+                pivot = matrix[i][i] - partial
+                if pivot <= _ZERO:
+                    msg = "matrix is not positive definite"
+                    raise ValueError(msg)
+                rows[i][j] = pivot.sqrt()
+            else:
+                rows[i][j] = (matrix[i][j] - partial) / rows[j][j]
+    return tuple(tuple(row) for row in rows)
+
+
+@dataclass(frozen=True, slots=True)
+class StochasticReturnModel:
+    """Correlated lognormal return model for Monte Carlo (roadmap 7.2).
+
+    Per asset class the period's nominal gross return is lognormal with
+    its arithmetic mean equal to the deterministic composition
+    ``(1 + real)(1 + cpi)`` — so the expected outcome of a Monte Carlo
+    run agrees with the deterministic run by construction. The assumed
+    volatility is read as the standard deviation of the annual
+    log-return; draws are correlated across the three classes (in the
+    fixed order equity, bonds, cash) through the ``Decimal`` Cholesky
+    factor of the pairwise correlation assumptions. CPI stays the
+    assumed deterministic value on every path (module docstring).
+
+    Purity (planning §4.6): each ``(period, path)`` pair reads its
+    draws from a private substream seeded by
+    ``derive_seed(seed, path, period start)``, so results depend only
+    on the arguments — call order is irrelevant, paths are
+    order-independent, and any single period of any path is
+    individually re-runnable.
+
+    ``source_factory`` is the injectable :class:`RandomSource`
+    boundary of planning §4.6: it builds the substream for a derived
+    seed, defaulting to :class:`SeededRandomSource`. Injecting a
+    factory (a test double, an alternative generator) must preserve
+    purity: the source it returns may depend on nothing but the seed
+    it is given.
+    """
+
+    assumptions: TrackedAssumptions
+    seed: int
+    source_factory: Callable[[int], RandomSource] = SeededRandomSource
+
+    def returns_for(self, period: Period, path: int, /) -> PeriodReturns:
+        """Draw the period's correlated nominal returns on ``path``.
+
+        Raises:
+            ValueError: If an assumed volatility is negative, a
+                correlation falls outside [-1, 1] or the correlation
+                matrix is not positive definite, or an expected
+                nominal gross return is not positive (its logarithm
+                would be undefined).
+        """
+        cpi = decimal_assumption_value(
+            self.assumptions.get(AssumptionKey.INFLATION_CPI)
+        )
+        grosses = tuple(
+            self._expected_gross(key, cpi)
+            for key in (
+                AssumptionKey.RETURNS_EQUITY_REAL,
+                AssumptionKey.RETURNS_BONDS_REAL,
+                AssumptionKey.RETURNS_CASH_REAL,
+            )
+        )
+        sigmas = tuple(
+            self._volatility(key)
+            for key in (
+                AssumptionKey.VOLATILITY_EQUITY,
+                AssumptionKey.VOLATILITY_BONDS,
+                AssumptionKey.VOLATILITY_CASH,
+            )
+        )
+        factor = cholesky_lower(self._correlation_matrix())
+        source = self.source_factory(
+            derive_seed(self.seed, path, period.start.isoformat())
+        )
+        draws = source.standard_normals(_ASSET_CLASS_COUNT)
+        correlated = (
+            sum((row[k] * draws[k] for k in range(_ASSET_CLASS_COUNT)), start=_ZERO)
+            for row in factor
+        )
+        equity, bonds, cash = (
+            _lognormal_rate(gross, sigma, normal)
+            for gross, sigma, normal in zip(grosses, sigmas, correlated, strict=True)
+        )
+        return PeriodReturns(
+            assets=AssetReturns(equity=equity, bonds=bonds, cash=cash),
+            cpi=Rate(cpi),
+        )
+
+    def _expected_gross(self, key: AssumptionKey, cpi: Decimal) -> Decimal:
+        """The expected nominal gross return ``(1 + real)(1 + cpi)``.
+
+        Raises:
+            ValueError: If the gross is not positive — a lognormal
+                cannot have a non-positive mean.
+        """
+        real = decimal_assumption_value(self.assumptions.get(key))
+        gross = (_ONE + real) * (_ONE + cpi)
+        if gross <= _ZERO:
+            msg = f"expected nominal gross return for {key!r} must be positive"
+            raise ValueError(msg)
+        return gross
+
+    def _volatility(self, key: AssumptionKey) -> Decimal:
+        """The assumed annual log-return volatility, validated non-negative.
+
+        Raises:
+            ValueError: If the volatility is negative.
+        """
+        sigma = decimal_assumption_value(self.assumptions.get(key))
+        if sigma < _ZERO:
+            msg = f"volatility {key!r} must be non-negative"
+            raise ValueError(msg)
+        return sigma
+
+    def _correlation_matrix(self) -> tuple[tuple[Decimal, ...], ...]:
+        """The 3-by-3 correlation matrix in the equity, bonds, cash order.
+
+        Raises:
+            ValueError: If a pairwise correlation lies outside [-1, 1].
+        """
+        pairs: dict[AssumptionKey, Decimal] = {}
+        for key in (
+            AssumptionKey.CORRELATION_EQUITY_BONDS,
+            AssumptionKey.CORRELATION_EQUITY_CASH,
+            AssumptionKey.CORRELATION_BONDS_CASH,
+        ):
+            value = decimal_assumption_value(self.assumptions.get(key))
+            if not _MINUS_ONE <= value <= _ONE:
+                msg = f"correlation {key!r} must lie between -1 and 1"
+                raise ValueError(msg)
+            pairs[key] = value
+        equity_bonds = pairs[AssumptionKey.CORRELATION_EQUITY_BONDS]
+        equity_cash = pairs[AssumptionKey.CORRELATION_EQUITY_CASH]
+        bonds_cash = pairs[AssumptionKey.CORRELATION_BONDS_CASH]
+        return (
+            (_ONE, equity_bonds, equity_cash),
+            (equity_bonds, _ONE, bonds_cash),
+            (equity_cash, bonds_cash, _ONE),
+        )
+
+
+def _lognormal_rate(gross: Decimal, sigma: Decimal, normal: Decimal) -> Rate:
+    """One lognormal nominal return with arithmetic mean ``gross - 1``.
+
+    ``mu = ln(gross) - sigma²/2`` makes ``E[exp(mu + sigma·Z)]`` exactly
+    ``gross``, so with zero volatility the draw degenerates to the
+    deterministic nominal rate. Exponentials keep the gross strictly
+    positive: a lognormal loss can approach but never reach -100%.
+    """
+    mu = gross.ln() - sigma * sigma / _TWO
+    return Rate((mu + sigma * normal).exp() - _ONE)