Quant Risk Optimizer

A professional-grade portfolio risk management and optimization platform that combines Python's ease of use with C++'s computational performance.

Built for quantitative analysts, portfolio managers, and financial engineers who need production-ready risk management tools with institutional-grade performance.

🚀 Key Features

High-Performance Risk Calculations

• Monte Carlo Value at Risk (VaR) - Industry-standard risk measurement with configurable confidence levels
• Expected Shortfall (ES/CVaR) - Coherent risk measure for tail risk assessment
• Portfolio Risk Decomposition - Asset-level risk contribution analysis
• Maximum Drawdown - Historical drawdown analysis with path simulation
• Volatility Metrics - Annualized portfolio volatility with time scaling

Advanced Portfolio Optimization

• Mean-Variance Optimization - Classic Markowitz portfolio theory implementation
• Maximum Sharpe Ratio - Risk-adjusted return optimization
• Minimum Variance Portfolio - Risk minimization with return constraints
• Efficient Frontier Generation - Complete risk-return frontier analysis
• Flexible Constraints - Min/max weight bounds and sector constraints

Hybrid Architecture

• C++ Computational Core - High-performance linear algebra using Eigen library
• Python Interface - Intuitive API with automatic fallback implementations
• pybind11 Integration - Seamless C++/Python interoperability with GIL release
• Memory Efficient - Optimized for large portfolios (50+ assets)

Interactive Dashboard

• Professional Web Interface - Built with Dash/Plotly for institutional use
• Real-time Calculations - Responsive UI with progress indicators
• Comprehensive Visualizations - Risk histograms, efficient frontiers, allocation charts
• Performance Benchmarking - C++ vs Python speed comparisons
• Export Capabilities - PDF reports and CSV data export

📋 Table of Contents

• Installation
• Quick Start
• Web Dashboard
• API Documentation
• Architecture
• Performance
• Development
• Testing
• Contributing
• License

🔧 Installation

Prerequisites

The following system dependencies are required:

# Ubuntu/Debian
sudo apt-get install cmake libeigen3-dev g++

# CentOS/RHEL  
sudo yum install cmake eigen3-devel gcc-c++

# macOS (with Homebrew)
brew install cmake eigen

# Windows (with vcpkg)
vcpkg install eigen3 cmake

Option 1: pip Install (Recommended)

pip install quant-risk-optimiser

Option 2: Development Install

# Clone the repository
git clone https://github.com/quantrisk/quant-risk-optimiser.git
cd quant-risk-optimiser

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Build C++ extensions
python setup.py build_ext --inplace

Verification

Test the installation:

python -c "import quant_risk_core; print('C++ backend available:', quant_risk_core.version())"
python -m pytest tests/ -v

🚀 Quick Start

Basic Risk Calculation

import numpy as np
from quant_risk_optimiser import create_risk_manager

# Portfolio data
returns = np.array([0.10, 0.08, 0.12, 0.04, 0.09])  # Expected annual returns
weights = np.array([0.30, 0.25, 0.20, 0.15, 0.10])   # Portfolio weights

# Covariance matrix (5x5 for 5 assets)
cov_matrix = np.array([
    [0.0225, 0.0045, 0.0030, -0.0015, 0.0020],
    [0.0045, 0.0324, 0.0054, -0.0009, 0.0015],
    [0.0030, 0.0054, 0.0625, 0.0000, 0.0040],
    [-0.0015, -0.0009, 0.0000, 0.0025, -0.0005],
    [0.0020, 0.0015, 0.0040, -0.0005, 0.0400]
])

# Create risk manager
risk_manager = create_risk_manager(seed=42)

# Calculate 95% VaR with 10,000 Monte Carlo simulations
var_result = risk_manager.calculate_var(
    returns=returns,
    cov_matrix=cov_matrix, 
    weights=weights,
    confidence_level=0.95,
    num_simulations=10000
)

