Project-Q — Quantitative Risk System

Multivariate GARCH–Vine Copula Hybrid Framework with Monte Carlo Simulation & Quantum Exploration Layer

A 2-week intensive pilot building a production-grade quantitative risk system that combines classical volatility modelling, advanced dependency analysis, large-scale simulation, and an honest quantum-inspired exploration layer.

---

Overview

Traditional risk models assume constant volatility and linear correlations between assets — assumptions that collapse during market crises. Project-Q addresses this by building a hybrid pipeline that captures:

• Volatility clustering via Multivariate GARCH (DCC-GARCH)
• Non-linear, tail-dependent asset relationships via Vine Copulas (C-vine / R-vine)
• Regime-aware stress testing via Monte Carlo simulation (1k–5k scenarios)
• Complex systems dynamics — herding behaviour, feedback loops, network effects
• Quantum-inspired acceleration — an honest POC for high-dimensional dependency estimation

The final output is a live risk dashboard presenting VaR, Expected Shortfall, stress scenarios, network topology, and regime analysis — presented to founders and mentors on Day 14.

---

Architecture

Raw Data → Data Pipeline → Log Returns / Regime Labels
                              ↓
                     DCC-GARCH Volatility Model
                              ↓
                     Standardised Residuals
                              ↓
                     Vine Copula (C-vine / R-vine)
                              ↓
                     Joint Dependency Simulations
                              ↓
              ┌───────────────┴───────────────┐
              │                               │
     Monte Carlo Engine              Quantum Sampling (POC)
     (1k–5k scenarios)                (small asset subset)
              │                               │
              └───────────────┬───────────────┘
                              ↓
                     Risk Metrics (VaR / CVaR)
                              ↓
                     Backtesting & Validation
                              ↓
                     Interactive Dashboard (Dash/Plotly)

---

Project Structure

project-q/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                # CI (lint, test, bench)
│   │   └── release.yml           # Tagged release pipeline
│   └── PULL_REQUEST_TEMPLATE.md  # Standardised PR checklist
├── src/project_q/                # Core library
│   ├── __init__.py
│   ├── core.py                   # Pipeline orchestration
│   ├── logging.py                # Shared structured logging
│   ├── versioning.py             # Output versioning & manifests
│   ├── data/                     # Data ingestion & preprocessing
│   ├── volatility/               # GARCH / DCC-GARCH models
│   ├── copula/                   # Vine copula dependency models
│   ├── network/                  # Network analysis & systemic risk
│   ├── simulation/               # Monte Carlo engine
│   ├── risk/                     # VaR, ES, backtesting
│   ├── quantum/                  # Quantum exploration layer (POC)
│   └── dashboard/                # Backend data API for dashboard
├── tests/                        # Unit & integration tests
│   ├── conftest.py               # Shared fixtures (synthetic data)
│   └── test_core.py              # Pipeline stage tests
├── benchmarks/                   # Performance benchmarks
│   ├── conftest.py               # Parameterised fixtures
│   ├── bench_core.py             # pytest-benchmark profiling
│   └── bench_utils.py            # Benchmark comparison utilities
├── docs/                         # Documentation & references
│   ├── conventions.md            # Logging & output versioning conventions
│   ├── spec.md                   # Technical specification (Ankur)
│   ├── project-assignment-plan.md # Role-wise daily assignment plan
│   └── 2-Week Pilot Project Day-Day Plan.pdf  # Master sprint plan
├── frontend/                         # React + Vite + Tailwind dashboard
│   ├── src/
│   │   ├── context/ThemeContext.jsx   # Dark/light mode state
│   │   ├── components/               # Panel components (Header, KPI, etc.)
│   │   ├── Pages/Dashboard.jsx       # Composed dashboard page
│   │   ├── App.jsx                   # Main app entry
│   │   └── index.css                 # Tailwind + base styles
│   ├── package.json
│   └── vite.config.js
├── scripts/
│   ├── seed_data.py                  # Download seed datasets
│   └── create_issues.sh              # GitHub issue creation script
├── CONTRIBUTING.md               # Git workflow & team conventions
├── pyproject.toml                # Package config, dependencies, tool settings
├── requirements.txt              # Locked pins for CI reproducibility
├── requirements-dev.txt          # Dev/test extras
├── .env.example                  # Environment variable template
├── Makefile                      # Common tasks (install, test, lint, bench)
└── .pre-commit-config.yaml       # Git hooks (ruff, mypy, file hygiene)

---

Quick Start

Prerequisites

• Python 3.11+
• Git

Setup

# Clone the repository
git clone https://github.com/project-q-team/project-q.git
cd project-q

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install all dependencies (production + dev)
make install-dev

# Download seed datasets
make seed

Daily Workflow

# Run linter
make lint

# Auto-format code
make format

# Run tests with coverage
make test

# Run benchmarks
make bench

# Fit volatility models (Day 3+)
make fit-vol

# See all available commands
make help

---

Team

Person	Role
Ankur	Research & Quant Systems Lead
Ankur	Infrastructure, Validation & Benchmarking
Sunil	Quantum Research & Exploratory Modeling
Dharani	Visualisation & Interactive Systems
Grace	Optimization & Quantum Pipeline Engineer
Rishik	Data Processing & Simulation Engineer

---

Sprint Phases

Phase	Days	Focus
1	1–2	Foundation — repo setup, data pipeline
2	3–7	Modelling Core — GARCH, copulas, integration
3	8–10	Risk Engine — Monte Carlo, VaR/ES, backtest
4	11–12	Quantum POC & full dashboard
5	13–14	Report, slides, demo day

Code freeze: End of Day 12. Days 13–14 are presentation-only.

---

Key Rules

1. Git push deadline — 6:30 PM IST daily (before standup)
2. Daily standup — 7:30–9:00 PM IST
3. One measurable output per person per day — no exceptions
4. Quantum layer — genuine POC only, no unsupported claims
5. All computation complete by Day 12

---

Quick Start (Docker)

One command to build and run the full stack:

git clone https://github.com/weebcoder101/Project-Q-Pilot-Project.git
cd Project-Q-Pilot-Project
docker compose up --build

Then open http://localhost:8080.

The dashboard loads with pre-computed pipeline results. The Quantum Comparison tab generates on first request.

To rebuild from scratch after changes:

docker compose down --remove-orphans -v
docker compose up --build

Windows (Docker Desktop)

If Docker Desktop's WSL integration is disabled for this distro, run this from Windows PowerShell as Administrator:

powershell -ExecutionPolicy Bypass -File scripts/docker-deploy.ps1

This script builds, starts, waits for health, and compacts the Docker VHDX automatically.

---

Tech Stack

Layer	Libraries
Data	pandas, yfinance, NumPy
Volatility	arch (GARCH, EGARCH, DCC-GARCH)
Dependency	pyvinecopulib (C-vine / R-vine), SciPy
Network	NetworkX (MST, centrality, community detection)
Simulation	NumPy (vectorised MC), SciPy
Risk Metrics	Custom (VaR, CVaR, Kupiec, Christoffersen)
Regime Detection	statsmodels (Markov switching)
Quantum	Qiskit, PennyLane (simulator-based POC)
Dashboard	Plotly, Dash
Testing	pytest, pytest-cov, pytest-benchmark
Code Quality	ruff, mypy, pre-commit
CI/CD	GitHub Actions

---

License

MIT