QMoE+: Hybrid Quantum Mixture of Experts

Quantum Mixture-of-Experts with coherent routing and data re-uploading (DRU) experts and load balancing.

Files

File	Description
train.py	Training script - single run entry point
models_final.py	All model architectures
datasets.py	Dataset loaders
noise.py	Depolarizing noise + shot sampling
qmoe_true_joint.py	Paper baseline
requirements.txt	Dependencies

Install

pip install -r requirements.txt

Run

python train.py \
    --model qmoe_plus_sparse \
    --dataset mnist_2cls \
    --gate-set RX+RY+RZ \
    --noise 0.0 \
    --top-k 1 \
    --seed 42 \
    --gpu 0 \
    --results-dir results/

Models

--model	Description
qmoe_plus_sparse	Main model - sparse coherent MoE with DRU experts
qmoe_hetero	Heterogeneous MoE: [QCNN, QSVM, QKNN, QNN] experts
qmoe_true_joint	Paper baseline
single_pqc	Single PQC, no MoE
dru_only	Single DRU circuit, no MoE
qsvm / qcnn / qknn / qnn	Standalone expert baselines
abl_sparse_no_dru	Ablation: SinglePQC experts instead of DRU
abl_sparse_no_coherent	Ablation: classical weighted sum instead of CoherentAgg

Top-k ablation: use --top-k 1/2/3/4 with qmoe_plus_sparse.

Datasets

mnist_2cls, mnist_4cls, fashion_2cls, fashion_4cls, synthetic, wine, wine_full, breast_cancer, breast_cancer_full

Noise

--noise	Effect
0.0	Noiseless
0.001 / 0.01 / 0.05	Depolarizing noise after every CNOT layer (train + eval)

Shot noise (1024 shots) is added on top during final evaluation when --noise > 0.

Validation / model selection

A held-out validation split is carved from the training set (stratified, seeded; --val-frac, default 0.15). Early stopping and checkpoint selection use validation accuracy only - the test set is scored once, at the end, on the val-selected checkpoint.

Split sizes are printed in the run header (train=… val=… test=…) and stored in config.json (train_n, val_n, test_n, val_frac).

Seeds

All reported tables are mean ± std over 5 independent seeds (--seed). Run one seed per invocation and aggregate across the seed_{s}/ output directories:

for s in "${SEEDS[@]}"; do   # 5 seeds
  python train.py --model qmoe_plus_sparse --dataset mnist_2cls \
    --gate-set RX+RY+RZ --noise 0.01 --top-k 1 --seed "$s" --gpu 0 \
    --results-dir results/
done

Output

Each run writes to {results-dir}/{group}/{dataset}/{model}/{gate_set}/noise_{n}/seed_{s}/:

config.json      run configuration (incl. train_n / val_n / test_n / val_frac)
epoch_log.csv    per-epoch train_acc, val_acc, best_val_acc, routing stats
summary.json     best_val_acc (selection) + best_model_acc_exact (TEST) + shots
best_model.pt    checkpoint at best VALIDATION accuracy
final_model.pt   last-epoch checkpoint