Mathnetica Tools for CUDA-Q

Independent developer tools for NVIDIA CUDA-Q™ in Visual Studio Code and Cursor.

Run CUDA-Q programs, inspect your environment, select execution targets, work with Jupyter notebooks, and optionally use AI assistance — without leaving the editor.

Preview: Mathnetica Tools for CUDA-Q is under active development. Feedback and contributions are welcome.

Features

• Run CUDA-Q — Execute CUDA-Q Python files directly from the editor
• Kernel CodeLens — Run @cudaq.kernel functions from the editor
• Target selection — Discover and switch between available CUDA-Q execution targets
• Environment diagnostics — Inspect Python, CUDA-Q version, platform, and GPU availability
• CUDA-Q detection — Automatically recognize CUDA-Q projects and files
• Jupyter support — Work with CUDA-Q inside VS Code / Cursor notebooks
• CUDA-Q snippets — Quickly create kernels, qvectors, sampling code, and common examples
• Optional AI assistance — Explain, fix, and generate CUDA-Q code using local Ollama or Mistral BYOK

Quick Start

1. Install CUDA-Q

pip install cuda-quantum

Verify the installation:

python -c "import cudaq; print(cudaq.__version__)"

2. Select your Python environment

In VS Code or Cursor run:

Python: Select Interpreter

Select the environment where CUDA-Q is installed.

3. Open CUDA-Q code

For example:

import cudaq

@cudaq.kernel
def bell():
    qubits = cudaq.qvector(2)
    h(qubits[0])
    x.ctrl(qubits[0], qubits[1])

result = cudaq.sample(bell)
print(result)

The extension detects CUDA-Q and activates the relevant developer tools.

4. Run

Open the Command Palette (Ctrl/Cmd + Shift + P) and run:

CUDA-Q: Run Current File

Output appears in the Mathnetica Tools for CUDA-Q output channel.

Commands

Kernel CodeLens

CUDA-Q kernels are detected automatically:

@cudaq.kernel
def bell():
    ...

Editor actions appear above the kernel:

▶ Run Kernel    ✨ Explain

In the current Preview, running a kernel executes the containing Python file so imports and surrounding context are preserved.

Execution Targets

The current CUDA-Q target is shown in the status bar:

CUDA-Q: qpp-cpu

Click the status bar item or run:

CUDA-Q: Select Target

Target availability is determined from your local CUDA-Q environment. The extension does not assume that GPU or QPU targets are available.

Jupyter Notebooks

CUDA-Q is supported in .ipynb notebooks opened with the Microsoft Jupyter extension.

Notebook-aware commands include:

• Mathnetica: Explain Current Cell
• Mathnetica: Fix Current Cell

Standalone JupyterLab is not currently supported.

CUDA-Q Snippets

Type a prefix and press Tab:

cudaq-import
cudaq-kernel
cudaq-qvector
cudaq-sample
cudaq-observe
cudaq-bell

Optional AI Assistant

AI is completely optional. All core CUDA-Q tools work without configuring an AI provider.

Ollama — Local

Configure:

Mathnetica Tools for CUDA-Q › AI: Enabled → true
Mathnetica Tools for CUDA-Q › AI: Provider → ollama

Set the Ollama URL and model in settings. Requests go to your local Ollama instance.

Mistral — BYOK

Run:

Mathnetica: Set Mistral API Key

The key is stored in VS Code / Cursor SecretStorage — not in settings or source code.

When using a cloud provider, selected source code and relevant context may be sent to that provider.

AI Commands

AI-generated code may be incorrect. Review it before running.

Requirements

• Visual Studio Code 1.85+ or Cursor
• Python 3.9+
• CUDA-Q installed in the selected Python environment

Recommended extensions:

• Python
• Jupyter

Privacy

• No telemetry in the current Preview release
• Ollama: requests go to your configured local endpoint
• Mistral: request content is sent to Mistral's API
• API credentials use SecretStorage

Known Limitations

This is an early Preview release.

• Kernel execution currently runs the containing Python file
• GPU detection depends on locally available system tooling
• Target discovery requires a working CUDA-Q installation
• Standalone JupyterLab is not supported
• Circuit visualization is not yet available
• AI does not yet use CUDA-Q documentation retrieval / RAG

Roadmap

v0.2 — Developer Experience

• Improved CUDA-Q diagnostics
• Better notebook integration
• CUDA-Q documentation context

v0.3 — Visualization & Execution

• Circuit visualization
• Richer execution results
• Improved GPU execution workflow

v0.4 — Migration

• Qiskit → CUDA-Q migration assistance

v1.0

• Broader CUDA-Q development environment

The roadmap is directional and may change based on feedback.

Feedback & Contributing

Bug reports, feature requests, and contributions are welcome via the GitHub repository.

Local development

npm install
npm run compile

Press F5 to launch the Extension Development Host, or package a VSIX:

npm run package

Then install with Extensions → Install from VSIX….

License

MIT License. See LICENSE for details.

Trademark Notice

Mathnetica Tools for CUDA-Q is an independent open-source project developed by Mathnetica. It is not affiliated with, sponsored by, or endorsed by NVIDIA Corporation.

NVIDIA and CUDA-Q are trademarks of NVIDIA Corporation in the United States and other countries. All other trademarks are the property of their respective owners.

This project does not use NVIDIA logos or official CUDA-Q branding assets.