print(f"Portfolio VaR (95%, 1-day): {var_result['var']:.2%}")
print(f"Computation time: {var_result['computation_time']:.3f}s")
print(f"Backend used: {var_result['method']}")

# Calculate Expected Shortfall
es_result = risk_manager.calculate_es(
    returns, cov_matrix, weights, confidence_level=0.95
)
print(f"Expected Shortfall (95%): {es_result['es']:.2%}")

Portfolio Optimization

from quant_risk_optimiser import create_optimizer

# Create optimizer
optimizer = create_optimizer()

# Find maximum Sharpe ratio portfolio
optimal_result = optimizer.maximize_sharpe_ratio(
    returns=returns,
    cov_matrix=cov_matrix,
    risk_free_rate=0.02  # 2% risk-free rate
)

if optimal_result.converged:
    print(f"Optimal weights: {optimal_result.weights}")
    print(f"Expected return: {optimal_result.expected_return:.2%}")
    print(f"Volatility: {optimal_result.volatility:.2%}")
    print(f"Sharpe ratio: {optimal_result.sharpe_ratio:.3f}")

# Generate efficient frontier
frontier_points = optimizer.generate_efficient_frontier(
    returns, cov_matrix, num_points=50
)

print(f"Generated {len(frontier_points)} efficient frontier points")

Advanced Usage with Constraints

# Set investment constraints
min_weights = np.full(5, 0.05)  # Minimum 5% in each asset
max_weights = np.full(5, 0.40)  # Maximum 40% in each asset

# Optimize with constraints
constrained_result = optimizer.maximize_sharpe_ratio(
    returns=returns,
    cov_matrix=cov_matrix,
    min_weights=min_weights,
    max_weights=max_weights
)

# Validate the result
validation = optimizer.validate_weights(
    constrained_result.weights, min_weights, max_weights
)
print(f"Weights valid: {validation['valid']}")

🖥️ Web Dashboard

Launch the interactive web dashboard for comprehensive portfolio analysis:

# Start the dashboard server
python -m quant_risk_optimiser.app

# Or run directly
cd frontend && python app.py

Navigate to http://localhost:8050 to access the dashboard.

Dashboard Features

1. Portfolio Upload: CSV/Excel file upload or use sample data
2. Risk Analysis: Interactive Monte Carlo simulations with real-time charts
3. Optimization: Sharpe ratio maximization, minimum variance, target return
4. Efficient Frontier: Visual risk-return analysis with 50 frontier points
5. Performance Benchmark: C++ vs Python speed comparison
6. Export Options: Download optimized portfolios and risk reports

Sample Dashboard Workflow

1. Upload your portfolio CSV with columns: Asset, Weight, Expected_Return, Volatility
2. Configure risk parameters (confidence level, simulations, time horizon)
3. Run risk calculation to see VaR, ES, and Monte Carlo histogram
4. Optimize portfolio using your preferred objective function
5. Generate efficient frontier to explore risk-return tradeoffs
6. Export results for further analysis

📚 API Documentation

Risk Management

create_risk_manager(seed=12345, use_cpp=True)

Factory function to create a risk manager instance.

Parameters:

• seed (int): Random seed for reproducible results
• use_cpp (bool): Use C++ backend when available

Returns: RiskManager instance

RiskManager.calculate_var(returns, cov_matrix, weights, **kwargs)

Calculate Value at Risk using Monte Carlo simulation.

Parameters:

• returns (np.ndarray): Expected returns vector
• cov_matrix (np.ndarray): Covariance matrix
• weights (np.ndarray): Portfolio weights (must sum to 1)
• confidence_level (float): Confidence level (default: 0.95)
• num_simulations (int): Number of MC simulations (default: 10,000)
• time_horizon (int): Time horizon in days (default: 1)

Returns: Dictionary with VaR result and metadata

RiskManager.calculate_es(returns, cov_matrix, weights, **kwargs)

