Claude Cursor Skill

cudaq-importing

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download nvidia-skills-skills_cudaq-importing-d8519c5.zip · 17 KB
nvidia/skills 3445 416 forks Apache-2.0 Updated 3d ago
Part of nvidia/skills — 26 skills

Install

skills CLI npx skills add https://github.com/NVIDIA/skills/tree/main/skills/cudaq-importing
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nvidia-skills@llmmart
Git 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

  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 (skills)
  • evals
    • evals.json 6.4 KB 
      {
  "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
    }
  ]
}
  • references
    • porting-reference.md 10.9 KB 
      # Qiskit to CUDA-Q Porting Reference

Use this reference when the top-level `SKILL.md` says detailed gate, ordering,
precision, or framework-decoupling guidance is needed.

## Porting Disciplines

Preserve the source algorithm when porting.

- Do not change the high-level quantum algorithm without explicit permission.
  Examples: removing mid-circuit measurements, replacing iterative QPE with a
  coherent unroll, or changing oracle decompositions.
- Do not introduce restrictions that the source implementation did not have.
- If a CUDA-Q language constraint genuinely requires a cap or unsupported path,
  raise `NotImplementedError` with a clear reason. Never silently drop gates.
- A CUDA-Q port must not depend on Qiskit, Qiskit Aer, Qiskit IBM Runtime, or
  another source framework at runtime.

Avoid these failure modes:

- Hardcoded register sizes such as `cudaq.qvector(10)` when
  `cudaq.qvector(num_qubits)` works.
- Fixed-arity dispatchers that silently ignore controls beyond a hand-coded
  limit. Use runtime-arity control lists.
- Rejecting source flags that are no-ops in CUDA-Q, such as a
  `parameterized=True` flag when the CUDA-Q kernel already accepts runtime
  parameters.
- Per-shape kernel factories when a runtime integer parameter is enough.

Framework-free ports:

- Do not `import qiskit` from CUDA-Q modules.
- Do not import a Qiskit module just to reuse pure-Python helpers.
- Do not build a `QuantumCircuit` and inspect `qc.data` at runtime.
- Move pure-Python analyzers, generators, and post-processing helpers into a
  sibling module using only stdlib and NumPy.

## Gate Translation Table

| Qiskit | CUDA-Q decorator-mode equivalent | Notes |
|---|---|---|
| `qc.h(q)`, `x`, `y`, `z`, `s`, `t`, `sdg`, `tdg` | `h(q)`, `x(q)`, `y(q)`, `z(q)`, `s(q)`, `t(q)`, `s.adj(q)`, `t.adj(q)` | Direct |
| `qc.rx/ry/rz(theta, q)` | `rx(theta, q)`, `ry(theta, q)`, `rz(theta, q)` | Direct |
| `qc.p(theta, q)` | `r1(theta, q)` | Both are `diag(1, exp(i theta))` |
| `qc.cx(c, t)` | `cx(c, t)` or `x.ctrl(c, t)` | Direct |
| `qc.cy/cz(c, t)` | `y.ctrl(c, t)`, `z.ctrl(c, t)` | Direct |
| `qc.ch(c, t)` | `h.ctrl(c, t)` | Direct |
| `qc.crx/cry/crz(theta, c, t)` | `rx.ctrl(theta, c, t)`, `ry.ctrl(...)`, `rz.ctrl(...)` | Control and target order matters |
| `qc.cp(theta, c, t)` | `r1.ctrl(theta, c, t)` | Controlled phase; symmetric mathematically |
| `qc.u/UGate/u3(theta, phi, lam, q)` | `u3(theta, phi, lam, q)` when available; otherwise decompose to rotations | Check the installed CUDA-Q version |
| `qc.cu/CUGate/cu3(theta, phi, lam, gamma, c, t)` | `u3.ctrl(theta, phi, lam, c, t)` when available, with global-phase handling if needed; otherwise decompose | Do not assume a separate `cu3` helper exists |
| `qc.rzz(theta, i, j)` | `cx(q[i], q[j]); rz(theta, q[j]); cx(q[i], q[j])` | Decomposition works across 0.14/0.15; prefer native `rzz` only if available in the installed API |
| `qc.rxx(theta, i, j)` | H on both qubits, RZZ decomposition, H on both qubits | |
| `qc.ryy(theta, i, j)` | Sdg and H basis changes around RZZ decomposition | |
| `qc.mcx([c...], t)` | `x.ctrl([c...], t)` | Arbitrary arity |
| `qc.mcry(theta, [c...], t)` | `ry.ctrl(theta, [c...], t)` | Arbitrary arity |
| `qc.mcp(theta, [c...], t)` | `r1.ctrl(theta, [c...], t)` | Preferred for many-control phase |
| `MCXGate(..., ctrl_state="010")` | X-wrap open controls before and after the controlled operation | No Qiskit-style `ctrl_state` argument; `~control` syntax may be available in the installed CUDA-Q version |
| `qc.swap(a, b)` | `swap(a, b)` | Direct |
| `qc.cswap(c, a, b)` | `swap.ctrl(c, a, b)` | Also accepts list/variadic controls |
| Final `qc.measure(q, c)` | `mz(qubits)` and `cudaq.sample` | See bit-ordering guidance |
| Mid-circuit `qc.measure(q, c)` | `b = mz(q)` plus `cudaq.run` and typed return | Use when the measurement result drives control flow or must be returned; newer CUDA-Q documents `mz` captures as measurement handles that discriminate in boolean contexts or typed returns |
| `qc.reset(q)` | `reset(q)` | Unconditional reset |
| `qc.append(U, qubits)` | Implement `U` as a CUDA-Q kernel/function and call it | |
| `qc.inverse()` | `cudaq.adjoint(K, *args)` at top level | Hand-roll inverse if `K` is used inside `cudaq.control` |
| `qc.control(n)` | `cudaq.control(K, controls, *args)` | `K` must not contain `cudaq.adjoint` |
| `qc.compose(other, qubits)` | Direct function call with qview slices or explicit qubits | |
| Qiskit `ParameterVector` / binds | Pass parameter values as kernel arguments | No symbolic-vs-bound distinction |

