qiskit-to-cudaq

name	qiskit-to-cudaq
title	Qiskit to CUDA-Q
description	Use when porting Qiskit Python circuits to CUDA-Q kernels while preserving algorithms and validation fidelity.
version	1.0.0
author	CUDA-Q Team <[e-mail]>
tags	["cuda-quantum","quantum-computing","qiskit","porting","migration","kernels","nvidia"]
tools	["Read","Glob","Grep"]
license	Apache-2.0
compatibility	Python 3.10+
metadata	{"author":"CUDA-Q Team <[e-mail]>","short-description":"Port Qiskit circuits to CUDA-Q","tags":["cuda-quantum","quantum-computing","qiskit","porting","migration","nvidia"],"languages":["python"],"domain":"quantum"}

Qiskit to CUDA-Q

Purpose

Use this skill to port Qiskit Python code, or code with Qiskit-style circuit construction, to CUDA-Q Python kernels. The goal is a framework-free CUDA-Q port that preserves the source quantum algorithm, matches source behavior at small test sizes, and documents any unavoidable CUDA-Q limitations.

Prerequisites

• Python 3.10+.
• CUDA-Q installed in the target environment. Check the runtime with: python -c "import cudaq; print(getattr(cudaq, '__version__', 'unknown'))".
• Access to the source implementation and a way to run or inspect its expected behavior.
• For validation against Qiskit, Qiskit/Aer must be installed in the validation environment. The final CUDA-Q port itself must not require Qiskit.
• When using CUDA-Q documentation or repository MCP connectors, verify the connector is available before relying on it; otherwise use local docs or the source tree.
• When debugging and the installed CUDA-Q version differs from the latest documentation, review relevant documentation or source changes before treating a behavior difference as a porting bug.

Workflow

1. Read the source circuit construction and identify the exact algorithm, qubit/register layout, measurement behavior, and any framework helpers.
2. Preserve the high-level quantum algorithm. Do not replace mid-circuit measurement, QPE structure, oracle definitions, or decomposition strategy without explicit user permission.
3. Select the CUDA-Q execution pattern:
   • Use cudaq.sample for final-measurement sampling.
   • Use cudaq.run when mid-circuit measurement values must be returned or used per shot.
   • Use runtime-argument kernels instead of generated per-size kernels unless CUDA-Q requires a fixed-length return shape.
4. Translate gates and subcircuits. For detailed gate mappings, ordering rules, precision guidance, and helper-extraction patterns, read references/porting-reference.md.
5. Remove runtime source-framework dependencies from the CUDA-Q port. Extract pure helpers into framework-free modules.
6. Validate with small deterministic inputs before scaling. Compare raw count keys and distributions, not just aggregate fidelity.
7. Re-run any previously failing configurations after every fix.

Core Rules

• Keep the source algorithm intact unless the user approves a change.
• Do not introduce fixed qubit caps, fixed control arities, or source-framework imports unless they are genuinely unavoidable and documented.
• Prefer native CUDA-Q gates (r1.ctrl, , , etc.) over transpiling through Qiskit.