cudaq-importing
Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity.
Install
npx skills add https://github.com/NVIDIA/skills/tree/main/skills/cudaq-importing
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nvidia-skills@llmmart
git clone https://github.com/NVIDIA/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nvidia/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.samplefor final-measurement sampling. - Use
cudaq.runwhen 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.
- Use
- 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-guideskill (/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.
Files (skills)
-
evals
-
evals.json 6.4 KB
Loading…
-
-
references
-
porting-reference.md 10.9 KB
Loading…
-
-
BENCHMARK.md 7.6 KB
Loading… -
skill-card.md 3.9 KB
Loading… -
SKILL.md 7.3 KB
--- name: "cudaq-importing" title: "CUDA-Q Importing" description: "Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity." version: "1.0.2" author: "CUDA-Q Team <cuda-quantum@nvidia.com>" tags: [cuda-quantum, quantum-computing, importing, porting, migration, qiskit, kernels, nvidia] tools: [Read, Glob, Grep] license: "Apache-2.0" compatibility: "Python 3.10+" metadata: author: "CUDA-Q Team <cuda-quantum@nvidia.com>" short-description: "Port circuits from other frameworks into CUDA-Q" tags: - cuda-quantum - quantum-computing - importing - porting - migration - qiskit - nvidia languages: - python domain: "quantum" --- # 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](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](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](references/porting-reference.md) - Companion skill: `cudaq-guide` (`/cudaq-guide author`) for CUDA-Q authoring patterns, kernel-language constraints, execution APIs, and debugging workflow. -
skill.oms.sig 4.7 KB · in bundle
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.