Add ERCOpt: Equal Risk Contribution (Risk Parity) portfolio optimizer

[hass-nation]

Summary

Adds ERCOpt to hierarchical_portfolio.py, implementing the Equal Risk Contribution (ERC) portfolio (Maillard, Roncalli & Teiletche 2010), also known as the Risk Parity portfolio.

Motivation

ERC fills a gap between the existing HRPOpt (hierarchical, cluster-based) and mean-variance optimizers: it is a simple, robust, model-free portfolio where every asset contributes the same fraction of total portfolio variance, requiring only a covariance estimate and no expected returns.

ERC has been shown to be more robust out-of-sample than max-Sharpe or min-variance portfolios (Maillard et al. 2010) and is widely used in practice.

Definition

Find w ≥ 0, sum(w) = 1 such that:

w_i · (Σw)_i / (w'Σw) = 1/n   for all i

When Σ is diagonal this reduces to inverse-volatility weighting: w_i ∝ 1/σ_i.

Solver: Spinu (2013) CCD

At each step, the exact one-dimensional sub-problem is solved for coordinate i:

Σᵢᵢ·wᵢ² + (Σw − Σᵢᵢ·wᵢ)·wᵢ − 1/n = 0   →   positive root

Crucially, weights are NOT normalised between coordinate updates — normalisation happens once after the full pass. This unconstrained formulation converges reliably for any PD covariance matrix, including those with negative off-diagonal entries (where Roncalli's multiplicative update fails).

API

Matches HRPOpt exactly:

from pypfopt import ERCOpt

# From returns
erc = ERCOpt(returns=returns_df)
weights = erc.optimize()
erc.portfolio_performance(verbose=True)

# From a pre-computed covariance matrix
erc = ERCOpt(cov_matrix=cov_df)
weights = erc.optimize()

Files changed

• pypfopt/hierarchical_portfolio.py — _erc_weights_ccd helper + ERCOpt class
• pypfopt/__init__.py — exports ERCOpt
• tests/test_erc.py — 29 tests

Test plan

• 29/29 new tests pass — CCD on diagonal covariance (analytic check), negative-correlation covariance, identical assets (equal weights), two-asset analytic solution, tickers preserved, clean_weights, portfolio_performance from returns and cov-only, error before optimize
• 294/294 existing tests pass (0 regressions; 2 test_plotting.py failures are pre-existing headless-display failures)
• sum(weights) = 1 and all weights ≥ 0 verified
• ERC condition RC_i = 1/n * (w'Σw) verified to rtol=1e-6

References

• Maillard, S., Roncalli, T., & Teiletche, J. (2010). The Properties of Equally Weighted Risk Contribution Portfolios. Journal of Portfolio Management, 36(4), 60-70.
• Spinu, F. (2013). An Algorithm for Computing Risk Parity Weights. SSRN working paper.

🤖 Generated with Claude Code