Native OpenQASM 2.0/3.0 Translation and Expanded Qiskit Support in contrib

[QuantumRaul]

Background & Context

I recently submitted PR #4613 which expanded the interoperability features within the cudaq.contrib module. The PR was labeled with a wontfix without additional feedback.

Since the PR was an iteration over my previously merged work in the same module, I am opening this issue to shift the conversation from a code review to a high-level architectural discussion. I would love to understand the core team's roadmap regarding OpenQASM parsing and framework interoperability, and see if the concepts proposed hold value for the project's future.

Motivation & The Gap

Currently, translating OpenQASM into CUDA-Q relies heavily on external dependencies. The proposal aims to solve two main pain points for users:

1. Dependency Overhead: Relying on Qiskit just to parse OpenQASM introduces unnecessary overhead. A native, zero-dependency translator simplifies the pipeline.
2. OpenQASM 3.0 Support: As the ecosystem moves towards OpenQASM 3.0, having first-class support (declarations, built-in gates, assignments) is becoming critical.
3. Qiskit Round-tripping: The existing from_qiskit coverage is somewhat limited. Expanding the dispatch table ensures users can round-trip circuits built with the full Qiskit standard library (qelib1.inc / stdgates.inc) without silent failures.

Proposed Solution (Proof of Concept)

The closed PR serves as a fully tested Proof of Concept for this architecture. The key features implemented were:

• Native OpenQASM Translator (from_qasm_str, from_qasm): A pure-Python parser dispatching on the OPENQASM <version>; header.
  • _QASM2Translator: Covers the full qelib1.inc gate set, user-defined gates with recursive expansion, and register broadcasting.
  • _QASM3Translator: Adds the 3.0 surface (qubit[N], c = measure q;, etc.).
  • Includes a safe expression evaluator built on ast.parse for parameter expressions.
• Expanded from_qiskit: Replaced ad-hoc if/elif with a comprehensive _GATE_HANDLERS dictionary covering parametric families and multi-qubit gates, staying in lockstep with the QASM semantics.

Discussion Questions for Maintainers

I understand that a wontfix usually means the approach conflicts with internal plans. To help align community contributions with the CUDA-Q vision:

1. Is the translation of OpenQASM 2.0/3.0 currently being developed at the C++ compiler/core level, making a Python contrib approach redundant?
2. If a native Python parser is not desired, would the team be open to merging only the expanded Qiskit gate coverage (from_qiskit improvements) in a separate PR?
3. What is the current policy/roadmap for the cudaq.contrib module moving forward?

Thanks for your time and for maintaining this great framework!

[aminx-hue]

@QuantumRaul We have someone looking into this and will get back to you shortly

[anpaz]

@QuantumRaul — first of all, thanks for your continuous contributions to the project. We really appreciate your engagement and your work.

The main concern is that we want to move to a model where integrations with third parties are not part of our repository, as this has multiple drawbacks:

• It adds work for us to maintain
• It removes ownership from the main contributors
• It couples our releases to third-party code
• External code can silently go stale as upstream projects evolve, creating a bad experience for users who assume it's maintained
• External contributors may not know who owns integration code, leading to PRs and issues being directed to the wrong people

