Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns. Use when the user asks about portfolio performance calculation, comparing manager returns, linking sub-period returns, understanding why different return meth

Return Calculations Core Concepts Simple (Holding Period) Return $$R = \frac{V {end} V {begin} + D}{V {begin}}$$ where D = distributions (dividends, interest) received during the period. If V end already reflects reinvested distributions, do not add D again. Mean and Log Return Conventions Arithmetic mean R a = (1/n) sum(R i) — unbiased estimate of the expected single period return (use for forward looking inputs, e.g., mean variance optimization). Always = geometric mean; overstates realized compound growth. Geometric mean R g = [prod(1 + R i)]^(1/n) 1 — the correct measure of realized multi period compound growth. The gap below the arithmetic mean approximates sigma^2 / 2 (volatility drag). Log return r = ln(V end / V begin) — time additive ( r total = r 1 + ... + r n ), so preferred for statistical modeling and multi period aggregation. Convert with R simple = e^r 1 and r = ln(1 + R simple) . Log returns are additive across time but NOT across assets. CAGR (Compound Annual Growth Rate) $$CAGR = \left(\frac{V {end}}{V {begin}}\right)^{1/n} 1$$ where n is measured in years. The annualized geometric growth rate between two valuations with no intermediate cash flows. Time Weighted Return (TWR) Chain links sub period returns calculated between each external cash flow, removing the effect of cash flow timing. TWR measures the manager's investment skill independent of investor deposit/withdrawal decisions, and is the GIPS standard for manager performance. $$1 + R {TWR} = \prod {i=1}^{n}(1 + R i), \qquad R i = \frac{V {end,i}}{V {begin,i} + CF i} 1$$ Exact TWR requires a portfolio valuation on every cash flow date. Modified Dietz Return When valuations on each cash flow date are unavailable, Modified Dietz approximates the period return by day weighting each external cash flow within the period: $$R {MD} = \frac{V {end} V {begin} CF {net}}{V {begin} + \sum i CF i \times w i}, \qquad w i = \frac{CD D i}{CD}$$ where CF net = sum of external cash flows, CD = calendar days in the period, and D i = day of flow i (so w i is the fraction of the period the flow was invested). It is a money weighted approximation; chain linking Modified Dietz sub period returns approximates TWR. Accuracy degrades when flows are large relative to portfolio value or markets are volatile within the period — revalue on large flow dates instead. Money Weighted Return (MWR / IRR) The internal rate of return that sets the NPV of all investor cash flows (contributions, withdrawals, and terminal value) to zero: $$0 = \sum {t=0}^{T} \frac{CF t}{(1 + r)^t}$$ MWR reflects the actual investor experience because it is sensitive to the timing and magnitude of cash flows. Solved numerically (Newton Raphson or bisection). Annualization $$R {annual} = (1 + R {period})^{periods\ per\ year} 1$$ For example, a 2% quarterly return annualizes to (1.02)^4 1 = 8.24% . Sub Period Linking $$(1 + R {total}) = \prod {i=1}^{n}(1 + R i)$$ The foundational identity behind TWR and CAGR. Worked Examples Example 1: Computing CAGR from a 5 Year Investment Given: An investment of $10,000 grows to $16,105.10 over exactly 5 years with no intermediate cash flows. Calculate: The compound annual growth rate (CAGR). Solution: The investment grew at a compound annual rate of 10% per year. Verification: $10,000 (1.10)^5 = $10,000 1.61051 = $16,105.10 Example 2: TWR vs MWR Divergence with Poorly Timed Cash Flow Given: A fund has the following history: Start of Year 1: Portfolio value = $100,000 End of Year 1: Portfolio value = $120,000 (return = +20%) Start of Year 2: Investor deposits $100,000, bringing portfolio to $220,000 End of Year 2: Portfolio value = $198,000 (return = 10%) Calculate: Both TWR and MWR, and explain the divergence. Solution: Time Weighted Return (TWR): Money Weighted Return (MWR / IRR): Cash flows from the investor's perspective: t=0: $100,000 (initial investment) t=1: $100,000 (additional deposit) t=2: +$198,000 (terminal value) Solve: 100,000 + ( 100,000)/(1+r) + 198,000/(1+r)^2 = 0 This is quadratic in x = 1/(1+r) ; the positive root gives r = 0.66815% (verifiable with the bundled script or any IRR solver). NPV check at r = 0.0066815: The MWR is approximately 0.67% annualized . Interpretation: The TWR of +3.92% annualized reflects the manager's skill: the fund gained 20% then lost 10%, netting +8% over two years. The MWR of approximately 0.67% reflects the investor's experience: more money was at risk during the losing year (Year 2) because of the large deposit, so the investor's dollar weighted outcome was slightly negative. This divergence highlights why TWR is preferred for evaluating manager performance, while MWR better describes the specific investor's realized result. Common Pitfalls Confusing arithmetic and geometric means: the arithmetic mean is always greater than or equal to the geometric mean (AM GM inequality). Using arithmetic mean to project compounded growth overstates terminal wealth. Using arithmetic mean for multi period compounding: always use geometric mean or CAGR when describing compound growth over multiple periods. Annualizing returns from very short periods: annualizing a 2% weekly return yields (1.02)^52 1 = 180% , which amplifies noise and is misleading. Annualization is most meaningful for periods of at least one year. Ignoring cash flow timing when TWR is appropriate: MWR conflates manager skill with investor timing decisions. Use TWR for manager evaluation. Double counting dividends: if the ending value V end already includes reinvested dividends, do not add D separately in the holding period return formula. Trusting Modified Dietz with large intra period flows: when a single flow exceeds roughly 10% of portfolio value, revalue the portfolio on the flow date rather than day weighting. Running the Script scripts/return calculations.py provides a Returns class with static methods for every formula above (holding period return, TWR, MWR/IRR via Newton's method, Modified Dietz is straightforward to compose from these, CAGR, annualization, linking, arithmetic/geometric means, log return conversions). Run: uv run scripts/return calculations.py (PEP 723 inline metadata resolves numpy automatically), or python3 scripts/return calculations.py with numpy installed. Bare invocation (or verify ) prints a demo of all functions and asserts the worked example values above (Example 1 CAGR = 10%, Example 2 TWR = +8.0% cumulative / 3.92% annualized, MWR = 0.6682%), exiting nonzero on any mismatch. help lists the available functions and import usage. For programmatic use, import rather than run: from return calculations import Returns . Cross References time value of money (core plugin): NPV, IRR, and discounting concepts overlap with MWR calculations; owns project/loan IRR statistics fundamentals (core plugin): Arithmetic and geometric means, return distribution analysis

return-calculations