ProtQC

Physics-based verification of AI-designed protein structures

Catches structural hallucinations before wet-lab

Why ProtQC?

AI protein design tools (AlphaFold, RFdiffusion, ProteinMPNN, BoltzGen) routinely produce structures with high confidence scores (pLDDT > 90) that still fail experimentally. A protein can look perfect by pLDDT yet harbor internal voids, unstable hydrogen bond networks, or thermodynamic instabilities that only surface in solution.

ProtQC combines six physics-based metrics into a composite risk score, catching high-pLDDT hallucinations that no single metric detects on its own.

Quick Start

protqc analyze protein.pdb

The 6 Metrics

Each metric produces a normalized 0–1 sub-score. The composite risk score is a weighted sum, mapped to a verdict:

• PASS (risk < 0.30) — Design is physically plausible
• WARNING (0.30 ≤ risk < 0.50) — Proceed with caution; review flagged metrics
• FAIL (risk ≥ 0.50) — Design has significant structural issues

Risk Scoring Weights

risk_weights:
  plddt: 0.12
  md_rmsd: 0.29
  cavity: 0.12
  hbond_persistence: 0.24
  ss_preservation: 0.18
  sasa_ratio: 0.05

Validated Results

Performance

Usage

ProtQC provides three usage modes:

CLI — Single Protein Analysis

# Analyze a PDB file
protqc analyze protein.pdb

# Enter a PDB ID — auto-downloads from RCSB
protqc analyze 1UBQ

# Skip MD simulation for quick structural checks
protqc analyze protein.pdb --skip-md

# Set MD simulation length
protqc analyze protein.pdb --md-duration 10

# Use pre-computed MD trajectory
protqc analyze protein.pdb --trajectory md_output.csv

# Generate FastQC-style HTML report
protqc analyze protein.pdb --html report.html

# JSON output
protqc analyze protein.pdb --format json

Interactive Mode

# Launch interactive prompt — guides you through analysis
protqc

AI Chat Assistant

# Start AI-powered chat for interpreting results
protqc chat

Chat supports 8 providers via LiteLLM: OpenAI, Anthropic, Google, DeepSeek, OpenRouter, Moonshot, MiniMax, Zhipu.

Installation

PyPI + conda (recommended)

conda create -n protqc python=3.11
conda activate protqc

# OpenMM and fpocket from conda-forge (not available on PyPI)
conda install -c conda-forge openmm fpocket

# Install ProtQC with all dependencies
pip install protqc

# Analyze a protein
protqc analyze protein.pdb

Source install (development)

git clone https://github.com/korayguzel/protqc.git
cd protqc
conda create -n protqc python=3.11
conda activate protqc
conda install -c conda-forge openmm fpocket
pip install -e '.[all,dev]'

Docker (all platforms)

Docker bundles all dependencies (OpenMM, CUDA, fpocket, FreeSASA, MDTraj):

# Build the image
docker build -t protqc .

# Analyze a protein (GPU-accelerated)
docker run --gpus all -v $(pwd)/data:/app/data protqc analyze data/benchmark/ubiquitin.pdb

# Run with MD simulation
docker run --gpus all -v $(pwd)/data:/app/data protqc analyze data/benchmark/ubiquitin.pdb --md-duration 10

# CPU-only (MD will be slow)
docker run -v $(pwd)/data:/app/data -e CUDA_VISIBLE_DEVICES="" protqc analyze protein.pdb --skip-md

Docker Compose:

# GPU-accelerated
docker compose run protqc analyze data/benchmark/ubiquitin.pdb

# CPU-only variant
docker compose run protqc-cpu analyze data/benchmark/ubiquitin.pdb --skip-md

Note: GPU support requires the NVIDIA Container Toolkit. Without a GPU, MD simulations still work but are significantly slower (~10–50x). Use --skip-md for quick checks without MD.

Configuration

All thresholds, weights, and verdict boundaries are defined in configs/thresholds.yaml. Key tunables:

• Intrinsically disordered proteins: Increase physics_verifier.md_rmsd_max_angstrom (e.g., 8.0–10.0) since higher RMSD is expected
• Membrane proteins: Adjust surface.sasa_polar_ratio_min/max for transmembrane segments

Limitations

ProtQC is a rapid pre-screening tool, not a substitute for comprehensive computational or experimental validation:

• MD simulation length. The default 10 ns simulation is a rapid pre-screen that catches catastrophic failures (large RMSD drift, complete unfolding). Subtle instabilities — slow conformational changes, partial unfolding events, aggregation-prone intermediates — may require 100–500 ns simulations for reliable detection (Lindorff-Larsen et al. 2011; Ferruz et al. 2022). Treat a ProtQC PASS as "no obvious red flags," not "experimentally validated."

• Cavity detection. fpocket was designed for identifying druggable surface binding pockets, not for internal void quality control (Le Guilloux et al. 2009). The suspicious cavity flagging (volume > 800 A^3, druggability < 0.4) is a literature-informed heuristic (Schmidtke et al. 2010), not a validated structural defect detector. Combine with packing density metrics or Voronoi-based tools for higher confidence.

• Risk score weights. The current weights are expert estimates based on published benchmarks (Dauparas et al. 2022; Ferruz et al. 2022) and will be refined through calibration on larger, more diverse protein sets. Different protein families (membrane proteins, IDPs, repeat proteins) may need substantially different weight profiles.

Related Tools

Roadmap

v0.2.0 — Benchmark dataset (25 proteins, Garcia/Hermosilla/Chevalier), Colab MCP integration, weight calibration, replica runs

v0.3.0 — Thermal stability prediction, MultiQC-style batch reports, Nextflow/Snakemake templates, REST API

License

MIT

Citation

Güzel, Ö.K. (2026). ProtQC: Physics-based verification of AI-designed protein designs.
github.com/korayguzel/protqc