做什么（One-liner）

给 NxN 协方差矩阵求解等风险贡献权重（每个资产贡献 1/N 风险）。Maillard (2010) 固定点迭代，500 iter cap，1e-10 tolerance。Bridgewater All Weather 核心构件。

怎么用

Canvas 拖 risk_parity_v1，填 cov_matrix（必填，NxN PSD 矩阵）+ 可选 target_risk。输出 weights + portfolio_vol + risk_contributions_pct。

典型用法：

# 4-ETF cross-asset basket
cov = numpy_cov(returns_SPY_TLT_GLD_DBC)
result = risk_parity(cov.tolist())
# result.weights sum to 1, each asset contributes ~25% portfolio risk

核心公式

起点: w = [1/N, 1/N, ..., 1/N]

迭代 (≤500 次，1e-10 tolerance):
  σ_p = sqrt(wᵀ Σ w)
  rc_i = w_i × (Σw)_i / σ_p       # 每个资产的风险贡献
  target = σ_p / N
  w_new_i = w_i × (target / rc_i)
  w_new = w_new / sum(w_new)       # 归一化
  终止 if max|Δw| < 1e-10

# 目标: 所有 rc_i = σ_p / N（每个资产贡献 1/N 风险）

可选 target_risk 参数 → 返回 scaled_weights = w × (target / σ_p)（杠杆缩放）。

假设与适用场景

假设：协方差 PSD + long-only 不 enforce + 500 iter 足够 well-conditioned 场景 + equal-weight start。

适用：股/债/商品/黄金多元化组合（正相关 / 低正相关场景）；长期战略配置。

不适用：负相关对冲组合（会产生 long-short 权重）、严格 long-only（需 QP 变体）、singular 协方差、2 资产零相关退化。

已知局限

1. 2 资产零相关 2-cycle —— 振荡于 [0.5, 0.5] ↔ [0.69, 0.31]，收敛失败但 500 iter cap 决定终点。golden 锁定当前行为；long-only QP 变体是 future work。
2. 负权重可能 —— 简单迭代不 enforce w ≥ 0。负相关主导输入会 long-short；实操应用需 caller 检测。
3. 收敛保证弱 —— 对病态 Σ（条件数 > 1e6）可能 500 iter 仍不收敛；无 diagnostics 输出。
4. rounding: weights / vol round(6), RC% round(2)。
5. 无 PSD 检查 —— 非 PSD 输入可能产生 complex σ_p。

参考文献

Maillard, Roncalli, Teiletche (2010) ERC 原始 + Qian (2006) risk contribution 可加性 + Bai, Scheinberg, Tütüncü (2016) QP 变体 + Roncalli (2013) 教科书。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier2/risk_parity/，1e-12 tolerance byte-equality on 4-ETF positive-correlation basket（12 iter 内 clean converge）。7 tests：

• matches_reference — numpy 独立 reimplementation 对比（全部 field byte-equal）
• determinism — 5 reruns byte-identical
• equal_risk_contribution_achieved — 语义锁定：每个 RC ≈ 100/N ± 0.05pp
• weights_sum_to_one — normalization contract
• rejects_single_asset — N<2 → error payload
• target_risk_scaling — 可选 target_risk 产生 scaled_weights = w × (target/σ_p)
• known_2_cycle_documented — 锁定 2-asset 零相关退化场景的 oscillation 行为（反向归纳：未来若换 damped iteration 会触发此 test）

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 2 batch 2, iterative optimization pilot）