Calculate Expected Shortfall (Conditional VaR).

Returns: Dictionary with ES result and metadata

Portfolio Optimization

create_optimizer(tolerance=1e-8, max_iterations=1000, use_cpp=True)

Factory function to create an optimizer instance.

PortfolioOptimizer.maximize_sharpe_ratio(returns, cov_matrix, **kwargs)

Find portfolio with maximum Sharpe ratio.

Returns: PortfolioResult with optimal weights and metrics

PortfolioOptimizer.generate_efficient_frontier(returns, cov_matrix, num_points=50)

Generate efficient frontier points.

Returns: List of FrontierPoint objects

Data Structures

PortfolioResult

Named tuple containing optimization results:

• weights: Optimal portfolio weights
• expected_return: Portfolio expected return
• volatility: Portfolio volatility
• sharpe_ratio: Sharpe ratio
• converged: Convergence flag
• computation_time: Execution time
• method: Backend used ('cpp' or 'python')

🏗️ Architecture

System Design

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   Web Dashboard     │    │   Python API        │    │   C++ Core          │
│   (Dash/Plotly)     │◄──►│   (Frontend)        │◄──►│   (Backend)         │
│                     │    │                     │    │                     │
│ • Interactive UI    │    │ • Risk Management   │    │ • Monte Carlo       │
│ • File Upload       │    │ • Optimization      │    │ • Linear Algebra    │
│ • Visualizations    │    │ • Data Validation   │    │ • Matrix Ops        │
│ • Export Tools      │    │ • Error Handling    │    │ • Eigen Library     │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
         │                           │                           │
         └───────────────────────────┼───────────────────────────┘
                                     │
                              ┌─────────────────────┐
                              │   pybind11          │
                              │   Bindings          │
                              │                     │
                              │ • C++/Python Bridge │
                              │ • GIL Release       │
                              │ • Type Conversion   │
                              │ • Error Propagation │
                              └─────────────────────┘

Technology Stack

Backend (C++):

• Eigen 3.4+: High-performance linear algebra
• Modern C++17: Memory safety and performance optimizations
• CMake: Cross-platform build system
• OpenMP: Parallel computing (optional)

Frontend (Python):

• NumPy/SciPy: Numerical computing and fallback implementations
• Dash 2.14+: Web application framework
• Plotly 5.15+: Interactive visualizations
• Pandas: Data manipulation and analysis

Integration:

• pybind11 2.10+: Seamless C++/Python bindings
• pytest: Comprehensive testing framework
• setuptools: Package building and distribution

Performance Architecture

The system uses a hybrid approach:

1. C++ Core: Computationally intensive operations (Monte Carlo, optimization)
2. Python Orchestration: High-level logic, data validation, UI
3. Automatic Fallback: Pure Python implementations when C++ unavailable
4. Memory Efficiency: Eigen's expression templates minimize memory allocation
5. Parallel Processing: OpenMP support for multi-core systems

⚡ Performance

Benchmark Results

Performance comparison on a representative portfolio optimization problem:

Operation	Problem Size	C++ Time	Python Time	Speedup
Monte Carlo VaR (10K sims)	10 assets	15ms	180ms	12x
Mean-Variance Optimization	20 assets	8ms	95ms	11.9x
Efficient Frontier (50 pts)	15 assets	120ms	1.2s	10x
Risk Decomposition	25 assets	5ms	45ms	9x

Benchmarks run on Intel i7-10700K, 32GB RAM, compiled with -O3 optimization

Scalability

The system efficiently handles portfolios of varying sizes:

• Small portfolios (2-10 assets): Sub-millisecond optimization
• Medium portfolios (10-30 assets): Millisecond-scale calculations
• Large portfolios (30-50 assets): Still under 100ms for most operations
• Memory usage: Linear scaling, ~1MB per 100 assets

Optimization Features