For asymmetric controlled rotations, keep Qiskit's control-target orientation
exactly. Swapping arguments gives a different unitary.

## Bit Ordering and Count Keys

CUDA-Q and Qiskit stringify measurement results differently. Keep ordering
changes at the port boundary: allocation convention, measurement return list,
or final count-key formatting.

| API | Convention |
|---|---|
| `cudaq.sample` with `mz(qview)` | Keys follow qview order; `qview[0]` is leftmost |
| Multiple CUDA-Q `qvector` allocations | Keys follow allocation order, not `mz` call order |
| `cudaq.sample(..., explicit_measurements=True)` | Keys follow measurement-call order |
| `cudaq.run` returning `List[bool]` | Join return-list element 0 as leftmost |
| `cudaq.get_state(K)[i]` | `format(i, f"0{N}b")` matches CUDA-Q sample key order for the same kernel |
| Qiskit `get_counts` | Classical bit `c[0]` is displayed rightmost |

Mapping rules:

- To match Qiskit keys like `{prefix}{c[N-1]}...{c[0]}`, build a CUDA-Q
  return list in that same displayed order.
- To match a Qiskit register without a prefix, allocate CUDA-Q qubits so
  `qubits[N - 1 - q]` corresponds to Qiskit's `qr[q]`.
- If a Qiskit oracle decomposes an integer and reverses its bit list with
  `[::-1]`, check whether the CUDA-Q port should remove that reverse because
  CUDA-Q `register[0]` appears leftmost.
- CUDA-Q does not add spaces between classical registers in count keys.

When keys are wrong but counts are otherwise plausible, fix ordering at the
boundary, not by changing the algorithm. Use deterministic 2- or 3-qubit probes
and compare exact raw keys before relying on aggregate fidelity.

## Floating-Point Precision

CUDA-Q and Qiskit commonly default to different statevector precision:

| Framework | Typical backend | Default amplitude precision | Bytes per complex amplitude |
|---|---|---:|---:|
| CUDA-Q | `nvidia` / cuStateVec | fp32 | 8 |
| Qiskit | Aer statevector/GPU | fp64 | 16 |

Implications:

- Deep circuits or many small rotations can diverge between fp32 and fp64.
- Transpiling through small bases can add rotations and increase rounding drift.
- For cross-framework fidelity comparisons, use matching precision unless the
  task is explicitly default-vs-default comparison.

To match precision, adjust one side or the other (not both):

```python
# Option A: raise CUDA-Q to fp64 to match Aer's default
cudaq.set_target("nvidia", option="fp64")

# Option B: lower Aer to fp32 to match CUDA-Q's default
sim = AerSimulator(device="GPU", precision="single")
```

CUDA-Q fp64 roughly doubles statevector memory, reducing maximum GPU width.

## Framework-Decoupling Patterns

### Recursive Constructor to Flat Emitter

