cudaq-importing

Files (6)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• porting-reference.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills