Cudaq Importing
NVIDIAOfficialCreated by CUDA-Q TeamDistributed by NVIDIA
- Skill
- Workflow
- Software development
- Apache-2.0
- Medium risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The CUDA-Q Importing skill provides a systematic approach to migrating quantum circuits from external frameworks into the CUDA-Q Python environment. It emphasizes preserving the original quantum algorithm, ensuring validation fidelity, and removing runtime dependencies on source frameworks. The skill includes specific guidance on gate translation, handling floating-point precision differences, and managing bit-ordering conventions to ensure the ported code behaves identically to the source implementation.
What it does
- Maps source framework gates to native CUDA-Q decorator-mode equivalents.
- Provides patterns for decoupling pure-Python helpers from source-framework dependencies.
- Defines execution patterns for sampling and mid-circuit measurement handling.
- Offers troubleshooting steps for common porting issues like bit-order mismatches and precision differences.
- Ensures algorithmic structure is preserved during the migration process.
- Guides the validation of ported kernels against deterministic source inputs.
When to use it
- When you need to migrate an existing quantum algorithm from Qiskit or similar frameworks to CUDA-Q.
- When you need to ensure a port maintains the exact behavior and fidelity of the original implementation.
- When you are refactoring code to remove dependencies on external quantum frameworks.
- When you encounter discrepancies in fidelity or count-key results between frameworks.
Advantages
- Maintains high-level algorithmic integrity throughout the porting process.
- Reduces runtime overhead by eliminating unnecessary source-framework dependencies.
- Provides clear gate-mapping references to simplify translation.
- Addresses common pitfalls like floating-point precision and bit-ordering conventions.
- Supports scalable kernel design using runtime-argument patterns.
Usage examples
- “Port this Qiskit circuit to a CUDA-Q kernel while preserving the oracle definition.”
- The agent will analyze the Qiskit circuit, map the gates to CUDA-Q equivalents, and provide a framework-free Python kernel that maintains the original oracle logic.
- “My ported CUDA-Q circuit shows different measurement results than the original Qiskit version. How do I fix this?”
- The agent will guide you through checking bit-ordering, floating-point precision settings, and measurement return formats to align the CUDA-Q output with the source.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/cudaq-importing/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip cudaq-importing.zip -d .agents/skills
Documentation by CUDA-Q Team
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.
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
Companion skill:
cudaq-guide(/cudaq-guide author) for CUDA-Q authoring patterns, kernel-language constraints, execution APIs, and debugging workflow.
Files
- ATTRIBUTION.mdAdded by AutoGineer908 B
- BENCHMARK.md7.6 KiB
- LICENSELicence file added by AutoGineer11.2 KiB
- SKILL.md7.3 KiB
- evals/evals.json6.4 KiB
- references/porting-reference.md10.9 KiB
- skill-card.md3.9 KiB
- skill.oms.sig4.7 KiB
evals/evals.json
{
"skill_name": "cudaq-importing",
"evals": [
{
"id": "cudaq-importing-001",
"prompt": "Using the cudaq-importing skill, help me port this Qiskit circuit to CUDA-Q:\n\n```python\nfrom qiskit import QuantumCircuit\nfrom qiskit_aer import AerSimulator\n\nqc = QuantumCircuit(3, 3)\nqc.x(0)\nqc.h(1)\nqc.cx(1, 2)\nqc.measure([0, 1, 2], [0, 1, 2])\n\nsim = AerSimulator()\nresult = sim.run(qc, shots=1000).result()\nprint(result.get_counts())\n```\n\nI want the CUDA-Q version to produce equivalent count keys so I can validate the port. This circuit should make bit ordering visible: Qiskit should report counts on keys like `001` and `111`, while raw CUDA-Q measurement order would include `100` and `111` unless the keys are remapped.",
"expected_output": "The agent used cudaq-importing to produce a complete CUDA-Q port using @cudaq.kernel decorator mode, correctly translating x, h, and cx gates, addressing bit-ordering conventions so raw CUDA-Q key `100` is remapped to Qiskit-style key `001`, and ensuring no Qiskit runtime dependency.",
"assertions": [
"The agent read the cudaq-importing SKILL.md to reference the gate-translation table and bit-ordering conventions",
"The agent produced a @cudaq.kernel decorated function with cudaq.qvector and equivalent x/h/cx gate calls",
"The agent explained or handled the bit-ordering difference between Qiskit and CUDA-Q count keys, including that raw CUDA-Q key `100` maps to Qiskit-style key `001` for this circuit",
"The agent ensured the ported code has no import or runtime dependency on qiskit",
"The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
],
"expected_skill": "cudaq-importing",
"expected_script": null
},
{
"id": "cudaq-importing-002",
"prompt": "I have a Qiskit implementation of a 4-qubit Grover's algorithm with a custom oracle. I need to rewrite it in CUDA-Q so it runs on NVIDIA GPUs without needing Qiskit installed. The Qiskit version uses `.inverse()` for the diffuser and multi-controlled Z gates. How should I approach this migration, especially handling the `.inverse()` pattern and making sure the count results match between frameworks?",
"expected_output": "The agent used cudaq-importing to explain the porting approach for Grover's algorithm including handling .inverse() via the hand-rolled-inverse or gate-recorder pattern, translating multi-controlled gates using runtime-arity encoding, addressing fp32 vs fp64 precision differences, and validating via raw count-key comparison.",
"assertions": [
"The agent referenced the framework-decoupling patterns for handling .inverse() constructors (gate-recorder class or hand-rolled inverse)",
"The agent addressed multi-controlled gate translation using the runtime-arity list-comprehension pattern rather than fixed-arity dispatchers",
"The agent discussed count-key validation and floating-point precision differences (CUDA-Q fp32 vs Qiskit fp64)",
"The agent emphasized preserving the source algorithm without changing the quantum logic",
"The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
],
"expected_skill": "cudaq-importing",
"expected_script": null
},
{
"id": "cudaq-importing-003",
"prompt": "Using the cudaq-importing skill, help me port this small parameterized Qiskit circuit to CUDA-Q:\n\n```python\nimport math\nfrom qiskit import QuantumCircuit\nfrom qiskit_aer import AerSimulator\n\ntheta = math.pi / 3\nphi = math.pi / 5\n\nqc = QuantumCircuit(4, 4)\nqc.x(0)\nqc.ry(theta, 1)\nqc.rz(phi, 1)\nqc.cx(1, 2)\nqc.h(3)\nqc.measure([0, 1, 2, 3], [0, 1, 2, 3])\n\nsim = AerSimulator()\nresult = sim.run(qc, shots=1000).result()\nprint(result.get_counts())\n```\n\nKeep `theta` and `phi` as runtime arguments to the CUDA-Q kernel, and make the CUDA-Q counts comparable to Qiskit's `get_counts()` keys.",
"expected_output": "The agent used cudaq-importing to produce a complete CUDA-Q port using @cudaq.kernel decorator mode with runtime float arguments for theta and phi, correctly translating x, ry, rz, cx, and h gates, handling Qiskit-vs-CUDA-Q count-key ordering, and ensuring no Qiskit runtime dependency.",
"assertions": [
"The agent read the cudaq-importing SKILL.md to reference the gate-translation table and bit-ordering conventions",
"The agent produced a @cudaq.kernel decorated function with runtime float arguments for theta and phi rather than hardcoding the angles inside the kernel",
"The agent translated x, ry, rz, cx, and h to their CUDA-Q decorator-mode equivalents",
"The agent explained or handled the bit-ordering difference between Qiskit and CUDA-Q count keys for measure([0, 1, 2, 3], [0, 1, 2, 3])",
"The agent ensured the ported code has no import or runtime dependency on qiskit",
"The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
],
"expected_skill": "cudaq-importing",
"expected_script": null
},
{
"id": "cudaq-importing-004",
"prompt": "How do I set up a multi-node MPI simulation in CUDA-Q to distribute a 35-qubit statevector across multiple GPUs? I'm not porting from another framework, I just want to understand the CUDA-Q distributed execution model and which target/backend flags to use.",
"expected_output": "The agent recognized this as a pure CUDA-Q distributed simulation question unrelated to porting from Qiskit, and either used the cudaq-guide skill or general CUDA-Q knowledge to address multi-GPU statevector distribution without invoking the cudaq-importing skill.",
"assertions": [
"The agent did not invoke or reference the cudaq-importing skill since no framework porting is involved",
"The agent addressed the multi-node/multi-GPU distributed simulation topic using general CUDA-Q knowledge or the cudaq-guide skill",
"The agent discussed target selection or backend configuration relevant to distributed statevector simulation",
"The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
],
"expected_skill": null,
"expected_script": null
}
]
}
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Python
The author says: Python 3.10+
Security
What our scanner noticed· Medium risk
- Large base64-encoded blobs
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- CUDA-Q Team
- Publisher
- NVIDIA (Official)
- Distributed by
- NVIDIA
- Source
- NVIDIA/skills · skills/cudaq-importing · commit fce3cca
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE-APACHE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by CUDA-Q Team or NVIDIA.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cudaq-importing.zip