invest.time-weighted-return Unreviewed

def time_weighted_return(points: Sequence[ValuationPoint]) -> TwrResult

@dataclass(frozen=True)
class ValuationPoint:
    """The portfolio's value on a date, just before that date's external cash flow."""

    date: str
    #: the market value before the flow; 0 or more
    value: Money
    #: money added (positive) or withdrawn (negative) straight after the valuation
    flow: Money

@dataclass(frozen=True)
class TwrResult:
    """The linked return, each sub-period's return, and the annualised figure when the period is a year or more."""

    #: the cumulative time-weighted return: 1550 = 15.5%
    basis_points: int
    #: one per sub-period between consecutive points
    sub_period_basis_points: List[int]
    #: first date to last date
    days: int
    #: (1 + R)^(365 / days) − 1; null under 365 days
    annualised_basis_points: Optional[int]

from fune.invest.time_weighted_return import time_weighted_return  # invest.time-weighted-return@^1

from typing import List, Optional, Sequence

from .dates_add_days import epoch_day_from_iso  ← from dates.add-days ^1.0.0 · built alongside by fune
from .invest_time_weighted_return_types import TwrResult, ValuationPoint
from .math_fractional_power import FIXED_SCALE, fractional_power_fixed  ← from math.fractional-power ^1.0.0 · built alongside by fune

_MAX_SPAN_DAYS = 36500


def _round_half_away(n: int, d: int) -> int:
    """n / d rounded half away from zero; d > 0."""
    magnitude = (abs(n) * 2 + d) // (2 * d)
    return -magnitude if n < 0 else magnitude


def _whole(minor: int) -> int:
    if isinstance(minor, bool) or not isinstance(minor, int):
        raise ValueError("amounts must be whole minor units, received %r" % (minor,))
    return minor


def time_weighted_return(points: Sequence[ValuationPoint]) -> TwrResult:
    """True time-weighted return: each sub-period's growth, value_i over the
    previous value plus the previous flow, linked geometrically as an exact
    fraction and rounded once to basis points, half away from zero."""
    if len(points) < 2:
        raise ValueError("at least two valuation points are needed")
    currency = points[0].value.currency
    days: List[int] = []
    for point in points:
        for amount in (point.value, point.flow):
            if amount.currency != currency:
                raise ValueError("currency mismatch: %s and %s" % (currency, amount.currency))
        if _whole(point.value.minor) < 0:
            raise ValueError("valuations must not be negative, received %d on %s" % (point.value.minor, point.date))
        _whole(point.flow.minor)
        day = epoch_day_from_iso(point.date)
        if days and day <= days[-1]:
            raise ValueError("dates must be strictly increasing, one point per date")
        days.append(day)
    span = days[-1] - days[0]
    if span > _MAX_SPAN_DAYS:
        raise ValueError("points must fall within %d days" % _MAX_SPAN_DAYS)

    numerator, denominator = 1, 1
    sub_period_basis_points: List[int] = []
    for i in range(1, len(points)):
        invested = points[i - 1].value.minor + points[i - 1].flow.minor
        if invested <= 0:
            raise ValueError("nothing is invested at the start of the sub-period from %s" % points[i - 1].date)
        value = points[i].value.minor
        sub_period_basis_points.append(_round_half_away((value - invested) * 10000, invested))
        numerator *= value
        denominator *= invested

    annualised: Optional[int] = None
    if span >= 365:
        if numerator == 0:
            annualised = -10000
        else:
            growth = fractional_power_fixed(numerator * FIXED_SCALE // denominator, 365, span)
            annualised = _round_half_away((growth - FIXED_SCALE) * 10000, FIXED_SCALE)
    return TwrResult(
        basis_points=_round_half_away((numerator - denominator) * 10000, denominator),
        sub_period_basis_points=sub_period_basis_points,
        days=span,
        annualised_basis_points=annualised,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 4 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add invest.time-weighted-return

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./invest.time-weighted-return-1.0.1-python.fune, or fetch it from a terminal with fune pull invest.time-weighted-return@1.0.1:python.

The whole function, every language, is one file too: invest.time-weighted-return-1.0.1.fune, 32,416 bytes, sha256 7d64059a234d6464f3e546ed8903c2babb7b2a1f0c1bd3df47b357d88585a42a. It installs into a project of any language.

# fune: before invest.time-weighted-return

# fune: after invest.time-weighted-return

# fune: replace dates.add-days in invest.time-weighted-return
# fune: replace math.big-integer in invest.time-weighted-return
# fune: replace math.fractional-power in invest.time-weighted-return
# fune: replace money.amount in invest.time-weighted-return

# fune: step invest.time-weighted-return after <n|label>

More from the author

The portfolio is valued on the date of every external cash flow, **just before** the flow. Between two consecutive points the sub-period return is

r_i = value_i / (value_(i−1) + flow_(i−1)) − 1

and the sub-periods are linked geometrically: 1 + R = Π (1 + r_i). This is the "true" TWR; it needs a valuation at every flow, which is what the points are. (Approximations such as Modified Dietz, which avoid the valuations, are not this capability.)

The product is formed exactly, as a fraction of big integers, and rounded once: every figure is in basis points, **half away from zero** (+0.5 bp is 1, −0.5 bp is −1). A naive "gain over opening value" gets deposits wrong: £100,000 that grows 10%, receives £50,000 and then grows 5% ends at £168,000, a TWR of 15.5%, not 18%.

## Annualised

When the first and last dates are 365 days or more apart, `annualisedBasisPoints` is (1 + R)^(365 / days) − 1, taken in `math.fractional-power`'s 18-place fixed point (actual days over 365, as XIRR does, so a leap year counts as 366/365). Under 365 days it is null: GIPS says returns for periods of less than one year must not be annualised. A total loss annualises to −100%.

## Edge cases

- The first point's value may be zero when its flow opens the account. - The last point's flow does not affect the return: nothing is measured after it. It is still checked for currency. - Errors: fewer than two points; dates not strictly increasing; a negative valuation; a sub-period that starts with nothing invested (value plus flow zero or less); mixed currencies; fractional minor units; more than 36,500 days from first to last.

## Before you rely on this

**Not professional advice.** This capability calculates investment figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a tax adviser review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified tax adviser has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files