# invest.cagr

The compound annual growth rate: the constant yearly rate that turns the start
value into the end value over the holding period,

    CAGR = (end / start)^(1 / years) − 1

returned in basis points (718 = 7.18% a year).

## Why it is shaped this way

- **Years are a fraction**, `yearsNumerator / yearsDenominator`, so 18 months
  is `3, 2` and 30 days is `30, 365`. A float number of years would put the
  platform's `pow` back into the answer, and it differs by an ulp across
  languages.
- **Short periods are annualised by compounding**, not scaled: 5% in six
  months is 10.25% a year, not 10%. Whether a return under a year should be
  annualised at all is the caller's decision (GIPS says not to present one);
  this function does what it is asked.
- **Exact arithmetic.** end / start is taken to 18 decimal places (floored),
  and raised to 1 / years with `math.fractional-power`'s 18-place fixed point,
  which floors every step in the same order in every language. The result is
  then rounded to a whole basis point, **half away from zero**: +0.5 bp is 1,
  −0.5 bp is −1. The fixed-point error is around 10^-16, far below the half
  basis point, and a power that is exact in 18 places (1.21^(1/2) = 1.1) comes
  out exact.

## Edge cases

- An end value of zero is a total loss, −10000 (−100%), for any period.
- Equal values are 0.
- The start must be greater than zero, the end must not be negative, and both
  must be in the same currency.
- `yearsNumerator` and `yearsDenominator` are whole numbers from 1 to 100000.
- A growth so large the rate cannot be held (e.g. a thousandfold rise in a
  week) is an error rather than an overflow.