投资组合收益计算与比较：需要计算 TWR、MWR/IRR…

当要计算或比较投资组合业绩、区分管理人收益与投资者实际收益、处理现金流导致的收益差异时，按现金流时点选择 TWR、MWR、CAGR、Modified Dietz 等正确公式。

适用场景

解决思路

1. 计算简单持有期收益：R = (V_end - V_begin + D) / V_begin；D 是期间收到的分红/利息等分配。若 V_end 已反映再投资分配，不要再加 D。
2. 计算算术平均收益：R_a = (1/n) * sum(R_i)。它用于向前看的单期期望收益输入（如均值-方差优化），总是不小于几何平均，并会高估已实现复合增长。
3. 计算几何平均收益：R_g = [prod(1 + R_i)]^(1/n) - 1。它是已实现多期复合增长的正确度量；其低于算术平均的差距约等于 sigma^2 / 2，即波动拖累。
4. 计算对数收益：r = ln(V_end / V_begin)。它在时间上可加，优先用于统计建模和多期聚合。
5. 在对数收益与简单收益之间转换：R_simple = e^r - 1，r = ln(1 + R_simple)。注意对数收益在时间上可加，但跨资产不可加。
6. 计算 CAGR：CAGR = (V_end / V_begin)^(1/n) - 1，n 以年为单位。它用于两个估值之间无中间现金流时的年化几何增长率。
7. 计算时间加权收益 TWR：按每个外部现金流划分区间并链式连接子期收益，以剔除现金流时点影响；1 + R_TWR = prod_{i=1}^{n}(1 + R_i)，R_i = V_end,i / (V_begin,i + CF_i) - 1。TWR 衡量管理人投资技能，独立于投资者存入/取出决策，是 GIPS 的管理人业绩标准；精确 TWR 要求在每个现金流日期都有组合估值。
8. 使用 Modified Dietz 近似：当无法在每个现金流日期估值时，R_MD = (V_end - V_begin - CF_net) / (V_begin + sum_i CF_i * w_i)，w_i = (CD - D_i) / CD；CF_net 是外部现金流之和，CD 是期间日历天数，D_i 是第 i 笔现金流的日期，w_i 是现金流在期间内被投资的占比。
9. 链式连接 Modified Dietz 子期收益以近似 TWR；它是资金加权近似，当现金流相对组合价值很大或期间市场波动大时准确性下降，应在大的现金流日期重新估值。
10. 计算资金加权收益 MWR / IRR：令所有投资者现金流（投入、取出、期末价值）的 NPV 为零，0 = sum_{t=0}^{T} CF_t / (1 + r)^t。MWR 对现金流时点和规模敏感，反映投资者实际体验。
11. 数值求解 MWR/IRR：使用 Newton-Raphson 或二分法求解使 NPV = 0 的 r。
12. 年化收益率：R_annual = (1 + R_period)^(periods_per_year) - 1；例如 2% 季度收益年化为 (1.02)^4 - 1 = 8.24%。
13. 链接子期收益：1 + R_total = prod_{i=1}^{n}(1 + R_i)。这是 TWR 和 CAGR 背后的基础恒等式。
14. 按示例 1 计算 5 年投资 CAGR：给定 V_begin=10,000、V_end=16,105.10、n=5，执行 CAGR = (16,105.10 / 10,000)^(1/5) - 1 = 10%。
15. 用 V_end = V_begin * (1 + CAGR)^n 验证 CAGR：10,000 * (1.10)^5 = 16,105.10。
16. 按示例 2 计算 TWR：先算各子期收益，R_1 = (120,000 - 100,000)/100,000 = +20%，R_2 = (198,000 - 220,000)/220,000 = -10%；累计 TWR = (1 + 0.20) * (1 - 0.10) - 1 = +8.0%；年化 TWR = (1.08)^(1/2) - 1 = 3.92%。
17. 按示例 2 计算 MWR/IRR：列出投资者现金流 t=0: -100,000，t=1: -100,000，t=2: +198,000；解 -100,000 + (-100,000)/(1 + r) + 198,000/(1 + r)^2 = 0；令 x = 1/(1 + r)，取二次方程正根得 r = -0.66815%。
18. 对 MWR 做 NPV 校验：在 r = -0.0066815 时检查 -100,000 + (-100,000)/0.9933185 + 198,000/0.9933185^2 = 0.00（精确）。
19. 解释 TWR 与 MWR 的分歧：TWR +3.92% 年化反映管理人技能；MWR 约 -0.67% 年化反映投资者体验，因为亏损年份有更多资金暴露。用 TWR 评价管理人，用 MWR 描述特定投资者的已实现结果。
20. 运行脚本：uv run scripts/return_calculations.py（PEP 723 inline metadata 自动解析 numpy），或在已安装 numpy 时运行 python3 scripts/return_calculations.py。
21. 用裸调用或 --verify 运行脚本：会打印所有函数演示，并断言上述示例值（示例 1 CAGR = 10%、示例 2 TWR 累计 +8.0% / 年化 3.92%、MWR = -0.6682%）；任何不匹配都会以非零状态退出。
22. 查看可用函数：运行 --help 会列出可用函数和导入用法。
23. 以编程方式使用脚本：不要运行脚本，而是导入，例如 from return_calculations import Returns。
24. 使用 Returns 类：scripts/return_calculations.py 提供 Returns 类，包含上述所有公式的静态方法：持有期收益、TWR、MWR/IRR（Newton 法）、Modified Dietz（可由这些组合）、CAGR、年化、链接、算术/几何平均、对数收益转换。
25. 处理常见陷阱：不要混淆算术和几何平均，算术平均总是不小于几何平均（AM-GM），用算术平均投影复合增长会高估期末财富。
26. 处理常见陷阱：描述多期复合增长时始终使用几何平均或 CAGR，不要用算术平均做多期复利。
27. 处理常见陷阱：不要对极短期间年化；例如 2% 周收益年化为 (1.02)^52 - 1 = 180%，会放大噪声且误导；年化至少对一年以上期间最有意义。
28. 处理常见陷阱：TWR 合适时不要忽略现金流时点；MWR 会把管理人技能和投资者择时决策混在一起，评价管理人应使用 TWR。
29. 处理常见陷阱：不要重复计算分红；如果 V_end 已包含再投资分红，持有期收益公式中不要另外加 D。
30. 处理常见陷阱：单笔现金流超过组合价值约 10% 时不要只信任 Modified Dietz 日加权；应在现金流日期重新估值。
31. 跨技能路由：遇到项目/贷款 IRR、NPV 和通用「求利率」问题，改用 time-value-of-money。
32. 跨技能参考：算术/几何平均、收益分布分析可参考 statistics-fundamentals。

适用边界 · 注意事项

• 项目或贷款 IRR、NPV、通用「求利率」问题不适用本技能，应使用 time-value-of-money。
• 期间短于一整年时不要年化收益，会放大噪声且误导。
• 当单笔现金流超过组合价值约 10% 时不要只依赖 Modified Dietz 日加权；应在现金流日期重新估值。