Cudaq Importing

CUDA-Q Importing

Purpose

Use this skill to port quantum circuits from another framework into CUDA-Q Python kernels. This includes Qiskit code and Qiskit-style circuit construction, as well as other framework-driven circuit builders. 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.

For authoring new CUDA-Q kernels from scratch, and for CUDA-Q installation, simulation targets, QPU access, and parallelization, use the cudaq-guide skill (/cudaq-guide author for kernel authoring).

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.
• To validate against the source framework (e.g. Qiskit/Aer), it must be installed in the validation environment only. The final CUDA-Q port itself must not require the source framework.
• 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, x.ctrl, swap.ctrl, etc.) over transpiling through the source framework.
• Keep bit-order conversion at the port boundary: allocation order, measurement return list, or final count-key formatting.
• Match floating-point precision when comparing CUDA-Q and source results if fidelity differences matter (CUDA-Q defaults to fp32, Qiskit to fp64).
• Accept source flags that become no-ops in CUDA-Q when doing so preserves source-compatible behavior.

When to Read the Reference

Read references/porting-reference.md when you need any of the following:

• Qiskit-to-CUDA-Q gate translation table.
• Bit-ordering and count-key conventions.
• CUDA-Q fp32 vs Qiskit fp64 precision implications.
• Pure-Python helper extraction and import-blocker validation.
• Recursive-constructor emitters or gate-recorder patterns.
• Detailed port validation checklist and external CUDA-Q references.