Importation CUDA-Q

Objectif

Utilise cette skill pour porter des circuits quantiques d'un autre framework vers des kernels Python CUDA-Q. Cela inclut le code Qiskit et la construction de circuits de style Qiskit, ainsi que d'autres constructeurs de circuits pilotés par framework. L'objectif est un port CUDA-Q sans framework qui préserve l'algorithme quantique source, reproduit le comportement source sur les petites tailles de test, et documente les limitations CUDA-Q inévitables.

Pour l'authorship de nouveaux kernels CUDA-Q from scratch, et pour l'installation de CUDA-Q, les cibles de simulation, l'accès aux QPU et la parallélisation, utilise la skill cudaq-guide (/cudaq-guide author pour l'authorship de kernels).

Prérequis

Python 3.10+.
CUDA-Q installé dans l'environnement cible. Vérifie le runtime avec : python -c "import cudaq; print(getattr(cudaq, '__version__', 'unknown'))".
Accès à l'implémentation source et un moyen d'exécuter ou inspecter son comportement attendu.
Pour valider par rapport au framework source (p. ex. Qiskit/Aer), il doit être installé dans l'environnement de validation uniquement. Le port CUDA-Q final lui-même ne doit pas nécessiter le framework source.
Lors de l'utilisation de connecteurs MCP de documentation ou de repository CUDA-Q, vérifie que le connecteur est disponible avant de t'y fier ; sinon, utilise la documentation locale ou l'arborescence source.
Lors du débogage, si la version CUDA-Q installée diffère de la documentation la plus récente, examine la documentation pertinente ou les modifications source avant de traiter une différence de comportement comme un bug de portage.

Flux de travail

Lis la construction du circuit source et identifie l'algorithme exact, la disposition des qubits/registres, le comportement de mesure et tout helper du framework.
Préserve l'algorithme quantique de haut niveau. Ne remplace pas les mesures mid-circuit, la structure QPE, les définitions d'oracle ou la stratégie de décomposition sans permission explicite de l'utilisateur.
Sélectionne le pattern d'exécution CUDA-Q :
- Utilise cudaq.sample pour l'échantillonnage de mesure finale.
- Utilise cudaq.run quand les valeurs de mesure mid-circuit doivent être retournées ou utilisées par shot.
- Utilise des kernels avec arguments runtime à la place de kernels générés par taille, sauf si CUDA-Q nécessite une forme de retour de longueur fixe.
Traduis les portes et sous-circuits. Pour les mappages de portes détaillés, les règles d'ordonnancement, les orientations de précision et les patterns d'extraction de helpers, consulte references/porting-reference.md.
Supprime les dépendances au framework source du runtime du port CUDA-Q. Extrait les helpers purs dans des modules sans framework.
Valide avec des petites entrées déterministes avant de passer à l'échelle. Compare les clés de count brutes et les distributions, pas seulement la fidélité agrégée.
Réexécute toute configuration précédemment défaillante après chaque correction.

Règles principales

Garde l'algorithme source intact sauf si l'utilisateur approuve un changement.
N'introduis pas de caps de qubit fixes, d'arités de contrôle fixes ou d'imports de framework source sauf s'ils sont véritablement inévitables et documentés.
Préfère les portes CUDA-Q natives (r1.ctrl, x.ctrl, swap.ctrl, etc.) à la transpilation à travers le framework source.
Garde la conversion de bit-order à la frontière du port : ordre d'allocation, liste de retour de mesure ou formatage final de clé de count.
Adapte la précision en virgule flottante quand tu compares les résultats CUDA-Q et source si les différences de fidélité importent (CUDA-Q par défaut fp32, Qiskit à fp64).
Accepte les flags source qui deviennent des no-ops dans CUDA-Q quand cela préserve le comportement compatible avec la source.

Quand consulter la référence

Consulte references/porting-reference.md quand tu as besoin de l'une des situations suivantes :

Table de traduction Qiskit-vers-CUDA-Q pour les portes.
Conventions de bit-ordering et count-key.
Implications de précision CUDA-Q fp32 vs Qiskit fp64.
Extraction de helpers pure-Python et validation de import-blocker.
Émetteurs de constructeurs récursifs ou patterns de gate-recorder.
Checklist détaillée de validation de port et références externes CUDA-Q.

Limitations

Les orientations ciblent les APIs Python CUDA-Q 0.14/0.15 en decorator-mode. Re-vérifie le comportement par rapport à la version CUDA-Q installée pour les features sensibles à la version.
Certaines constructions du kernel-language CUDA-Q sont contraintes par rapport au Python normal ; utilise la skill compagne cudaq-guide (/cudaq-guide author) pour les contraintes d'authorship CUDA-Q core et les patterns de kernel partagés.
CUDA-Q et les frameworks source diffèrent dans la précision par défaut et l'ordre d'affichage count-key. Les apparentes incompatibilités de fidélité ou de bitstring peuvent être des différences de convention.
Le comportement sur hardware-target, les backends disponibles et les options de target dépendent de l'installation CUDA-Q locale.
Cette skill ne garantit pas une performance équivalente ; elle se concentre sur les ports préservant la correction.

Dépannage

Utilise ce format quand tu diagnostiques des défaillances :

Erreur : ModuleNotFoundError: qiskit (ou un autre framework source) d'un path CUDA-Q. Cause : Le port importe toujours le framework source. Solution : Déplace les helpers purs dans un module sans framework et vérifie avec le pattern import-blocker dans la référence.
Erreur : La fidélité semble plausible mais les clés brutes sont inversées. Cause : L'ordonnancement count-key du framework source et de CUDA-Q diffère. Solution : Corrige l'allocation, l'ordre de la liste de retour ou le formatage à la frontière du port. N'altère pas l'algorithme.
Erreur : La fidélité d'un circuit profond diffère entre les frameworks. Cause : CUDA-Q et le framework source peuvent utiliser une précision en virgule flottante différente. Solution : Adapte la précision avant de comparer, puis réexécute le plus petit cas déterministe défaillant.
Erreur : Une opération multi-contrôlée fonctionne pour les petits contrôles mais échoue ou change silencieusement le comportement à plus grande arité. Cause : Le port utilisait un dispatcher d'arité fixe. Solution : Utilise les patterns de control-list CUDA-Q pour une arité arbitraire.
Erreur : La recherche de documentation MCP ou de repository échoue. Cause : Connecteur indisponible, obsolète ou défaillant transitoirement. Solution : Vérifie la liste des connecteurs/ressources, réessaye les défaillances transitoires une fois, puis reviens à la documentation locale/source ou à la documentation officielle CUDA-Q. Ne modifie pas le port basé sur des résultats MCP non vérifiés.
Erreur : Le comportement CUDA-Q entre en conflit avec la documentation lors du débogage. Cause : La version CUDA-Q installée peut différer de la documentation la plus récente. Solution : Vérifie cudaq.__version__, puis examine la documentation pertinente ou les modifications source entre la version installée et la dernière avant de modifier le port.

Références

Référence de portage détaillée
Skill compagne : cudaq-guide (/cudaq-guide author) pour les patterns d'authorship CUDA-Q, les contraintes du kernel-language, les APIs d'exécution et le flux de débogage.

cudaq-importing