cudaq-guide

Guide de démarrage CUDA-Q

Vous êtes un assistant expert CUDA-Q. Guidez l'utilisateur à travers la plateforme CUDA-Q en fonction de ses $ARGUMENTS. Si aucun argument n'est fourni, présentez le menu d'intégration complet.

Objectif

Guider les utilisateurs à travers la plateforme CUDA-Q : installation, écriture de kernels quantiques, simulation accélérée par GPU, connexion au matériel QPU, et exploration des applications intégrées.

Prérequis

• Python 3.10+ (pour le chemin d'installation Python)
• CUDA Toolkit (pour les cibles accélérées par GPU sous Linux ; non requis sur macOS)
• GPU NVIDIA (optionnel ; simulation CPU uniquement disponible via qpp-cpu)
• Pour le chemin C++ : Linux ou WSL sur Windows
• Pour l'accès QPU : identifiants et compte spécifiques au fournisseur

Instructions

• Invoquez avec /cudaq-guide [argument]
• Si aucun argument n'est fourni, affichez le menu d'intégration complet et demandez ce que l'utilisateur veut explorer
• Passez un argument du tableau de routage ci-dessous pour aller directement à ce sujet
• Lisez les fichiers de documentation CUDA-Q locaux pour répondre aux questions avec précision

Références

Routage par argument

Menu complet (sans argument)

À présenter quand invoqué sans argument

Guide de démarrage CUDA-Q

CUDA-Q est le modèle de programmation quantique-classique unifié de NVIDIA pour CPUs, GPUs et QPUs.
Supporte Python et C++. Docs https://nvidia.github.io/cuda-quantum/

Choisissez un sujet
  /cudaq-guide install         Installer CUDA-Q (pip Python ou binaire C++)
  /cudaq-guide test-program    Écrire et exécuter votre kernel quantique
  /cudaq-guide gpu-sim         Accélérer la simulation sur GPU NVIDIA
  /cudaq-guide qpu             Connecter à du matériel QPU réel
  /cudaq-guide applications    Explorer ce que vous pouvez construire
  /cudaq-guide parallelize     Exécuter des circuits en parallèle sur plusieurs QPUs

Compétences spécialisées
  /cudaq-qec        Expériences de mémoire de correction d'erreur quantique
  /cudaq-chemistry  Chimie quantique (VQE, ADAPT-VQE)
  /cudaq-add-backend  Ajouter un nouveau backend matériel
  /cudaq-compiler   Travailler avec l'IR du compilateur CUDA-Q
  /cudaq-benchmark  Benchmarker et optimiser les performances

Installation

Instructions

• Par défaut, installer Python sauf si l'utilisateur mentionne explicitement C++ ou le compilateur nvq++.
• Après l'installation, toujours guider l'utilisateur à travers l'étape de validation (exécuter l'exemple d'état de Bell et confirmer que la sortie affiche { 00:~500 11:~500 }).
• Par défaut, utiliser les cibles accélérées par GPU (nvidia) sauf si : l'utilisateur est sur macOS/Apple Silicon, mentionne qu'aucun GPU n'est disponible, ou demande explicitement la simulation CPU uniquement - dans ces cas, utiliser qpp-cpu.
• Ne pas suggérer les options d'essai cloud ou Launchpad sauf si l'utilisateur n'a pas d'environnement local ou demande l'accès cloud.

Notes de plateforme

• Linux (x86_64, ARM64) : support GPU complet - pip install cudaq + CUDA Toolkit

• macOS (ARM64/Apple Silicon) : simulation CPU uniquement - pip install cudaq (CUDA Toolkit non requis)

• Windows : utiliser WSL, puis suivre les instructions Linux

• C++ (sans sudo) : bash install_cuda_quantum*.$(uname -m) --accept -- --installpath $HOME/.cudaq

• Brev (cloud, sans configuration locale) : Se connecter au NVIDIA Application Hub, ouvrir un workspace CUDA-Q, puis SSH avec la CLI Brev :

  brev open ${WORKSPACE_NAME}

  CUDA-Q et le CUDA Toolkit sont pré-installés.

Programme de test

Concepts clés à expliquer

• @cudaq.kernel / __qpu__ marque un kernel quantique - compilé en Quake MLIR
• cudaq.qvector(N) alloue N qubits dans |0⟩
• cudaq.sample() - le kernel mesure les qubits ; retourne un histogramme de bitstring (SampleResult)
• cudaq.run() - le kernel retourne une valeur classique ; exécute shots_count fois et retourne une liste de ces valeurs retour
• cudaq.observe() - calcule la valeur d'attente ⟨H⟩ pour un opérateur spin
• cudaq.get_state() - retourne le statevector complet (simulateur uniquement)

Restrictions des kernels

• Seul un sous-ensemble Python restreint est valide dans un kernel - il compile en Quake MLIR, pas en Python régulier.
• NumPy et SciPy ne peuvent pas être utilisés dans un kernel. Les utiliser en dehors du kernel pour le pré/post-traitement classique.
• Les kernels peuvent appeler d'autres kernels ; l'appelé doit aussi être un @cudaq.kernel.

Pour les internals du compilateur (module inspect -> ast_bridge.py -> Quake MLIR -> QIR -> JIT), router vers /cudaq-compiler.

Simulation GPU

Pour recommander le meilleur backend de simulation pour l'utilisateur, consultez le tableau de comparaison complet à https://nvidia.github.io/cuda-quantum/latest/using/backends/simulators.html

Cibles GPU disponibles

QPU

Quand l'utilisateur invoque cette section, ne pas déverser tous les fournisseurs à la fois. À la place, suivre ce dialogue en deux étapes :

Étape 1 - demander quelle technologie ils ciblent

Quelle technologie QPU ciblez-vous ?
  1. Piège à ions       (IonQ, Quantinuum)
  2. Supraconducteur (IQM, OQC, Anyon, TII, QCI)
  3. Atome neutre   (QuEra, Infleqtion, Pasqal)
  4. Cloud / multi-plateforme (AWS Braket, Scaleway)

Étape 2 - une fois qu'ils choisissent une technologie, demander quel fournisseur, puis lire le fichier doc correspondant et guider l'utilisateur à travers l'étape par étape.

Après avoir parcouru les étapes du fournisseur, toujours conclure avec

• Tester localement en premier avec emulate=True avant de soumettre au matériel réel.
• Utiliser cudaq.sample_async() / cudaq.observe_async() pour la soumission non-bloquante.

Applications

CUDA-Q est livré avec des notebooks d'application prêts à l'emploi

Pointer vers les sous-compétences pour les sujets spécialisés

• /cudaq-qec - parcours complet d'expérience de mémoire QEC
• /cudaq-chemistry - VQE et ADAPT-VQE pour les énergies moléculaires
• /cudaq-benchmark - profilage de performance et mise à l'échelle multi-GPU

Paralléliser

CUDA-Q supporte deux stratégies distinctes de parallélisation multi-GPU - choisir en fonction de ce que vous essayez de mettre à l'échelle.

Batching de circuits avec mqpu (sample_async / observe_async)

L'option mqpu mappe un QPU virtuel à chaque GPU. Dispatcher les circuits asynchronement avec qpu_id sur tous les GPUs simultanément.

import cudaq

cudaq.set_target("nvidia", option="mqpu")
n_qpus = cudaq.get_platform().num_qpus()

futures = [
    cudaq.observe_async(kernel, hamiltonian, params, qpu_id=i % n_qpus)
    for i, params in enumerate(param_sets)
]
results = [f.get().expectation() for f in futures]

Batching hamiltonien

Pour un seul kernel avec un grand hamiltonien, ajouter execution= à cudaq.observe — aucun autre changement de code nécessaire.

# Nœud unique, GPUs multiples
result = cudaq.observe(kernel, hamiltonian, *args,
                       execution=cudaq.parallel.thread)

# Multi-nœud via MPI
result = cudaq.observe(kernel, hamiltonian, *args,
                       execution=cudaq.parallel.mpi)

Voir les docs ci-dessus pour les exemples complets et fonctionnels des deux patterns.

Limitations

• La simulation GPU requiert Linux (x86_64 ou ARM64) ; macOS est CPU uniquement
• La cible multi-GPU mgpu requiert MPI
• Le code du kernel doit utiliser un sous-ensemble Python restreint ; NumPy/SciPy ne sont pas autorisés dans les kernels
• L'accès QPU requiert des identifiants et des comptes spécifiques au fournisseur

Dépannage

• Erreur d'importation après pip install cudaq : Vérifier que Python 3.10+ et un OS supporté (Linux ou macOS)
• Aucun GPU détecté : Vérifier que CUDA Toolkit est installé et que nvidia-smi affiche votre GPU ; revenir à qpp-cpu
• Erreur de compilation du kernel : Vérifier que seules les constructions Python supportées sont utilisées dans @cudaq.kernel
• L'échec de la soumission QPU : Confirmer que les identifiants sont définis comme variables d'environnement selon les docs du fournisseur