cpz-quant

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-quant

60-second quickstart

import numpy as np
import polars as pl
from cpz_quant.portfolio import (
    hierarchical_risk_parity, mean_cvar, 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.
# Synthetic demonstration inputs; replace with aligned market returns.
# 756 observations leave enough training data for four 63-day test folds.
rng = np.random.default_rng(7)
returns = pl.DataFrame({
    "asset_a": rng.normal(0.0003, 0.012, 756),
    "asset_b": rng.normal(0.0002, 0.010, 756),
    "asset_c": rng.normal(0.0001, 0.006, 756),
})

# 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.to_dict(as_series=False),
    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)

What is in the box

Portfolio optimization (20+ allocators)

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

Covariance estimation and factor models

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.

Model selection that respects time

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]).

Strategy certification (the referee layer)

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

Convex optimization backend

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.

Technical indicators

Vectorised momentum, trend, volatility, volume, and statistical indicators on NumPy/Polars, with optional Rust acceleration and graceful pure-Python fallback.

Quantum and quantum-inspired optimization

Portfolio selection as a QUBO problem with pluggable solvers: exact brute force, classical simulated annealing (pip install cpz-quant[quantum]), and quantum-inspired HRP cluster ordering. build_portfolio_qubo exposes the matrix using x'Qx. Experimental BraketSolver(device="local", seed=7) runs genuine gate-model QAOA simulation on CPU with cpz-quant[quantum-braket]. Paid AWS simulators and physical QPUs are disabled pending budget enforcement and cost reconciliation. No quantum advantage is claimed. Private CPZAI routing and hedge formulations are not distributed in this package.

Rust-accelerated core

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.

Visualization

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.

Transaction costs, capacity, and attribution

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.

Design principles

1. Pure functions. Every public API is data in, results out. No database, no network, no global state. Trivially testable and reproducible.
2. 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.
3. Fail loudly. No silent fallbacks, no fabricated defaults. Missing solver, degenerate covariance, or invalid input raises with an actionable message.
4. Typed end to end. py.typed, mypy-checked in CI, pydantic result models where structure matters.
5. 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.

FAQ

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 this investment advice? No. cpz-quant is a software library for quantitative research. Nothing in it constitutes investment advice.

Documentation

Full documentation: https://cpz-lab.github.io/cpz-quant/

• Quickstart
• Portfolio optimization guide
• Certification guide
• Cross-validation guide
• Examples

Contributing

Contributions are welcome: see CONTRIBUTING.md. The CI configuration targets Python 3.9 to 3.12 with lint, type-check, and branch-coverage gates. Release verification must include successful test results; a configured workflow alone is not evidence that it ran.

Citation

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

License

Apache License 2.0. Copyright (c) 2024-2026 CPZ Capital Ltd.