"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Portfolio return when the client, not the manager, moves the money.
``backtest/metrics.py`` computes every figure from an equity curve and a single
scalar ``initial_cash``. That is the right model for a backtest, where the only
capital event is the opening deposit. It cannot express a real client account,
where money arrives and leaves on dates the manager did not choose. Feeding such
an account into a scalar-funded metric silently reports the *client's* deposits
as the *manager's* performance.
This module is the parallel path. It takes a valuation series plus an irregular
:class:`~src.entities.cashflow.CashFlowSeries` and reports the two answers that
actually exist, kept deliberately distinct:
``time_weighted_return``
True daily-valuation TWR. Chain-links the return of each interval between
valuations, so the size and the date of an external flow cancel out of the
product entirely. This is the manager-skill number, and it is what GIPS
composites report.
``modified_dietz_return``
The classic day-weighted *approximation* to a money-weighted return. It
needs only an opening value, a closing value, and dated flows -- no interim
valuations -- which is why it survives in reporting stacks that cannot
revalue daily. It is NOT a TWR, despite being widely mislabelled as one; it
weights each flow by the fraction of the period it was invested and is
therefore sensitive to flow timing.
``money_weighted_return``
The internal rate of return (XIRR) of the client's own cash: opening value
out, flows as they fell, closing value back. This is the client-experience
number, and it moves with how much money was exposed to which stretch of
the return path.
WHICH FLOWS ARE EXTERNAL
------------------------
Only movements **across the portfolio boundary** are external. A contribution,
capital call, subscription, transfer in, distribution, redemption, withdrawal,
or transfer out changes the capital base without the manager earning or losing
anything, so it must be removed before a return is struck
(:data:`DEFAULT_EXTERNAL_KINDS`).
A dividend, coupon, interest payment, fee, expense, purchase, or sale proceed is
**internal**: it is already inside the valuation series, and netting it out a
second time double-counts it (:data:`DEFAULT_INTERNAL_KINDS`). Valuation marks
(``nav``, ``residual_value``, ``valuation``) are not cash at all and are ignored.
A kind in neither table is an error, not a default. Silently ignoring an
unrecognised kind would understate the flow adjustment and produce a
plausible-looking wrong return; the caller must classify it explicitly through
``external_kinds=`` or ``internal_kinds=``.
SIGN CONVENTION
---------------
``CashFlow.amount`` is holder-perspective: a ``contribution`` is **negative**
because the cash leaves the client's pocket (see ``src.entities.cashflow``).
The portfolio sees the mirror image, so every external flow is negated exactly
once, here, at :func:`external_flows`. The library never asks a caller to flip
a sign, and :func:`money_weighted_return` consumes ``CashFlow.amount`` as-is
because the holder perspective *is* the IRR perspective.
Only the standard library is imported, matching the rest of ``quantlib``: an
optional numerical dependency missing elsewhere cannot break this module.
"""
from __future__ import annotations
import math
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from datetime import date, datetime
from src.entities.cashflow import CashFlow, CashFlowSeries, normalize_kind
from src.entities.models import normalize_date
__all__ = [
"DAYS_PER_YEAR",
"DEFAULT_EXTERNAL_KINDS",
"DEFAULT_INTERNAL_KINDS",
"FLOW_TIMING_END",
"FLOW_TIMING_START",
"ModifiedDietzReturn",
"MoneyWeightedReturn",
"SubPeriodReturn",
"TimeWeightedReturn",
"UnsolvableRateError",
"external_flows",
"modified_dietz_return",
"money_weighted_return",
"time_weighted_return",
"xirr",
]
#: Day basis for annualisation and for the XIRR time axis. 365 actual days is
#: the XIRR convention (and the one Excel's ``XIRR`` uses), not 252 trading
#: days: client cash moves on calendar dates, including weekends.
DAYS_PER_YEAR = 365.0
#: Kinds that move cash across the portfolio boundary. See the module docstring.
DEFAULT_EXTERNAL_KINDS: frozenset[str] = frozenset(
{
"contribution",
"capital_call",
"subscription",
"transfer_in",
"distribution",
"redemption",
"withdrawal",
"transfer_out",
}
)
#: Kinds that occur *inside* the portfolio and are therefore already reflected
#: in the valuation series. Netting them out again double-counts them.
DEFAULT_INTERNAL_KINDS: frozenset[str] = frozenset(
{
"dividend",
"coupon",
"interest",
"principal",
"fee",
"expense",
"purchase",
"proceeds",
}
)
#: A flow dated on a valuation date is deemed to settle *after* that valuation
#: is struck, so it belongs to the period that ends there.
FLOW_TIMING_END = "end"
#: A flow dated on a valuation date is deemed to settle *before* the next
#: interval begins, so it belongs to the period that starts there.
FLOW_TIMING_START = "start"
_FLOW_TIMINGS = (FLOW_TIMING_END, FLOW_TIMING_START)
#: Bisection floor for the IRR search. A rate at or below -100% would make the
#: discount base non-positive, so the solver stops just short of it.
_IRR_LOWER_BOUND = -0.999999
#: Largest rate the bracket expansion will reach before giving up.
_IRR_UPPER_LIMIT = 1e9
#: Absolute width of the final IRR bracket.
_IRR_TOLERANCE = 1e-12
#: Hard iteration cap for the bisection, so a pathological input cannot spin.
_IRR_MAX_ITERATIONS = 400
#: Magnitude returned in place of a diverging NPV term. At ``base`` just above
#: zero and a horizon beyond ~51 years the discount factor underflows to 0.0 and
#: the true term diverges to +/-inf. The bisection compares signs only, so a
#: sign-preserving finite stand-in keeps the bracketing exact without letting
#: :func:`math.fsum` overflow.
_NPV_DIVERGED_MAGNITUDE = 1e300
class UnsolvableRateError(ValueError):
"""Raised when a cash-flow stream admits no single internal rate of return."""
@dataclass(frozen=True)
class SubPeriodReturn:
"""One interval between two consecutive valuations.
Attributes:
start: Date of the opening valuation of the interval.
end: Date of the closing valuation of the interval.
start_value: Portfolio value at ``start``.
end_value: Portfolio value at ``end``.
external_flow: Net external cash into the portfolio during the
interval, portfolio-perspective (positive is money arriving).
period_return: Return of the interval with the external flow removed.
"""
start: date
end: date
start_value: float
end_value: float
external_flow: float
period_return: float
@dataclass(frozen=True)
class TimeWeightedReturn:
"""Chain-linked true time-weighted return over the whole window.
Attributes:
total_return: Compounded return, ``prod(1 + r_i) - 1``.
sub_periods: Every interval's decomposition, in date order.
start_date: Date of the first valuation.
end_date: Date of the last valuation.
start_value: Value at ``start_date``.
end_value: Value at ``end_date``.
net_external_flow: Sum of the external flows, portfolio-perspective.
flow_timing: Which boundary a flow dated on a valuation date was
assigned to; see :data:`FLOW_TIMING_END` and
:data:`FLOW_TIMING_START`.
annualized_return: Geometrically annualised ``total_return``, or
``None`` when the window is shorter than a year. Annualising a
three-month figure states a full-year result that was never
observed, so it is withheld rather than extrapolated.
"""
total_return: float
sub_periods: tuple[SubPeriodReturn, ...]
start_date: date
end_date: date
start_value: float
end_value: float
net_external_flow: float
flow_timing: str
annualized_return: float | None
@dataclass(frozen=True)
class ModifiedDietzReturn:
"""Day-weighted money-weighted approximation over a single period.
Attributes:
total_return: ``(V1 - V0 - F) / (V0 + sum(w_i * F_i))``.
start_date: Opening date of the period.
end_date: Closing date of the period.
start_value: Value at ``start_date``.
end_value: Value at ``end_date``.
net_external_flow: ``F``, the sum of external flows.
weighted_external_flow: ``sum(w_i * F_i)``.
average_capital: The denominator, ``V0 + sum(w_i * F_i)``.
flow_weights: ``(date, amount, weight)`` per external flow, in date
order, so a reported figure can be audited line by line.
annualized_return: Geometrically annualised ``total_return``, or
``None`` for a window shorter than a year.
"""
total_return: float
start_date: date
end_date: date
start_value: float
end_value: float
net_external_flow: float
weighted_external_flow: float
average_capital: float
flow_weights: tuple[tuple[date, float, float], ...]
annualized_return: float | None
@dataclass(frozen=True)
class MoneyWeightedReturn:
"""Internal rate of return of the client's own cash.
Attributes:
annualized_return: The XIRR itself, an annual rate on a
:data:`DAYS_PER_YEAR` actual-day basis.
period_return: ``(1 + annualized_return) ** years - 1``, the same rate
expressed over the observed window rather than per annum.
start_date: Date of the opening valuation.
end_date: Date of the closing valuation.
start_value: Opening value, entered into the IRR as an outflow.
end_value: Closing value, entered into the IRR as an inflow.
net_external_flow: Net external cash into the portfolio,
portfolio-perspective, for reconciliation against the TWR result.
years: Window length in years on the same actual-day basis.
iterations: Bisection steps the solver used, exposed so a
near-degenerate stream is visible rather than silently trusted.
"""
annualized_return: float
period_return: float
start_date: date
end_date: date
start_value: float
end_value: float
net_external_flow: float
years: float
iterations: int
# ─── Input normalisation ───
def _normalize_valuations(
valuations: Mapping[date | datetime | str, float]
| Sequence[tuple[date | datetime | str, float]],
) -> tuple[tuple[date, float], ...]:
"""Coerce a valuation series to sorted ``(date, value)`` pairs.
Args:
valuations: Either a mapping of date to value, or a sequence of
two-element ``(date, value)`` pairs. Dates go through
``src.entities.models.normalize_date``, so ISO-8601 strings and
``datetime`` instances are accepted.
Returns:
Pairs sorted by date, with at least two entries.
Raises:
ValueError: If fewer than two valuations were supplied, a pair is
malformed, a value is not finite, or a date repeats. A repeated
date is rejected rather than deduplicated because two different
marks for one day have no defensible ordering.
"""
if isinstance(valuations, Mapping):
raw_items: list[tuple[object, object]] = list(valuations.items())
else:
raw_items = []
for index, item in enumerate(valuations):
if isinstance(item, (str, bytes)) or not isinstance(item, Sequence):
raise ValueError(
f"valuations[{index}] must be a (date, value) pair, got "
f"{type(item).__name__}"
)
pair = tuple(item)
if len(pair) != 2:
raise ValueError(
f"valuations[{index}] must have exactly two elements "
f"(date, value), got {len(pair)}"
)
raw_items.append((pair[0], pair[1]))
if len(raw_items) < 2:
raise ValueError(
"a return needs an opening and a closing valuation; got "
f"{len(raw_items)}"
)
resolved: list[tuple[date, float]] = []
for raw_date, raw_value in raw_items:
when = normalize_date(raw_date, field_name="valuation date")
try:
value = float(raw_value)
except (TypeError, ValueError) as exc:
raise ValueError(
f"valuation on {when} must be numeric, got {raw_value!r}"
) from exc
if not math.isfinite(value):
raise ValueError(
f"valuation on {when} must be finite, got {raw_value!r}; a "
"missing mark must be fixed at the source, not carried as NaN"
)
resolved.append((when, value))
resolved.sort(key=lambda item: item[0])
for earlier, later in zip(resolved, resolved[1:], strict=False):
if earlier[0] == later[0]:
raise ValueError(
f"two valuations share the date {earlier[0]}; a single day can "
"carry only one mark"
)
return tuple(resolved)
def external_flows(
flows: CashFlowSeries | Iterable[CashFlow] | None,
*,
external_kinds: Iterable[str] | None = None,
internal_kinds: Iterable[str] | None = None,
) -> tuple[tuple[date, float], ...]:
"""Select the boundary-crossing flows and restate them portfolio-side.
The returned amounts are the **negation** of ``CashFlow.amount``: the input
is holder-perspective (a contribution is cash leaving the client, hence
negative), the output is portfolio-perspective (a contribution is cash
arriving, hence positive). This is the only place in the module where that
flip happens.
Args:
flows: A ``CashFlowSeries``, any iterable of ``CashFlow``, or ``None``
for a period with no client activity.
external_kinds: Kinds to treat as boundary-crossing. Defaults to
:data:`DEFAULT_EXTERNAL_KINDS`. Labels are normalised, so
``"Capital Call"`` matches ``"capital_call"``.
internal_kinds: Kinds to treat as already inside the valuation series.
Defaults to :data:`DEFAULT_INTERNAL_KINDS`.
Returns:
``(date, amount_into_portfolio)`` pairs in date order. Several flows on
one date stay as several entries; callers that need one number per date
aggregate themselves.
Raises:
ValueError: If a flow's kind appears in both classifications, or in
neither. An unclassified kind is refused rather than assumed
internal, because assuming would understate the flow adjustment and
return a plausible wrong number.
"""
if flows is None:
return ()
external = (
DEFAULT_EXTERNAL_KINDS
if external_kinds is None
else frozenset(normalize_kind(kind) for kind in external_kinds)
)
internal = (
DEFAULT_INTERNAL_KINDS
if internal_kinds is None
else frozenset(normalize_kind(kind) for kind in internal_kinds)
)
overlap = external & internal
if overlap:
raise ValueError(
"a kind cannot be both external and internal; overlapping: "
f"{', '.join(sorted(overlap))}"
)
selected: list[tuple[date, float]] = []
for flow in flows:
if flow.is_valuation:
continue
if flow.kind in external:
selected.append((flow.date, -flow.amount))
elif flow.kind not in internal:
raise ValueError(
f"cash-flow kind {flow.kind!r} on {flow.date} is classified "
"neither external nor internal, so it cannot be treated as "
"either. Pass external_kinds=[...] or internal_kinds=[...] to "
"say which side of the portfolio boundary it crosses. Known "
f"external: {', '.join(sorted(external))}. Known internal: "
f"{', '.join(sorted(internal))}."
)
selected.sort(key=lambda item: item[0])
return tuple(selected)
def _annualize(total_return: float, days: int) -> float | None:
"""Annualise a holding-period return, or decline to when the window is short.
Args:
total_return: Return over the whole window, as a decimal fraction.
days: Calendar days spanned by the window.
Returns:
The annualised return, or ``None`` when ``days`` is below
:data:`DAYS_PER_YEAR`. A total wipeout annualises to ``-1.0``, matching
``backtest/metrics.py``'s handling of a non-positive growth factor
rather than raising a negative base to a fractional power.
"""
if days < DAYS_PER_YEAR:
return None
growth = 1.0 + total_return
if growth <= 0.0:
return -1.0
try:
return float(growth ** (DAYS_PER_YEAR / days) - 1.0)
except OverflowError:
return None
# ─── Time-weighted return ───
def _assign_flows_to_periods(
dates: Sequence[date],
flows: Sequence[tuple[date, float]],
flow_timing: str,
) -> list[float]:
"""Bucket external flows into the intervals between valuations.
With :data:`FLOW_TIMING_END` interval ``k`` covers ``(d[k-1], d[k]]``, so a
flow dated on a valuation date belongs to the interval ending there and a
flow dated on the *first* valuation is already inside the opening value.
With :data:`FLOW_TIMING_START` interval ``k`` covers ``[d[k-1], d[k])``, so
a flow dated on a valuation date opens the next interval and a flow on the
*last* valuation falls outside the window.
Args:
dates: Valuation dates in ascending order.
flows: Portfolio-perspective ``(date, amount)`` pairs.
flow_timing: One of :data:`FLOW_TIMING_END` / :data:`FLOW_TIMING_START`.
Returns:
One net flow per interval, so ``len(dates) - 1`` entries.
Raises:
ValueError: If a flow falls outside the valuation window. Dropping it
silently would move the client's money into the manager's return.
"""
first, last = dates[0], dates[-1]
buckets = [0.0] * (len(dates) - 1)
for when, amount in flows:
if when < first or when > last:
raise ValueError(
f"cash flow on {when} lies outside the valuation window "
f"{first}..{last}; extend the valuations or trim the flows "
"rather than dropping the flow"
)
if flow_timing == FLOW_TIMING_END:
if when == first:
raise ValueError(
f"cash flow on {when} coincides with the opening valuation "
f"and flow_timing={FLOW_TIMING_END!r} places it inside the "
"opening value, where it would be counted twice. Use "
f"flow_timing={FLOW_TIMING_START!r}, or start the "
"valuations one period earlier."
)
# First interval whose closing date is at or after the flow.
index = next(k for k in range(1, len(dates)) if dates[k] >= when) - 1
else:
if when == last:
raise ValueError(
f"cash flow on {when} coincides with the closing valuation "
f"and flow_timing={FLOW_TIMING_START!r} places it after the "
"window ends. Use flow_timing="
f"{FLOW_TIMING_END!r}, or extend the valuations."
)
# Last interval whose opening date is at or before the flow.
index = max(k for k in range(len(dates) - 1) if dates[k] <= when)
buckets[index] += amount
return buckets
def time_weighted_return(
valuations: Mapping[date | datetime | str, float]
| Sequence[tuple[date | datetime | str, float]],
flows: CashFlowSeries | Iterable[CashFlow] | None = None,
*,
flow_timing: str = FLOW_TIMING_END,
external_kinds: Iterable[str] | None = None,
internal_kinds: Iterable[str] | None = None,
) -> TimeWeightedReturn:
"""Chain-link the true time-weighted return across a valuation series.
Each interval's return removes that interval's external flow before
dividing, so the product telescopes to the return a single unit of capital
would have earned. Neither the size nor the date of a client contribution
can move it -- that invariance is the entire reason the measure exists, and
it is what distinguishes this from :func:`modified_dietz_return`.
For ``flow_timing=FLOW_TIMING_END`` the interval return is
``(V_k - F_k) / V_{k-1} - 1``: the flow arrives after the market has moved,
so it earns nothing that interval. For ``FLOW_TIMING_START`` it is
``V_k / (V_{k-1} + F_k) - 1``: the flow is invested for the whole interval.
Both are exact given the stated timing; picking the wrong one biases every
interval that carried a flow.
Only boundary-crossing flows are removed; dividends, coupons, and fees are
internal and already sit in the valuations. See the module docstring.
Args:
valuations: Portfolio value on each valuation date, as a mapping or as
``(date, value)`` pairs. At least two are required, and more
valuations make the answer more exact -- this is *true* TWR, not an
approximation, only to the resolution the marks provide.
flows: Client cash flows over the window. ``None`` means none.
flow_timing: Which side of a valuation date a flow dated on it settles.
external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.
internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.
Returns:
A :class:`TimeWeightedReturn` carrying the compounded figure and every
interval that produced it.
Raises:
ValueError: If fewer than two valuations were given, ``flow_timing`` is
not a recognised token, a flow falls outside the window or on a
boundary the timing cannot represent, a flow's kind is
unclassified, or an interval's invested base is not strictly
positive. A non-positive base has no honest percentage: an account
that reached zero did not "return" anything on the way back.
"""
if flow_timing not in _FLOW_TIMINGS:
raise ValueError(
f"flow_timing must be one of {_FLOW_TIMINGS}, got {flow_timing!r}"
)
marks = _normalize_valuations(valuations)
dates = [when for when, _ in marks]
values = [value for _, value in marks]
selected = external_flows(
flows, external_kinds=external_kinds, internal_kinds=internal_kinds
)
buckets = _assign_flows_to_periods(dates, selected, flow_timing)
sub_periods: list[SubPeriodReturn] = []
growth = 1.0
for index, flow_amount in enumerate(buckets):
opening = values[index]
closing = values[index + 1]
if flow_timing == FLOW_TIMING_END:
base = opening
numerator = closing - flow_amount
else:
base = opening + flow_amount
numerator = closing
if not base > 0.0:
raise ValueError(
f"interval {dates[index]}..{dates[index + 1]} has an invested "
f"base of {base!r}; a return is undefined on zero or negative "
"capital, so the window must start after the account was funded"
)
period_return = numerator / base - 1.0
growth *= 1.0 + period_return
sub_periods.append(
SubPeriodReturn(
start=dates[index],
end=dates[index + 1],
start_value=opening,
end_value=closing,
external_flow=flow_amount,
period_return=period_return,
)
)
total_return = growth - 1.0
return TimeWeightedReturn(
total_return=total_return,
sub_periods=tuple(sub_periods),
start_date=dates[0],
end_date=dates[-1],
start_value=values[0],
end_value=values[-1],
net_external_flow=math.fsum(buckets),
flow_timing=flow_timing,
annualized_return=_annualize(total_return, (dates[-1] - dates[0]).days),
)
# ─── Modified Dietz ───
def modified_dietz_return(
valuations: Mapping[date | datetime | str, float]
| Sequence[tuple[date | datetime | str, float]],
flows: CashFlowSeries | Iterable[CashFlow] | None = None,
*,
external_kinds: Iterable[str] | None = None,
internal_kinds: Iterable[str] | None = None,
) -> ModifiedDietzReturn:
"""Compute the day-weighted Modified Dietz return over one period.
``R = (V1 - V0 - F) / (V0 + sum(w_i * F_i))`` with
``w_i = (CD - D_i) / CD``, where ``CD`` is the calendar length of the period
and ``D_i`` the days from its start to flow ``i``. A flow on the opening day
carries weight 1 (invested throughout); one on the closing day carries
weight 0 (invested for none of it).
This is a **money-weighted** measure. It approximates the IRR by assuming a
constant rate of return within the period, and it is sensitive to when the
client moved money -- the opposite property to
:func:`time_weighted_return`. It is offered because it needs no interim
valuations, not because it is a cheaper TWR.
Only the first and last valuations are used; any interim marks are ignored
by construction. Pass them to :func:`time_weighted_return` instead.
Args:
valuations: Portfolio values; the earliest is ``V0`` and the latest is
``V1``. At least two are required.
flows: Client cash flows over the period. ``None`` means none.
external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.
internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.
Returns:
A :class:`ModifiedDietzReturn` carrying the return and every term of
its denominator.
Raises:
ValueError: If fewer than two valuations were given, the opening and
closing dates coincide, a flow lies outside the period, a flow's
kind is unclassified, or the average capital is not strictly
positive (an account funded to zero average capital has no return).
"""
marks = _normalize_valuations(valuations)
start_date, start_value = marks[0]
end_date, end_value = marks[-1]
calendar_days = (end_date - start_date).days
if calendar_days <= 0:
raise ValueError(
f"Modified Dietz needs a period of at least one day, got "
f"{start_date}..{end_date}"
)
selected = external_flows(
flows, external_kinds=external_kinds, internal_kinds=internal_kinds
)
weights: list[tuple[date, float, float]] = []
for when, amount in selected:
if when < start_date or when > end_date:
raise ValueError(
f"cash flow on {when} lies outside the period "
f"{start_date}..{end_date}; trim the flows or widen the period "
"rather than dropping the flow"
)
weight = (calendar_days - (when - start_date).days) / calendar_days
weights.append((when, amount, weight))
net_flow = math.fsum(amount for _, amount, _ in weights)
weighted_flow = math.fsum(amount * weight for _, amount, weight in weights)
average_capital = start_value + weighted_flow
if not average_capital > 0.0:
raise ValueError(
f"average capital is {average_capital!r}; Modified Dietz is "
"undefined on a non-positive invested base"
)
total_return = (end_value - start_value - net_flow) / average_capital
return ModifiedDietzReturn(
total_return=total_return,
start_date=start_date,
end_date=end_date,
start_value=start_value,
end_value=end_value,
net_external_flow=net_flow,
weighted_external_flow=weighted_flow,
average_capital=average_capital,
flow_weights=tuple(weights),
annualized_return=_annualize(total_return, calendar_days),
)
# ─── Money-weighted return ───
def _npv(rate: float, years: Sequence[float], amounts: Sequence[float]) -> float:
"""Net present value of dated amounts at an annual rate.
Args:
rate: Annual discount rate, strictly above -100%.
years: Time from the first flow, in years, aligned with ``amounts``.
amounts: Signed amounts.
Returns:
The discounted sum. A term whose discount factor overflows to beyond
the float range contributes ``0.0``, which is its limit, rather than
raising and aborting the search. A term whose discount factor
*underflows* to ``0.0`` -- or stays subnormal long enough that the
term itself leaves the float range -- diverges to +/-inf in truth;
such terms are represented by a sign-preserving stand-in of magnitude
:data:`_NPV_DIVERGED_MAGNITUDE`, which dominates every finite term
exactly as the limit does while keeping ``fsum`` finite.
"""
base = 1.0 + rate
terms: list[float] = []
diverged: dict[float, float] = {}
for exponent, amount in zip(years, amounts, strict=True):
try:
factor = base**exponent
except OverflowError:
terms.append(0.0)
continue
if factor == 0.0:
# Underflow: the true term is infinite, so only its sign and its
# exponent rank matter. Group by exponent first, so several terms
# that share the largest exponent can still cancel before the sign
# of the limit is decided.
diverged[exponent] = diverged.get(exponent, 0.0) + amount
continue
term = amount / factor
if not math.isfinite(term):
# A subnormal factor (a horizon just short of the underflow point)
# can still push the term past the float range. It diverges in
# exactly the same sense and is grouped the same way; leaving it in
# ``terms`` would hand ``fsum`` an infinity and, with two opposite
# signs, raise ``-inf + inf in fsum``.
diverged[exponent] = diverged.get(exponent, 0.0) + amount
continue
terms.append(term)
for exponent in sorted(diverged, reverse=True):
grouped = diverged[exponent]
if grouped != 0.0:
return math.copysign(_NPV_DIVERGED_MAGNITUDE, grouped)
return math.fsum(terms)
def _solve_irr(
years: Sequence[float], amounts: Sequence[float]
) -> tuple[float, int]:
"""Bisect for the annual rate that zeroes the net present value.
Bisection is used rather than Newton because it cannot diverge and needs no
guess. The bracket starts just above -100% -- where the NPV is dominated by
the latest, largest-exponent amount -- and expands upward until the sign
flips.
Args:
years: Time from the first flow, in years, ascending.
amounts: Signed amounts aligned with ``years``.
Returns:
``(rate, iterations)``.
Raises:
UnsolvableRateError: If the stream never changes sign, or if no rate
below :data:`_IRR_UPPER_LIMIT` brackets a root. Both mean there is
no single rate to report, which is a real property of the stream and
not a solver failure to paper over.
"""
if not any(amount > 0 for amount in amounts) or not any(
amount < 0 for amount in amounts
):
raise UnsolvableRateError(
"an internal rate of return needs at least one inflow and one "
"outflow; this stream is one-directional"
)
low = _IRR_LOWER_BOUND
npv_low = _npv(low, years, amounts)
if npv_low == 0.0:
return low, 0
high = 1.0
npv_high = _npv(high, years, amounts)
iterations = 0
while npv_low * npv_high > 0.0 and high < _IRR_UPPER_LIMIT:
high *= 2.0
npv_high = _npv(high, years, amounts)
iterations += 1
if npv_low * npv_high > 0.0:
raise UnsolvableRateError(
"no internal rate of return between "
f"{_IRR_LOWER_BOUND:.6f} and {_IRR_UPPER_LIMIT:.0f} explains this "
"stream; the net present value never changes sign"
)
while iterations < _IRR_MAX_ITERATIONS and (high - low) > _IRR_TOLERANCE:
middle = 0.5 * (low + high)
npv_middle = _npv(middle, years, amounts)
if npv_middle == 0.0:
return middle, iterations
if npv_low * npv_middle < 0.0:
high = middle
else:
low, npv_low = middle, npv_middle
iterations += 1
return 0.5 * (low + high), iterations
def xirr(
dated_amounts: Sequence[tuple[date | datetime | str, float]],
) -> float:
"""Annual internal rate of return of irregularly dated amounts.
Amounts are holder-perspective, matching ``CashFlow.amount``: money paid out
is negative, money received is positive. Several amounts on one date are
summed. Time is measured in actual days over :data:`DAYS_PER_YEAR`.
A stream with more than one sign change can admit several mathematically
valid rates. This returns whichever root the bisection isolates inside its
initial bracket, and does not enumerate the rest: a stream where that
matters is one whose "the IRR" is not a well-defined quantity, and no
solver choice repairs that. Check the sign pattern before quoting the
number.
Args:
dated_amounts: ``(date, amount)`` pairs. Order does not matter.
Returns:
The annual rate as a decimal fraction, e.g. ``0.087`` for 8.7%.
Raises:
ValueError: If fewer than two amounts were given, a date or amount is
unusable, or every amount falls on one date.
UnsolvableRateError: If the stream is one-directional or no rate
brackets a root.
"""
if len(dated_amounts) < 2:
raise ValueError(
f"an IRR needs at least two dated amounts, got {len(dated_amounts)}"
)
totals: dict[date, float] = {}
for raw_date, raw_amount in dated_amounts:
when = normalize_date(raw_date, field_name="cash-flow date")
try:
amount = float(raw_amount)
except (TypeError, ValueError) as exc:
raise ValueError(
f"amount on {when} must be numeric, got {raw_amount!r}"
) from exc
if not math.isfinite(amount):
raise ValueError(f"amount on {when} must be finite, got {raw_amount!r}")
totals[when] = totals.get(when, 0.0) + amount
ordered = sorted(totals.items())
if len(ordered) < 2:
raise ValueError(
f"every amount falls on {ordered[0][0]}; an IRR needs a time span"
)
origin = ordered[0][0]
years = [(when - origin).days / DAYS_PER_YEAR for when, _ in ordered]
amounts = [amount for _, amount in ordered]
rate, _ = _solve_irr(years, amounts)
return rate
def money_weighted_return(
valuations: Mapping[date | datetime | str, float]
| Sequence[tuple[date | datetime | str, float]],
flows: CashFlowSeries | Iterable[CashFlow] | None = None,
*,
external_kinds: Iterable[str] | None = None,
internal_kinds: Iterable[str] | None = None,
) -> MoneyWeightedReturn:
"""Compute the client's money-weighted return (XIRR) over the window.
The client's cash stream is the opening value paid in, every external flow
as it fell, and the closing value taken back out. Because
``CashFlow.amount`` is already holder-perspective, the flows enter the IRR
unchanged; only the two valuations need signs attached, and they get the
signs a purchase and a sale would carry.
This answers "what did the client's money earn", so unlike
:func:`time_weighted_return` it is *supposed* to move when a large
contribution lands just before a drawdown. Report both, never one as a
proxy for the other.
Interim valuations are ignored: an IRR is determined by cash, and marking
the account midway does not change what the client paid or received.
Args:
valuations: Portfolio values; the earliest opens the stream and the
latest closes it. At least two are required.
flows: Client cash flows over the window. ``None`` means none, in which
case the IRR is just the annualised growth of the opening value.
external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.
internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.
Returns:
A :class:`MoneyWeightedReturn` with both the annualised rate and the
same rate restated over the observed window.
Raises:
ValueError: If fewer than two valuations were given, the window has no
length, a flow lies outside it, or a flow's kind is unclassified.
UnsolvableRateError: If the resulting stream admits no single rate --
for instance a closing value of zero with no distributions, where
every amount points the same way.
"""
marks = _normalize_valuations(valuations)
start_date, start_value = marks[0]
end_date, end_value = marks[-1]
if (end_date - start_date).days <= 0:
raise ValueError(
f"a money-weighted return needs a window of at least one day, got "
f"{start_date}..{end_date}"
)
selected = external_flows(
flows, external_kinds=external_kinds, internal_kinds=internal_kinds
)
for when, _ in selected:
if when < start_date or when > end_date:
raise ValueError(
f"cash flow on {when} lies outside the window "
f"{start_date}..{end_date}; trim the flows or widen the window "
"rather than dropping the flow"
)
# Portfolio-perspective flows are negated back to the client's perspective:
# cash arriving in the portfolio is cash the client paid out.
stream: list[tuple[date, float]] = [(start_date, -start_value)]
stream.extend((when, -amount) for when, amount in selected)
stream.append((end_date, end_value))
totals: dict[date, float] = {}
for when, amount in stream:
totals[when] = totals.get(when, 0.0) + amount
ordered = sorted(totals.items())
origin = ordered[0][0]
years = [(when - origin).days / DAYS_PER_YEAR for when, _ in ordered]
amounts = [amount for _, amount in ordered]
rate, iterations = _solve_irr(years, amounts)
window_years = (end_date - start_date).days / DAYS_PER_YEAR
return MoneyWeightedReturn(
annualized_return=rate,
period_return=(1.0 + rate) ** window_years - 1.0,
start_date=start_date,
end_date=end_date,
start_value=start_value,
end_value=end_value,
net_external_flow=math.fsum(amount for _, amount in selected),
years=window_years,
iterations=iterations,
)