Pep-Q-GAN

Official implementation of the paper: "Hybrid quantum-classical de novo design of MHC-binding peptides"

This repository implements both, purely classical and hybrid quantum-classical, Generative Adversarial Networks (GANs) for generating of MHC class I-binding peptides. The hybrid models utilize quantum prior distributions that generate more binding peptides than classical ones.

Installation

Requires Python 3.12+. uv is recommended for faster package management.

Step 1: Install uv (recommended)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: install with pip
pip install uv

Step 2: Create and activate virtual environment

uv venv
source .venv/bin/activate  # macOS/Linux
# or: .venv\Scripts\activate  # Windows

Step 3: Install package

# Install dependencies and package
uv pip install -e .

Alternative (pip)

# Optional: Create virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or: .venv\Scripts\activate  # Windows

# Install in editable mode
pip install -e .

Usage

Training

The recommended way to train the WGAN-GP models is to use the train.sh script. Set the seeds, config_names and available gpus in the script and execute it.

Note: Make you make the necessary changes in the config file in the conf folder.

./train.sh

Alternatively you can train a single WGAN-GP is to use the scripts/wgangp_train.py script with Hydra configuration:

python scripts/wgangp_train.py

Inference

The recommended way to train the WGAN-GP models is to use the generate_peptides.sh script. Set the available gpus, root_dir, seeds, config_names and the number of samples nsamps in the script and execute it.

./generate_peptides.sh

Alternatively, you can generate peptides from a trained model using the scripts/gan_infer.py script:

python scripts/gan_infer.py \
  --model_dir MODEL_DIR \
  --hla_file data/unique_hla_allotypes.txt \
  --samples_per_condition N_SAMPS \
  --output_path generated_peptides.txt

Inference Parameters

• --model_dir: Directory containing trained model checkpoints (required)
• --checkpoint: Checkpoint filename to load (default: latest.pt)
• --hla_file: File containing HLA types, one per line (required)
• --samples_per_condition: Number of samples to generate per HLA type (default: 100)
• --output_path: Output file path for generated peptides (default: generated_peptides.txt)

Inference Examples

# Generate 50 samples for each HLA type
python scripts/gan_infer.py \
  --model_dir MODEL_DIR \
  --hla_file data/unique_hla_allotypes.txt \
  --samples_per_condition 50

# Use a specific checkpoint
python scripts/gan_infer.py \
  --model_dir MODEL_DIR \
  --checkpoint checkpoint_step_10.pt \
  --hla_file data/unique_hla_allotypes.txt \
  --output_path my_peptides.txt

The generated output is a tab-separated file with columns: sequence and hla.

Binding Analysis

Note: Before running binding analysis, ensure you have the NetMHCpan executable and you have generated peptide outputs for all relevant models (run generate_peptides.sh). Each model should have its own peptide output file to enable comprehensive binding evaluation.

Analyze binding affinities for generated peptides using the scripts/netmhc_calc_binding.py script:

./compute_bindings.sh

This script processes tab-separated files from inference (with peptide and HLA columns) and computes binding predictions using NetMHCpan for each peptide-HLA pair.

The script will process the generated petides and create a folder gen_peptides under the results/ folder. It will also create a new folder netmhc_outputs under the results/ folder. The binding results are saved as csv file with binding scores and ranks.

Prerequisites:

• NetMHCpan (more information on installation and usage can be found at https://services.healthtech.dtu.dk/services/NetMHCpan-4.2/)
• Tab-separated input file with peptide and HLA columns

Parameters:

• --netmhc_executable_path: Path to NetMHCpan executable (required)
• --root_dir: Folder where the model results are stored (default: "outputs")

Quantum Latent Configuration

For quantum-based latent distributions, configure the latent yaml file in your config:

_target_: pepqgan.samples.get_samples.get_latent
latent_type: sps_indist
z_dim: 32
batch_size: ${batch_size}
samples_dir: path/to/samples/

Note: Make sure to specify the correct path to samples.

To use the pre-configured quantum setup, specify the config name:

python scripts/wgangp_train.py latent=pt2

Other Configuration Override Examples

Override specific parameters:

# Basic training with custom parameters
python scripts/wgangp_train.py \
  train_data=data/HLA_pos9mers.txt \
  batch_size=512

# Adjust model architecture and training
python scripts/wgangp_train.py \
  generator.hidden_size=1024 \
  training.gradient_penalty=5

Configuration Structure

The main configuration file is at conf/config.yaml. The configuration is managed by Hydra and structured hierarchically:

• Main Config (conf/config.yaml):

  • train_data: Path to training data file
  • pseudo_file: Path to MHC pseudo sequence file
  • hla_type: HLA type filtering (null for no filtering)
  • batch_size: Training batch size
  • seed: Random seed for training and generator seeding

• Latent Configuration (conf/latent/):

  • Configures the latent generator. Options include:
    • gaussian.yaml
    • bernoulli.yaml
    • pt2.yaml
    • quantum_sps.yaml
    • distinguishable_sps.yaml

• Model Architectures (conf/models/):

  • Configures the Generator and Discriminator parameters (e.g., models.yaml which defines hidden_size).

• Training Hyperparameters (conf/training/):

  • Configures learning rate, training iterations, and scheduling (e.g., di5.yaml which defines learning_rate, discriminator_iterations, weight_decay, max_steps, gradient_penalty, log_interval, and save_interval).

Quantum samples

Quantum samples used for training WGAN-GP models can be obtained by emailing wclements@orcacomputing.com.

Citation

Cite our paper using the following bibtex item:

@article {Engdal2026.07.09.736951,
	author = {Engdal, Emilie Sofie and Funk, Jonathan and Bacarreza, Omar and Machado, Laura and Johansen, Kristoffer Haurum and Kemming, Janine and Farnsworth, Thorin and Brasas, Valentas and Lefevre-Morand, Rodrigue Yves Louis and Slysz, Mateusz and Noerregaard, Oliver Luscombe and Sandberg, Oliver August Dall Alba and Makarovskiy, Alexander and Lodahl, Peter and Acevedo-Rocha, Carlos G. and Kurowski, Krzysztof and Hadrup, Sine Reker and Clements, William R. and Jenkins, Timothy},
	title = {Hybrid quantum-classical de novo design of MHC-binding peptides},
	elocation-id = {2026.07.09.736951},
	year = {2026},
	doi = {10.64898/2026.07.09.736951},
	URL = {https://www.biorxiv.org/content/early/2026/07/10/2026.07.09.736951},
	eprint = {https://www.biorxiv.org/content/early/2026/07/10/2026.07.09.736951.full.pdf},
	journal = {bioRxiv}
}