• GIL Release: C++ computations don't block Python threads
• SIMD Instructions: Vectorized operations on supported hardware
• Memory Pooling: Reduced allocation overhead for repeated calculations
• Expression Templates: Eigen optimizes away temporary objects
• Compiler Optimizations: Profile-guided optimization for hot paths

🛠️ Development

Build from Source

# Clone and setup
git clone https://github.com/quantrisk/quant-risk-optimiser.git
cd quant-risk-optimiser

# Install development dependencies
pip install -e ".[dev]"

# Build C++ extensions with debug symbols
CMAKE_BUILD_TYPE=Debug python setup.py build_ext --inplace

# Run development server
cd frontend && python app.py

Code Structure

quant-risk-optimiser/
├── backend/                 # C++ computational core
│   ├── risk.h/.cpp         # Risk calculation implementations
│   ├── optimize.h/.cpp     # Portfolio optimization algorithms  
│   ├── bindings.cpp        # pybind11 Python bindings
│   └── CMakeLists.txt      # Build configuration
├── frontend/               # Python API and web interface
│   ├── risk.py             # Risk management interface
│   ├── optimize.py         # Optimization interface
│   ├── app.py              # Dash web application
│   └── config.py           # Configuration and constants
├── tests/                  # Comprehensive test suite
│   ├── test_risk.py        # Risk calculation tests
│   └── test_optimize.py    # Optimization tests
├── data/                   # Sample data and uploads
│   └── sample_portfolio.csv
├── setup.py                # Package configuration
├── requirements.txt        # Python dependencies  
└── README.md              # This documentation

Contributing Guidelines

1. Fork the repository and create a feature branch
2. Write tests for new functionality with >90% coverage
3. Follow PEP 8 style guidelines and C++ Core Guidelines
4. Add documentation for public API functions
5. Benchmark performance-critical changes
6. Submit a pull request with clear description

Code Quality

# Run linting
flake8 frontend/ tests/
black frontend/ tests/ --check

# Type checking  
mypy frontend/

# Security scan
bandit -r frontend/

# Run full test suite with coverage
pytest tests/ --cov=frontend --cov-report=html

🧪 Testing

The project includes a comprehensive test suite covering both Python and C++ functionality.

Run Tests

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=frontend --cov-report=term-missing

# Run specific test modules
python -m pytest tests/test_risk.py -v
python -m pytest tests/test_optimize.py -v

# Run C++ backend tests (if available)
python -c "import tests.test_risk; tests.test_risk.TestRiskCalculations().test_cpp_availability()"

Test Categories

• Unit Tests: Individual function testing with edge cases
• Integration Tests: Full workflow testing with realistic data
• Performance Tests: Benchmark validation and regression detection
• Validation Tests: Mathematical correctness of financial calculations
• Error Handling: Input validation and graceful error recovery

Continuous Integration

The project uses automated testing on multiple platforms:

• Linux: Ubuntu 20.04+ with GCC 9+
• macOS: macOS 11+ with Clang 12+
• Windows: Windows 10+ with MSVC 2019+
• Python versions: 3.8, 3.9, 3.10, 3.11

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions from the quantitative finance community! Please see our Contributing Guidelines for details.

Areas for Contribution

• New risk metrics (CVaR variants, coherent risk measures)
• Advanced optimization (robust optimization, transaction costs)
• Performance optimizations (GPU computing, distributed processing)
• Additional constraints (sector limits, ESG constraints)
• Enhanced visualizations (3D frontier plots, correlation heatmaps)

📞 Support

• Documentation: Project Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: quant@example.com

🏆 Acknowledgments

• Eigen Team for the exceptional linear algebra library
• pybind11 Contributors for seamless C++/Python integration
• Plotly Team for outstanding visualization capabilities
• Quantitative Finance Community for feedback and testing

---

Built with ❤️ for the quantitative finance community

Quant Risk Optimizer - Where Performance Meets Precision