CUDA-Q kernels cannot recurse. If a Qiskit implementation recursively builds
subcircuits, port the recursion to a pure-Python emitter that produces arrays
consumed by a non-recursive kernel.

```python
def ucr_sequence_pure(n, theta):
    ry_angles, ctrl_indices = [], []

    def recurse(qubit_idx_list, theta_slice):
        if len(qubit_idx_list) == 1:
            ry_angles.append(float(theta_slice[0]))
            ctrl_indices.append(qubit_idx_list[0])
            ry_angles.append(float(theta_slice[1]))
        else:
            half = len(theta_slice) // 2
            recurse(qubit_idx_list[1:], theta_slice[:half])
            ctrl_indices.append(qubit_idx_list[0])
            recurse(qubit_idx_list[1:], theta_slice[half:])

    recurse(list(range(n)), list(theta))
    ctrl_indices.append(0)
    return ry_angles, ctrl_indices
```

If source code uses `sympy.combinatorics.GrayCode`, replace it with
`gray(i) = i ^ (i >> 1)` when possible.

### Source-Framework Import Blocker

Use this verification pattern after extracting pure helpers:

```python
import sys, importlib.abc

class _BlockSourceFramework(importlib.abc.MetaPathFinder):
    BLOCKED = ("qiskit", "qiskit_aer", "qiskit_ibm_runtime", "sympy")
    def find_spec(self, name, path, target=None):
        for blocked in self.BLOCKED:
            if name == blocked or name.startswith(blocked + "."):
                raise ModuleNotFoundError(f"refusing to import {name}")
        return None

sys.meta_path.insert(0, _BlockSourceFramework())
```

Then import and run the CUDA-Q port at a small representative configuration.

### Gate-Recorder Class

For deeply nested Qiskit constructors with `.inverse()` and `.control(k)`, use
a Python-side recorder whose methods mirror the source constructors and append
parallel arrays for a CUDA-Q kernel walker.

Default op-kind menu for modular-arithmetic-style circuits:

```text
1 = h
2 = x
3 = cx
4 = swap.ctrl
5 = r1(angle, t)
6 = r1.ctrl(angle, c, t)
7 = r1.ctrl(angle, c1, c2, t)
8 = rz.ctrl(angle, c, t)
```

For inverse calls, build a forward sub-sequence into a temporary recorder, then
append records in reverse order while negating rotation angles. Self-inverse
gates such as H, X, CX, and CSWAP keep angle 0.

Native-gate dispatch avoids per-circuit transpile cost and precision loss from
unnecessary transpilation. When `u3` / controlled `u3` exists in the installed
CUDA-Q API, emit it directly; otherwise decompose through supported rotations,
`cx`, and `swap`.

## Port Validation Gate

For every port:

1. Run the source implementation for the same deterministic inputs.
2. Run the CUDA-Q implementation with the same inputs.
3. Compare raw count keys, not only fidelity.
4. Test at least one small, nominal, and larger configuration when feasible.
5. Use stochastic tolerance only when shot noise is expected to dominate.
6. Re-run every previously failing configuration after changes.

When installed CUDA-Q behavior differs from the latest documentation while
debugging, review relevant documentation or source changes between the
installed version and latest before changing the port.

When stuck, copy subcircuit conventions from the exact source module being
ported. IQFT direction, qubit order, and gate flavor can differ across
implementations with similar names.

## External References

- CUDA-Q latest documentation: <https://nvidia.github.io/cuda-quantum/latest/>
- CUDA-Q examples in the local/source tree: `docs/sphinx/examples/python`
- CUDA-Q Academic: <https://github.com/NVIDIA/cuda-q-academic>
- CUDA-Q tests: `python/tests/kernel/test_kernel_features.py` and
  `python/tests/kernel/test_measure_handle.py` when present
- Companion skill: `cudaq-guide` (`/cudaq-guide author`) for execution API
  selection, kernel-language constraints, shared kernel patterns, resource
  metrics, and debugging workflow.
  • BENCHMARK.md 7.6 KB 
    # Skill Benchmark: cudaq-importing

> ✅ **Overall verdict: PASS — Recommended for publication**

## Publication Recommendation

Recommended for publication based on the completed evaluation evidence in this report.

## Evaluation Metadata