We are already working on a plugin model for backends that will allow us to integrate with different backends hosted in other repositories (see #4619). OpenQASM and Qiskit fall into the same category — integrations with external projects that we don't feel belong in our repo.

The good news is that we don't think a new plugin system is needed for this. The OpenQASM integration can be built and released simply by taking a dependency on CUDA-Q and installed on top of it if you need it.

We would like to start exploring with you what would be a good mechanism to take your previous contribution and migrate it to a new GitHub repo with all the CI bells and whistles, in a way that it's easy to install on its own. We are also considering how to promote these contributions in our repo and documentation, and would like to work with you on that too. You would be one of the first projects on this new pattern, so you could really help us drive this and make it a success.

What do you think — would you be interested in driving this as a standalone project?

[QuantumRaul]

Thanks for the thoughtful response,. This makes a lot of sense, and I'm fully on board with the direction.

I agree with the reasoning: third-party integrations create a maintenance and ownership burden, couple your release cadence to upstream projects you don't control, and risk going stale. Moving them out of the core repo and onto a "depends on CUDA-Q, installs on top of it" model is the right call, and it makes sense that OpenQASM/Qiskit don't need the external backend package model (#4619) to get there, they're a language-translation layer, not a target/runtime integration, so a plain package on top of the public cudaq API is enough.

Yes, I'd be glad to drive this as a standalone project.

Here's what I'm proposing, and I'd love your feedback:

Package

• Name: cudaq-contrib (keeps continuity with the current cudaq.contrib module name so existing users recognize it).
• Install: pip install cudaq-contrib, depending on cuda-quantum.
• Public API (unchanged from the PR): from_qasm, from_qasm_str, from_qiskit.
• Zero reach into CUDA-Q internals. The current code only needs make_kernel, which is already part of the public cudaq API, so the extraction is clean, no private symbols, no coupling to the build tree.

Scope of the move

The two translators from PR #4613 migrate as-is:

• Native pure-Python OpenQASM 2.0/3.0 translator (_QASM2Translator / _QASM3Translator), no Qiskit dependency for parsing.
• Expanded from_qiskit with the _GATE_HANDLERS dispatch table covering the full qelib1.inc / stdgates.inc gate set, plus recursive Instruction.definition fallback.
• The full test suite (test_from_qasm.py, test_from_qiskit.py, test_roundtrip.py).

Qiskit stays an optional dependency (pip install cudaq-contrib[qiskit]), only the OpenQASM path is dependency-free, so users who only need QASM don't pull in Qiskit.

CI / release

• Lint + format matching CUDA-Q conventions (yapf/Google style), pytest matrix across supported Python versions.
• Compatibility note/test against the CUDA-Q versions the package targets, since make_kernel is the integration surface.
• Tagged releases publishing to PyPI.

Open questions for you

1. Where should the repo live?. Under an NVIDIA org, my own account with a link from CUDA-Q docs, or a community/contrib org you'd prefer? This affects naming and trust signaling.
2. Discoverability: you mentioned promoting these in the repo/docs. Would a curated "ecosystem / interop" page that links out to standalone projects like this one be the pattern? Happy to draft that page as part of this effort so we establish the template for the projects that follow.
3. CUDA-Q version compatibility policy. Is there a recommended way to pin/declare the supported cuda-quantum range, so the package degrades gracefully when the public API evolves?

Since I'd be one of the first projects on this pattern, I'm glad to help shape the conventions (repo template, CI, docs linkage) so it's repeatable for the next contributor. Just point me at whatever org/process constraints you have and I'll get the first cut up.

[anpaz]

@QuantumRaul, sorry for the delay. I've been traveling for the World Cup and I got distracted :)
I'm excited to have you on board! This is what I'm thinking:

1. I'll create a cudaq-community organization to host external community contributions
2. We'll create a new repo in there for your project. What name do you want to give it? I'm thinking openqasm2cudaq but maybe that's too corporate? It's your project so I'll let you decide
3. We'll work on adding a "Community Contributions" section under our Extending CUDA-Q page in our documentation.
4. I'll work on creating some clear guidelines about expectations for the repos in cudaq-community. I'll try to keep it at a minimal, but we'll need to have the ability to report security issues, I'll keep you in the loop to gather your feedback.

[QuantumRaul]

@anpaz Thanks, and no worries at all, hope the World Cup is being a good time! 🙂 Excited to move this forward. Replying to your points:

1. The cudaq-community org: Love it. Happy to be one of the first repos there and to help shake out any early rough edges.

2. Repo name: I'd like to go with cudaq-convert. The package isn't limited to OpenQASM 2.0, it already converts OpenQASM 2.0, OpenQASM 3.0, and Qiskit circuits into CUDA-Q kernels (the public API is from_qasm, from_qasm_str, from_qiskit). openqasm2cudaq would undersell that and read as OpenQASM-2-only. cudaq-convert is concise, stays accurate as we add more source formats, and pip install cudaq-convert reads naturally. So my vote is cudaq-community/cudaq-convert, but happy to hear if you feel strongly otherwise.

3. "Community Contributions" docs section: Sounds great, count me in. The package is standalone and being built to be pip-installable (depends only on the public cudaq API via make_kernel, installs on top of CUDA-Q), so it should slot in cleanly under the Extending CUDA-Q page whenever the section is ready.

4. Security guidelines: Makes sense, and agreed on keeping it minimal. Happy to review a draft and give feedback on the security-issue reporting flow whenever you have something to share.

Just let me know once the org exists and I'll create the repo under it. Thanks again for setting all this up!

One note that must be mentioned: The Qiskit/OpenQASM-CUDAQ interoperability module was merged some time ago in the PR #3847 I opened. As this utility will be living under a standalone proyect this contrib module under the python API should be removed in order to avoid any conflicts.

[anpaz]

Excellent! I'm going through the internal red-tape for creating a new org, and I'm also working on writing up some documentation of how I expect the process will work, and
I'll also work on creating some community health files (contributing, security, code of conduct) that we can use as templates for the repos.