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
- Read the source circuit construction and identify the exact algorithm,
qubit/register layout, measurement behavior, and any framework helpers.
- Preserve the high-level quantum algorithm. Do not replace mid-circuit
measurement, QPE structure, oracle definitions, or decomposition strategy
without explicit user permission.
- 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.
- Translate gates and subcircuits. For detailed gate mappings, ordering rules,
precision guidance, and helper-extraction patterns, read
references/porting-reference.md.
- Remove runtime source-framework dependencies from the CUDA-Q port. Extract
pure helpers into framework-free modules.
- Validate with small deterministic inputs before scaling. Compare raw count
keys and distributions, not just aggregate fidelity.
- 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.
Limitations
- Guidance targets CUDA-Q 0.14/0.15 decorator-mode Python APIs. Re-check
behavior against the installed CUDA-Q version for version-sensitive features.
- Some CUDA-Q kernel-language constructs are constrained compared with normal
Python; use the companion
cudaq-guide skill (/cudaq-guide author) for core
CUDA-Q authoring constraints and shared kernel patterns.
- CUDA-Q and source frameworks differ in default precision and count-key display
order. Apparent fidelity or bitstring mismatches may be convention
differences.
- Hardware-target behavior, available backends, and target options depend on
the local CUDA-Q installation.
- This skill does not guarantee equivalent performance; it focuses on
correctness-preserving ports.
Troubleshooting
Use this format when diagnosing failures:
Error: ModuleNotFoundError: qiskit (or another source framework) from a
CUDA-Q path.
Cause: The port still imports the source framework.
Solution: Move pure helpers into a framework-free module and verify with
the import-blocker pattern in the reference.
Error: Fidelity looks plausible but raw keys are reversed.
Cause: The source framework and CUDA-Q count-key ordering differ.
Solution: Fix allocation, return-list order, or formatting at the port
boundary. Do not alter the algorithm.
Error: Deep-circuit fidelity differs between frameworks.
Cause: CUDA-Q and the source framework may be using different
floating-point precision.
Solution: Match precision before comparing, then rerun the smallest
failing deterministic case.
Error: A multi-controlled operation works for small controls but fails or
silently changes behavior at higher arity.
Cause: The port used a fixed-arity dispatcher.
Solution: Use CUDA-Q control-list patterns for arbitrary arity.
Error: MCP documentation or repository lookup fails.
Cause: Connector unavailable, stale, or transiently failing.
Solution: Verify the connector/resource list, retry transient failures
once, then fall back to local docs/source or official CUDA-Q docs. Do not
change the port based on unverified MCP results.
Error: CUDA-Q behavior conflicts with documentation while debugging.
Cause: The installed CUDA-Q version may differ from the latest
documentation.
Solution: Check cudaq.__version__, then review relevant documentation or
source changes between the installed version and latest before changing the
port.
References
- Detailed porting reference
- Companion skill:
cudaq-guide (/cudaq-guide author) for CUDA-Q authoring
patterns, kernel-language constraints, execution APIs, and debugging workflow.
1---2name: "cudaq-importing"3title: "CUDA-Q Importing"4description: "Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity."5version: "1.0.2"6author: "CUDA-Q Team <cuda-quantum@nvidia.com>"7tags: [cuda-quantum, quantum-computing, importing, porting, migration, qiskit, kernels, nvidia]8tools: [Read, Glob, Grep]9license: "Apache-2.0"10compatibility: "Python 3.10+"11metadata:12 source: https://skillmd.com/skills/nvidia/cudaq-importing13 author: "CUDA-Q Team <cuda-quantum@nvidia.com>"14 short-description: "Port circuits from other frameworks into CUDA-Q"15 tags:16 - cuda-quantum17 - quantum-computing18 - importing19 - porting20 - migration21 - qiskit22 - nvidia23 languages:24 - python25 domain: "quantum"26---2728# CUDA-Q Importing2930## Purpose3132Use this skill to port quantum circuits from another framework into CUDA-Q33Python kernels. This includes Qiskit code and Qiskit-style circuit construction,34as well as other framework-driven circuit builders. The goal is a framework-free35CUDA-Q port that preserves the source quantum algorithm, matches source behavior36at small test sizes, and documents any unavoidable CUDA-Q limitations.3738For authoring new CUDA-Q kernels from scratch, and for CUDA-Q installation,39simulation targets, QPU access, and parallelization, use the `cudaq-guide`40skill (`/cudaq-guide author` for kernel authoring).4142## Prerequisites4344- Python 3.10+.45- CUDA-Q installed in the target environment. Check the runtime with:46 `python -c "import cudaq; print(getattr(cudaq, '__version__', 'unknown'))"`.47- Access to the source implementation and a way to run or inspect its expected48 behavior.49- To validate against the source framework (e.g. Qiskit/Aer), it must be50 installed in the validation environment only. The final CUDA-Q port itself51 must not require the source framework.52- When using CUDA-Q documentation or repository MCP connectors, verify the53 connector is available before relying on it; otherwise use local docs or the54 source tree.55- When debugging and the installed CUDA-Q version differs from the latest56 documentation, review relevant documentation or source changes before57 treating a behavior difference as a porting bug.5859## Workflow60611. Read the source circuit construction and identify the exact algorithm,62 qubit/register layout, measurement behavior, and any framework helpers.632. Preserve the high-level quantum algorithm. Do not replace mid-circuit64 measurement, QPE structure, oracle definitions, or decomposition strategy65 without explicit user permission.663. Select the CUDA-Q execution pattern:67 - Use `cudaq.sample` for final-measurement sampling.68 - Use `cudaq.run` when mid-circuit measurement values must be returned or69 used per shot.70 - Use runtime-argument kernels instead of generated per-size kernels unless71 CUDA-Q requires a fixed-length return shape.724. Translate gates and subcircuits. For detailed gate mappings, ordering rules,73 precision guidance, and helper-extraction patterns, read74 [references/porting-reference.md](references/porting-reference.md).755. Remove runtime source-framework dependencies from the CUDA-Q port. Extract76 pure helpers into framework-free modules.776. Validate with small deterministic inputs before scaling. Compare raw count78 keys and distributions, not just aggregate fidelity.797. Re-run any previously failing configurations after every fix.8081## Core Rules8283- Keep the source algorithm intact unless the user approves a change.84- Do not introduce fixed qubit caps, fixed control arities, or source-framework85 imports unless they are genuinely unavoidable and documented.86- Prefer native CUDA-Q gates (`r1.ctrl`, `x.ctrl`, `swap.ctrl`, etc.) over87 transpiling through the source framework.88- Keep bit-order conversion at the port boundary: allocation order,89 measurement return list, or final count-key formatting.90- Match floating-point precision when comparing CUDA-Q and source results if91 fidelity differences matter (CUDA-Q defaults to fp32, Qiskit to fp64).92- Accept source flags that become no-ops in CUDA-Q when doing so preserves93 source-compatible behavior.9495## When to Read the Reference9697Read [references/porting-reference.md](references/porting-reference.md) when98you need any of the following:99100- Qiskit-to-CUDA-Q gate translation table.101- Bit-ordering and count-key conventions.102- CUDA-Q fp32 vs Qiskit fp64 precision implications.103- Pure-Python helper extraction and import-blocker validation.104- Recursive-constructor emitters or gate-recorder patterns.105- Detailed port validation checklist and external CUDA-Q references.106107## Limitations108109- Guidance targets CUDA-Q 0.14/0.15 decorator-mode Python APIs. Re-check110 behavior against the installed CUDA-Q version for version-sensitive features.111- Some CUDA-Q kernel-language constructs are constrained compared with normal112 Python; use the companion `cudaq-guide` skill (`/cudaq-guide author`) for core113 CUDA-Q authoring constraints and shared kernel patterns.114- CUDA-Q and source frameworks differ in default precision and count-key display115 order. Apparent fidelity or bitstring mismatches may be convention116 differences.117- Hardware-target behavior, available backends, and target options depend on118 the local CUDA-Q installation.119- This skill does not guarantee equivalent performance; it focuses on120 correctness-preserving ports.121122## Troubleshooting123124Use this format when diagnosing failures:125126- **Error:** `ModuleNotFoundError: qiskit` (or another source framework) from a127 CUDA-Q path.128 **Cause:** The port still imports the source framework.129 **Solution:** Move pure helpers into a framework-free module and verify with130 the import-blocker pattern in the reference.131132- **Error:** Fidelity looks plausible but raw keys are reversed.133 **Cause:** The source framework and CUDA-Q count-key ordering differ.134 **Solution:** Fix allocation, return-list order, or formatting at the port135 boundary. Do not alter the algorithm.136137- **Error:** Deep-circuit fidelity differs between frameworks.138 **Cause:** CUDA-Q and the source framework may be using different139 floating-point precision.140 **Solution:** Match precision before comparing, then rerun the smallest141 failing deterministic case.142143- **Error:** A multi-controlled operation works for small controls but fails or144 silently changes behavior at higher arity.145 **Cause:** The port used a fixed-arity dispatcher.146 **Solution:** Use CUDA-Q control-list patterns for arbitrary arity.147148- **Error:** MCP documentation or repository lookup fails.149 **Cause:** Connector unavailable, stale, or transiently failing.150 **Solution:** Verify the connector/resource list, retry transient failures151 once, then fall back to local docs/source or official CUDA-Q docs. Do not152 change the port based on unverified MCP results.153154- **Error:** CUDA-Q behavior conflicts with documentation while debugging.155 **Cause:** The installed CUDA-Q version may differ from the latest156 documentation.157 **Solution:** Check `cudaq.__version__`, then review relevant documentation or158 source changes between the installed version and latest before changing the159 port.160161## References162163- [Detailed porting reference](references/porting-reference.md)164- Companion skill: `cudaq-guide` (`/cudaq-guide author`) for CUDA-Q authoring165 patterns, kernel-language constraints, execution APIs, and debugging workflow.