- Skill: `cudaq-importing`
- Evaluation date: 2026-09-11
- Evaluator version: `1.5.6`
- Agents: Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`), Codex (`openai/openai/gpt-5.5`)
- Tasks: 4 evaluation tasks (3 positive, 1 negative)
- Dataset digest: `sha256:85489ea0e566f515affb2b77d430f181d4180dffc638531af9c99f85f899a055` (skill-evaluator-dataset-snapshot/1)
- Attempts per task: 3
- Environment: `k8s-sandbox`
- Tier 2 evidence: required for publication
- Tier 3 evidence: required for publication

Each task attempt ran in its own isolated sandbox pod.

## What This Report Answers

The three-tier evaluation checks whether the skill:

- is safe to use;
- produces correct answers;
- is discovered and activated when needed;
- helps the agent complete the user's goal and expected workflow; and
- avoids wasted skill and tool usage.

## Results at a Glance

| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) |
|---|---:|---:|
| Overall | 91.9% — baseline ran, but no comparable score was available; uplift unavailable | 94.9% — baseline ran, but no comparable score was available; uplift unavailable |
| Security | 100.0% → 100.0% (±0.0 points) | 100.0% → 100.0% (±0.0 points) |
| Correctness | 90.0% → 100.0% (+10.0 points) | 90.0% → 100.0% (+10.0 points) |
| Discoverability | 93.3% — baseline ran, but no comparable score was available; uplift unavailable | 95.0% — baseline ran, but no comparable score was available; uplift unavailable |
| Effectiveness | 79.2% → 89.8% (+10.6 points) | 76.7% → 93.1% (+16.4 points) |
| Efficiency | 76.3% — baseline ran, but no comparable score was available; uplift unavailable | 86.6% — baseline ran, but no comparable score was available; uplift unavailable |

**How to read this table:** baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.

Example: `47.0% → 92.0% (+45.0 points)` means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.

A partial dimension was calculated from only the available configured signals; review the detailed report before relying on it.

## Token Usage

Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.

| Agent | Dataset case | With skill | Without skill | Delta | Change | Coverage |
|---|---|---:|---:|---:|---:|---|
| claude-code | All cases | 1,549,818 | 486,841 | +1,062,977 | +218.34% | skill 4/4; base 4/4 |
| claude-code | cudaq-importing-001 | 676,591 | 159,112 | +517,479 | +325.23% | skill 1/1; base 1/1 |
| claude-code | cudaq-importing-002 | 183,676 | 69,436 | +114,240 | +164.53% | skill 1/1; base 1/1 |
| claude-code | cudaq-importing-003 | 655,970 | 224,089 | +431,881 | +192.73% | skill 1/1; base 1/1 |
| claude-code | cudaq-importing-004 | 33,581 | 34,204 | -623 | -1.82% | skill 1/1; base 1/1 |
| codex | All cases | 308,702 | 117,968 | +190,734 | +161.68% | skill 4/4; base 4/4 |
| codex | cudaq-importing-001 | 79,475 | 14,241 | +65,234 | +458.07% | skill 1/1; base 1/1 |
| codex | cudaq-importing-002 | 105,600 | 33,611 | +71,989 | +214.18% | skill 1/1; base 1/1 |
| codex | cudaq-importing-003 | 80,533 | 33,761 | +46,772 | +138.54% | skill 1/1; base 1/1 |
| codex | cudaq-importing-004 | 43,094 | 36,355 | +6,739 | +18.54% | skill 1/1; base 1/1 |
| ALL AGENTS | Dataset aggregate | 1,858,520 | 604,809 | +1,253,711 | +207.29% | skill 8/8; base 8/8 |

Prompt tokens include cached reads, so total tokens are `prompt + completion` (cached is not added twice). The Efficiency score uses `(prompt - cached) + completion`. N/A means the relevant trajectory counters were not available; coverage is never estimated.

## Tier Status

| Tier | Purpose | Status | Evidence |
|---|---|---|---|
| Tier 1 | Static validation | **PASSED WITH OBSERVATIONS** | 11 validator(s); 7 finding(s) |
| Tier 2 | Semantic deduplication | **PASSED** | 2 validator(s); 0 finding(s) |
| Tier 3 | Live agent evaluation | **PASS** | 2 agent(s); 4 task(s) |

## Findings and Observations

<details>
<summary>Show detailed findings and successful checks</summary>

- **MEDIUM** SCHEMA/frontmatter_field_placement: Root field 'author' is ignored; use 'metadata.author' (`skills/cudaq-importing/SKILL.md`)
- **MEDIUM** SCHEMA/frontmatter_field_placement: Root field 'tags' is ignored; use 'metadata.tags' (`skills/cudaq-importing/SKILL.md`)
- **MEDIUM** SCHEMA/frontmatter_field_placement: Root field 'version' is ignored; use 'metadata.version' (`skills/cudaq-importing/SKILL.md`)
- **MEDIUM** SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/cudaq-importing/SKILL.md`)
- **MEDIUM** SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/cudaq-importing/SKILL.md`)
- 2 additional finding(s) are available in the full evaluation artifacts.

</details>

## Scoring Methodology

<details>
<summary>Show dimension definitions, source signals, and thresholds</summary>

| Dimension | Question | Scored signals |
|---|---|---|
| Security | Is it safe to use? | `security` (100%) |
| Correctness | Is the answer correct? | `accuracy` (100%) |
| Discoverability | Was the right skill loaded when needed? | `skill_execution` (100%) |
| Effectiveness | Did the skill help complete the task? | `goal_accuracy` (50%) + `behavior_check` (50%) |
| Efficiency | Did it avoid wasted tool calls and token usage? | `skill_efficiency` (50%) + `token_efficiency` (50%) |

- Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
- Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
- Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
- The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
- Effectiveness is the equal-weight mean of goal completion (`goal_accuracy`) and expected workflow adherence (`behavior_check`).
- Efficiency is 50% tool-call productivity (the backward-compatible `skill_efficiency` wire id) and 50% `token_efficiency`. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.

Signals present in this run:

- `security` (Security): unsafe operations, secret leakage, and unauthorized access.
- `skill_execution` (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.
- `skill_efficiency` (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).
- `accuracy` (Accuracy): final-answer correctness against the reference answer.
- `goal_accuracy` (Goal Accuracy): whether the user's goal was achieved.
- `behavior_check` (Behavior Check): whether the expected workflow behavior was followed.
- `token_efficiency` (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).

</details>

## Freshness

Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.
  • skill-card.md 3.9 KB 
    ## Description: <br>
Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity. <br>

This skill is ready for commercial/non-commercial use. <br>

## Owner
NVIDIA <br>

### License/Terms of Use: <br>
Apache-2.0 <br>
## Use Case: <br>
Developers and engineers use this skill to port quantum circuits from other frameworks (e.g., Qiskit) into CUDA-Q Python kernels while preserving algorithm correctness and validation fidelity. <br>

### Deployment Geography for Use: <br>
Global <br>

## Requirements / Dependencies: <br>
**Requires API Key or External Credential:** [Not Specified] <br>
**Credential Type(s):** [None identified] <br>

Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate. <br>

## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>

## Reference(s): <br>
- [Qiskit to CUDA-Q Porting Reference](references/porting-reference.md) <br>


## Skill Output: <br>
**Output Type(s):** [Code, Configuration instructions] <br>
**Output Format:** [Markdown with inline Python code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>

## Evaluation Agents Used: <br>
- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) <br>
- Codex (`openai/openai/gpt-5.5`) <br>



## Evaluation Tasks: <br>
4 evaluation tasks (3 positive, 1 negative), 3 attempts each, in isolated k8s-sandbox pods. <br>

## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Whether the skill is safe to use: checks for unsafe operations, secret leakage, and unauthorized access. <br>
- Correctness: Whether the final answer is correct against the reference answer. <br>
- Discoverability: Whether the expected skill was selected, decoys were avoided, and the workflow executed. <br>
- Effectiveness: Whether the skill helped complete the user's goal (50% goal accuracy + 50% expected workflow adherence). <br>
- Efficiency: Tool-call productivity and token efficiency (50% each). <br>

Underlying evaluation signals used in this run: <br>
- `security`: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
- `skill_execution`: Whether the expected skill was selected and the workflow executed. <br>
- `skill_efficiency`: Tool-call productivity (routing scored under Discoverability). <br>
- `accuracy`: Final-answer correctness against the reference answer. <br>
- `goal_accuracy`: Whether the user's goal was achieved. <br>
- `behavior_check`: Whether the expected workflow behavior was followed. <br>
- `token_efficiency`: Actual uncached prompt plus completion token usage. <br>



## Evaluation Results: <br>
| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) |
|---|---:|---:|
| Overall | 91.9% | 94.9% |
| Security | 100.0% → 100.0% (±0.0 points) | 100.0% → 100.0% (±0.0 points) |
| Correctness | 90.0% → 100.0% (+10.0 points) | 90.0% → 100.0% (+10.0 points) |
| Discoverability | 93.3% | 95.0% |
| Effectiveness | 79.2% → 89.8% (+10.6 points) | 76.7% → 93.1% (+16.4 points) |
| Efficiency | 76.3% | 86.6% |

## Skill Version(s): <br>
1.0.2 (source: frontmatter) <br>

## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>
  • 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.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude