Skip to content

[WIP] Add UnitarySynthesis transpiler pass to C API #14740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

mtreinish
Copy link
Member

Summary

This commit adds a standalone transpiler pass function to the C API for
running the UnitarySynthesis transpiler pass. This pass mutates a dag
in place and updates the provided circuit pointer with the newly
generated circuit. Right now the pass doesn't support >= 3q unitaries,
targets that would rely on the XX decomposer, or have the unitary
synthesis plugin interface that exists in Python. The first two could be
fixed if/when those synthesis algorithms are ported to C, but the plugin
interface will need some thought to think about how to expose that via
the C FFI, it will certainly be different/distinct from the Python
interface but some discovery and design will be needed to come up with a
reasonable interface to make unitary synthesis pluggable from C.

Details and comments

Fixes #14451

This depends on #14732 and will need to be rebased after that PR merges. In the meantime you can look at the HEAD commit to see the contents of this PR: 2524561

TODO:

This commit updates the UnitarySynthesis transpiler pass's rust
internals to add a path for running the pass without Python. This is a
requirement for using the pass from the C API. The complexity is that
part of the pass's core functionality is still in Python, mainly two
decomposers the XXDecomposer and the QSD function. These code paths are
super commonly used, although the QSD function will be necessary to
decompose 3+ qubit unitaries this is an ok limitation for the initial
C API especially since development of a rust QSD is in progress this is
only a temporary limitation.

The path through the pass without Python removes the explicit py token
from the main entrypoint and also adds a new rust entrypoint distinct
from the Python caller that has a new argument run_python_decomposers.
If this argument is set to `false` and either the xx decomposer or qsd
path are triggered the function will now either skip it or return an
error if there is no alternative.

Part of Qiskit#14451
This commit adds a standalone transpiler pass function to the C API for
running the UnitarySynthesis transpiler pass. This pass mutates a dag
in place and updates the provided circuit pointer with the newly
generated circuit. Right now the pass doesn't support >= 3q unitaries,
targets that would rely on the XX decomposer, or have the unitary
synthesis plugin interface that exists in Python. The first two could be
fixed if/when those synthesis algorithms are ported to C, but the plugin
interface will need some thought to think about how to expose that via
the C FFI, it will certainly be different/distinct from the Python
interface but some discovery and design will be needed to come up with a
reasonable interface to make unitary synthesis pluggable from C.

Fixes Qiskit#14451
@mtreinish mtreinish added this to the 2.2.0 milestone Jul 15, 2025
@mtreinish mtreinish requested a review from a team as a code owner July 15, 2025 18:58
@mtreinish mtreinish added on hold Can not fix yet Changelog: New Feature Include in the "Added" section of the changelog mod: transpiler Issues and PRs related to Transpiler C API Related to the C API labels Jul 15, 2025
@qiskit-bot
Copy link
Collaborator

One or more of the following people are relevant to this code:

  • @Qiskit/terra-core

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C API Related to the C API Changelog: New Feature Include in the "Added" section of the changelog mod: transpiler Issues and PRs related to Transpiler on hold Can not fix yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add UnitarySynthesis to the C API
2 participants