Portfolio optimization, risk analytics, and strategy certification in Python
CPZAI operating system · Documentation · Issues
cpz-quant is the open-source quantitative research engine from CPZ Lab: institutional-grade portfolio optimization, covariance estimation, risk measures, walk-forward and combinatorial purged cross-validation, anti-overfitting strategy certification (Probability of Backtest Overfitting, Deflated Sharpe Ratio), and vectorised technical indicators. Pure functions on NumPy arrays and plain dictionaries: data in, results out, no I/O, no hidden state, fully typed.
It is the research core of the CPZAI systematic trading operating system, and it is fully standalone: pip install cpz-quant and you have the complete library with an Apache-2.0 license.
pip install cpz-quantimport polars as pl
from cpz_quant.portfolio import (
hierarchical_risk_parity, black_litterman, mean_cvar,
ledoit_wolf, WalkForward, cross_validate,
)
# Daily returns per asset. Every function accepts a Polars DataFrame,
# a pandas DataFrame, or a plain {asset: [returns]} dict — date/string
# columns are treated as labels and excluded automatically.
returns = pl.DataFrame({
"AAPL": [0.012, -0.004, 0.007],
"MSFT": [0.008, 0.002, -0.001],
"TLT": [-0.002, 0.005, 0.001],
})
# Hierarchical Risk Parity: clustering-based allocation, no matrix inversion
hrp = hierarchical_risk_parity(returns)
print(hrp.weights, hrp.sharpe_ratio)
# Mean-CVaR: optimize tail risk instead of variance
cvar = mean_cvar(returns, confidence=0.95)
# Walk-forward cross-validation of any allocator
cv = cross_validate(
lambda train: hierarchical_risk_parity(train).weights,
returns,
cv=WalkForward(n_splits=4, test_size=63),
)
print(cv.oos_sharpe)Certify a strategy before you trust the backtest:
import numpy as np
from cpz_quant.certification import (
probability_of_backtest_overfitting, # CSCV / PBO
compute_risk_analytics, # Sortino, CVaR, tail ratio, MinTRL...
)
trials = np.column_stack([...]) # (T, N): returns of N tested configs
pbo = probability_of_backtest_overfitting(trials)
analytics = compute_risk_analytics(equity_curve)
print(pbo.pbo, pbo.performance_degradation, analytics.sortino)| Family | Methods |
|---|---|
| Classic convex | mean-variance (Markowitz), minimum variance, maximum Sharpe ratio, maximum diversification, minimum tracking error, turnover-penalized |
| Risk-based | risk parity / risk budgeting, equal weight, inverse volatility via mean-risk |
| Clustering | Hierarchical Risk Parity (HRP), Hierarchical Equal Risk Contribution (HERC), Nested Clustered Optimization (NCO), Schur complementary allocation |
| Views and priors | Black-Litterman, entropy pooling (fully flexible views) |
| Tail-risk | mean-CVaR, 17-measure mean-risk optimizer (CVaR, EVaR, CDaR, EDaR, drawdown-at-risk, Ulcer index, Gini mean difference, ...) |
| Robust | robust mean-variance (scipy native), box and ellipsoidal uncertainty sets on expected returns (convex backend) |
| Cardinality | exact mixed-integer cardinality-constrained portfolios with semi-continuous position bounds (convex backend) |
| Alpha-risk-cost | Grinold-Kahn style alpha-risk-cost optimizer with transfer coefficient |
| Quantum / QUBO | QUBO portfolio selection, quantum-inspired HRP, simulated annealing and D-Wave backends |
Sample, exponentially weighted (EWMA), Ledoit-Wolf shrinkage, Oracle Approximating Shrinkage, Marchenko-Pastur denoising, detoning, Gerber statistic, statistical (PCA) and fundamental factor models, factor risk decomposition.
WalkForward and CombinatorialPurgedCV splitters, cross_validate, and grid_search, built for overlapping financial samples where naive K-fold leaks. Optional scikit-learn estimator wrappers (MeanRiskEstimator, HRPEstimator, HERCEstimator, NCOEstimator) plug into sklearn Pipeline and GridSearchCV (pip install cpz-quant[sklearn]).
Most backtests are overfit. cpz-quant ships the math to prove whether yours is:
- Probability of Backtest Overfitting (PBO) via combinatorially symmetric cross-validation (CSCV)
- Deflated Sharpe Ratio and Probabilistic Sharpe Ratio gates that account for multiple testing
- Regime-conditional performance breakdowns
- A graded, reproducible certification score (
certify) used by the CPZ Certification Standard
pip install cpz-quant[cvx] adds exact cvxpy programs: hard gross-exposure and turnover constraints, L2 regularization, CVaR linear programming, robust uncertainty sets, and mixed-integer cardinality constraints ([cvx-mip] for the open-source SCIP solver). If a required solver is missing the library raises with install instructions; it never silently substitutes an approximation.
Vectorised momentum, trend, volatility, volume, and statistical indicators on NumPy/Polars, with optional Rust acceleration and graceful pure-Python fallback.
Portfolio selection as a QUBO problem with pluggable solvers: exact brute force, simulated annealing (pip install cpz-quant[quantum], dwave-neal), and quantum-inspired HRP cluster ordering. build_portfolio_qubo exposes the raw QUBO matrix for any annealer. Real quantum hardware (IonQ, Rigetti, IQM via Amazon Braket) runs through the CPZAI operating system with cost gating; the local solvers are fully standalone.
The rust/ crate (cpz_risk_rs, PyO3 + rayon) ships in this repo and accelerates the hot paths: certification analytics, Monte Carlo VaR, Ledoit-Wolf and EWMA covariance, Marchenko-Pastur denoising, HRP weights, and the indicator kernels. Build it with pip install maturin && cd rust && maturin develop --release. Everything runs identically without it — pure NumPy fallbacks are parity-tested, and has_rust() tells you which path is active. No silent behavior differences, only speed.
pip install cpz-quant[viz] adds four Plotly figures in cpz_quant.viz: plot_weights, plot_frontier (efficient frontier with max-Sharpe and min-variance marked), plot_drawdown (equity + underwater panel), and plot_corr_clusters (correlation matrix ordered by HRP clustering). Plotly is never imported unless you use them.
Almgren-Chriss market impact, linear and square-root impact, spread costs, turnover analysis, alpha-decay capacity estimation, Brinson-Fachler attribution, factor and risk attribution, alpha-beta decomposition.
- Pure functions. Every public API is data in, results out. No database, no network, no global state. Trivially testable and reproducible.
- DataFrame-native, dependency-lean. Polars and pandas DataFrames work everywhere returns go; neither library is imported unless you pass one, and pandas is never a dependency.
- Fail loudly. No silent fallbacks, no fabricated defaults. Missing solver, degenerate covariance, or invalid input raises with an actionable message.
- Typed end to end.
py.typed, mypy-checked in CI, pydantic result models where structure matters. - Certification is not optional. The same anti-overfitting gates that certify strategies on the CPZAI operating system are open source here, so any grade can be independently reproduced.
How do I do portfolio optimization in Python with cpz-quant?
pip install cpz-quant, then call any allocator in cpz_quant.portfolio with your returns as a Polars DataFrame, pandas DataFrame, or dict of series (see quickstart above). All 20+ methods share the same input shape and return an OptResult with weights, expected return, volatility, and Sharpe ratio.
Does cpz-quant work with Polars and pandas? Yes, natively: every allocator, covariance estimator, and pre-selection transformer accepts a Polars or pandas DataFrame directly (numeric columns become assets; date/string columns are excluded as labels). Polars is a core dependency; pandas is supported but never required.
Does cpz-quant support Hierarchical Risk Parity (HRP) and HERC?
Yes: hierarchical_risk_parity, hierarchical_equal_risk_contribution, plus NCO and Schur complementary allocation for nested and cluster-aware variants.
Can I detect backtest overfitting?
Yes: cpz_quant.certification.probability_of_backtest_overfitting implements CSCV/PBO, and certify grades a strategy with Deflated Sharpe Ratio gates.
Is it compatible with scikit-learn?
Yes, optionally: pip install cpz-quant[sklearn] provides estimator wrappers that work inside sklearn pipelines and grid search, while the core library stays dependency-light.
How does cpz-quant relate to the cpz-ai SDK? cpz-quant is the open-source research core (Apache-2.0). The proprietary cpz-ai SDK builds on it and adds live multi-broker execution, FIX connectivity, market data access, and the CPZAI operating system integration. Research is open; execution is a product.
Is AI used in developing cpz-quant?
Yes, and it is disclosed: parts of the library are developed with Simons, the AI research partner of the CPZAI operating system, under CPZ Lab's review and maintainership. AI-authored commits carry the git identity Simons <simons@cpz-lab.com> so provenance is auditable, in line with the transparency expectations of the EU AI Act, the NIST AI Risk Management Framework, and ISO/IEC 42001. See CONTRIBUTING.md.
Is this investment advice? No. cpz-quant is a software library for quantitative research. Nothing in it constitutes investment advice.
Full documentation: https://cpz-lab.github.io/cpz-quant/
Contributions are welcome: see CONTRIBUTING.md. The library is tested on Python 3.9 to 3.12 with lint, type-check, and branch-coverage gates enforced in CI.
If you use cpz-quant in academic work, please cite it (see CITATION.cff):
CPZ Lab (2026). cpz-quant: quantitative portfolio optimization, risk analytics,
and strategy certification in Python. https://github.com/CPZ-Lab/cpz-quant
Apache License 2.0. Copyright (c) 2024-2026 CPZ Capital Ltd.