Generated banner for Cudaq Importing
Generated logo for Cudaq Importing

Cudaq Importing

NVIDIAOfficialCreated by CUDA-Q TeamDistributed by NVIDIA

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • Medium risk

From the author

Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity.
— the description by CUDA-Q Team

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/cudaq-importing/download
  2. Unzip 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

  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.

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.

Files

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