cvxrisk: Convex Optimization for Portfolio Risk Management

📋 Overview

cvxrisk is a Python library for portfolio risk management using convex optimization. It provides a flexible framework for implementing various risk models that can be used with CVXPY to solve portfolio optimization problems.

The library is built around an abstract Model class that standardizes the interface for different risk models, making it easy to swap between them in your optimization problems.

🚀 Installation

```bash

Install from PyPI (without any convex solver)

pip install cvxrisk

Install with Clarabel solver

pip install cvxrisk[clarabel]

Install with Mosek solver

pip install cvxrisk[mosek]

For development installation

git clone https://github.com/cvxgrp/cvxrisk.git cd cvxrisk make install

For experimenting with the notebooks (after cloning)

make marimo ```

⚠️ Warning! The package does not install a convex solver if not explicitly desired. It relies on cvxpy-base. If you use cvxrisk as a dependency in your projects you may want to install clarabel using pip install cvxrisk[clarabel] or mosek using pip install cvxrisk[mosek].

🔧 Quick Start

cvxrisk makes it easy to formulate and solve portfolio optimization problems:

```python

import cvxpy as cp import numpy as np from cvxrisk.sample import SampleCovariance from cvxrisk.portfolio import minrisk_problem

# Create a risk model riskmodel = SampleCovariance(num=2)

# Update the model with data riskmodel.update( ... cov = np.array([[1.0, 0.5], [0.5, 2.0]]), ... lowerassets = np.zeros(2), ... upperassets = np.ones(2) ... )

# Define portfolio weights variable weights = cp.Variable(2)

# Create and solve the optimization problem problem = minrisk_problem(riskmodel, weights) problem.solve()

# Print the optimal weights print(np.round(weights.value, 2)) [0.8 0.2] ```

📊 Features

cvxrisk provides several risk models:

Sample Covariance

The simplest risk model based on the sample covariance matrix:

```python

from cvxrisk.sample import SampleCovariance import numpy as np

riskmodel = SampleCovariance(num=2) riskmodel.update(cov=np.array([[1.0, 0.5], [0.5, 2.0]])) riskmodel.parameter["cov"].value array([[1., 0.5], [0.5, 2.]]) ```

Factor Risk Models

Factor models reduce dimensionality by projecting asset returns onto a smaller set of factors:

```python

import numpy as np from cvxrisk.factor import FactorModel from cvxrisk.linalg import pca import pandas as pd

# Create some sample returns data returns = pd.DataFrame(np.random.randn(100, 25))

# Compute principal components factors = pca(returns, n_components=10)

# Create and update the factor model model = FactorModel(assets=25, k=10) model.update( ... cov = factors.cov.values, ... exposure = factors.exposure.values, ... idiosyncratic_risk = factors.idiosyncratic.std().values ... )

# Verify the model has the correct dimensions model.parameter["exposure"].value.shape (10, 25) ```

Factor risk models use the projection of the weight vector into a lower dimensional subspace, e.g. each asset is the linear combination of $k$ factors.

$$ri = \sum{j=1}^k fj \beta{ji} + \epsilon_i$$

The factor time series are $f1, \ldots, fk$. The loadings are the coefficients $\beta{ji}$. The residual returns $\epsiloni$ are assumed to be uncorrelated with the factors.

Any position $w$ in weight space projects to a position $y = \beta^T w$ in factor space. The variance for a position $w$ is the sum of the variance of the systematic returns explained by the factors and the variance of the idiosyncratic returns.

$$Var(r) = Var(\beta^T w) + Var(\epsilon w)$$

We assume the residual returns are uncorrelated and hence

$$Var(r) = y^T \Sigmaf y + \sumi wi^2 Var(\epsiloni)$$

where $\Sigmaf$ is the covariance matrix of the factors and $Var(\epsiloni)$ is the variance of the idiosyncratic returns.

Conditional Value at Risk (CVaR)

CVaR measures the expected loss in the worst-case scenarios:

```python

import numpy as np from cvxrisk.cvar import CVar

# Create some sample historical returns historical_returns = np.random.randn(50, 14)

# Create and update the CVaR model model = CVar(alpha=0.95, n=50, m=14) model.update(returns=historical_returns)

# Verify the model parameters model.alpha 0.95 model.parameter["returns"].value.shape (50, 14) ```

📚 Documentation

For more detailed documentation and examples, visit our documentation site.

🛠️ Development

cvxrisk uses modern Python development tools:

```bash

Install development dependencies

make install

Run tests

make test

Format code

make fmt

Start interactive notebooks

make marimo ```

📄 License

cvxrisk is licensed under the Apache License 2.0. See LICENSE for details.

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For more information, see CONTRIBUTING.md.