# invest.time-weighted-return

The time-weighted return (TWR) of a portfolio: the growth of one unit invested
at the start, with the effect of money the client adds or withdraws taken
out. It measures the manager, not the timing of the client's deposits, and is
the return the CFA Institute's Global Investment Performance Standards
require for most portfolios (GIPS 2020;
https://www.gipsstandards.org/wp-content/uploads/2021/02/2020_gips_standards_asset_owners.pdf,
read 2026-09-23).

## The calculation

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.