Adding MCX synthesis plugins #12961

alexanderivrii · 2024-08-15T13:28:03Z

Summary

This PR builds on top of #12904 and #12911 and adds additional MCX synthesis methods and MCX synthesis plugins, some support clean and dirty auxiliary qubits.

The default plugin for MCX gates runs other plugins maximally trying to exploit the sets of clean and dirty ancilla qubits available: it first tries the 'clean-n' method, then the 'dirty-n' method, then the 'clean-1' method, and finally the reduction to mcphase.

The MCXRecursive gate and other custom variants are marked for pending deprecation (and will be removed some time in the future).

Details and comments

The high_level_synthesis.py file was split into two: one containing the transpiler pass, and one containing the plugins.

There were a few additional caveats:

The MCXRecursive (and other custom MCX variants) inherit from MCXGate but are not called "mcx"
The C3XGate and C4XGate are called "mcx" but do not inherit from MCXGate.

The first point will be cleaned up by deprecating custom MCX variants. The second point might be cleaned up by renaming the names for C3XGate and C4XGate, however might introduce some breaking changes and should be done for 2.0.

…m as HLS synthesis plugins.

…mcx but is not an MCXGate

For better or for worse, C3X and C4X gates have name 'mcx', and therefore are caught by mcx plugins. We need to avoid recursion with HLS calling an MCX-synthesis plugin for a C3X-gate, which in turns returns a C3X-gate.

…oid qasm changes

…_decompose

qiskit-bot · 2024-08-15T13:28:09Z

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

@Cryoris
@Qiskit/terra-core
@ajavadia

alexanderivrii · 2024-08-15T13:33:08Z

One other thing: I would like to replace _define for C3XGate and C4XGate in x.py by synthesis/multi-controlled/synth_c3x and synth_c4x, but this leads to circular imports (these are singleton gates so the imports seem to be happening on the top-level). Help appreciated.

coveralls · 2024-08-15T13:52:59Z

Pull Request Test Coverage Report for Build 10503316607

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

272 of 299 (90.97%) changed or added relevant lines in 7 files are covered.
16 unchanged lines in 3 files lost coverage.
Overall coverage decreased (-0.001%) to 89.574%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/transpiler/passes/synthesis/hls_plugins.py	187	214	87.38%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	91.48%
qiskit/transpiler/passes/synthesis/high_level_synthesis.py	6	96.62%
crates/qasm2/src/parse.rs	6	96.69%

Totals
Change from base Build 10487858724:	-0.001%
Covered Lines:	67750
Relevant Lines:	75636

💛 - Coveralls

alexanderivrii · 2024-08-15T13:53:14Z

A quick experiment on benchpress multi_control_circuit benchmark (see #12729 for some prior numbers):

Number of 2-qubit gates:

10 qubits: tket: 937, before this PR: 1269, with this PR: 809
15 qubits: tket: 3617, before this PR: 5849, with this PR: 2293

The improvement comes from better synthesis algorithms that use clean/dirty ancilla qubits

ShellyGarion

Thanks @alexanderivrii! I've made some preliminary comments (mainly on the functions names and API)

qiskit/synthesis/__init__.py

qiskit/synthesis/multi_controlled/mcx_synthesis.py

ShellyGarion · 2024-08-16T06:02:14Z

qiskit/synthesis/multi_controlled/mcx_synthesis.py

+    return qc
+
+
+def synth_mcx_mcphase(num_ctrl_qubits: int) -> QuantumCircuit:


Any better suggestions for this function name? the mcp synth is based on iteratively using mcrz synth.
I would suggest synth_mcx_basic ?

Doesn't mcrz use the _mcsu2 work? Maybe we can use that paper as reference?

I was looking for a better name for this too, so ideas are welcome. I am not particularly fond of synth_mcx_basic though, as the word "basic" is too generic. By the way, do we have a reference for this?

here is a reference for the mcrz (mcsu2) paper, but this code is a variant that does not appear in the paper.

[1] R. Vale et al. Decomposition of Multi-controlled Special Unitary Single-Qubit Gates
arXiv:2302.06377 (2023) https://arxiv.org/abs/2302.06377

Thanks for the reference; adding.

I still think that we should find a better name than " synth_mcx_mcphase"

After an offline discussion with @ShellyGarion and @Cryoris, we have settled on synth_v24. I am not really fond of this or other names, but this is the best we could think of and consistent with the naming of other methods.

Yeah, we should definitely introduce a human-readable alias for these methods, which users can call in the HLS 🙂

qiskit/synthesis/multi_controlled/mcx_synthesis.py

qiskit/circuit/library/standard_gates/x.py

qiskit/synthesis/__init__.py

qiskit/synthesis/multi_controlled/mcx_synthesis.py

alexanderivrii · 2024-08-20T13:34:33Z

Thanks @Cryoris for the review. I have addressed of all your review comments (I think), so it's ready for review once again. The only remaining question (for the rest of the team) is what you think about the current plugin names "n_clean_m15", "v24", "1_clean_b95" -- these do look a bit ugly, but the best naming convention we could come up so far is to base the names off what they do (e.g., use n clean ancillas) and the name of the first author + the year of the paper describing the technique (e.g., Vale et al's 2024 paper).

… decomposition

qiskit/circuit/library/standard_gates/x.py

releasenotes/notes/add-mcx-plugins-85e5b248692a36db.yaml

Co-authored-by: Julien Gacon <gaconju@gmail.com>

ShellyGarion

LGTM. Thanks @alexanderivrii !
I only have one question, I generated the API docs, and could not find the hls_plugins.
Do you know where should they be located now?

alexanderivrii · 2024-08-22T06:14:09Z

@ShellyGarion, thanks for noticing! The docs now correctly appear in: html_docs/html/apidoc/synthesis.html

ShellyGarion · 2024-08-22T06:38:11Z

Another small comment - the last table in transpiler_synthesis_plugins.html shows the following, so all the references are [1].
So either remove it, or specify first author and a year.

…into mcx-plugins

alexanderivrii · 2024-08-22T06:56:54Z

@ShellyGarion , thanks for noticing that too. Fixed.

Cryoris

LGTM thanks for all the effort! I'll wait with putting it the merge queue, if @ShellyGarion still has some comments 🙂

alexanderivrii added 20 commits August 12, 2024 12:43

moving high-level-synthesis plugins to a separate file

d3e882c

Adding the remaining MCX synthesis functions and exposting all of the…

a64597a

…m as HLS synthesis plugins.

adding entry points for MCX plugins

e548257

adding documentation section for MCX plugins

dccd30f

renaming file

d5458ce

Adding pending deprecation warnings

014b8a2

placeholder for MCX plugin tests

cab6cb5

adding flag pending=True to deprecate

a79e2f9

changing checks from isinstance to name-based: a CCCX gate is called …

364cf75

…mcx but is not an MCXGate

merging main

bc4238c

futher exposing C3X and C4X synthesis

fa94424

fix compose to append

e54706b

renaming synthesized circuits for c3x and for c4x back to 'mcx' to av…

c3c1927

…oid qasm changes

test qasm fixes

b21f3ea

randomly spotted typo

f0f3de9

fixing how QuantumCircuit.decompose works in the presence of gates_to…

01d76b2

…_decompose

updating MCX plugins to check isinstance

d739065

fixing test

d856c88

pylint fixes

08051f3

alexanderivrii requested review from ShellyGarion and a team as code owners August 15, 2024 13:28

ShellyGarion mentioned this pull request Aug 15, 2024

Organize the synthesis library of multi-controlled gates #12863

Closed

10 tasks

properly fixing test

d73d941

ShellyGarion reviewed Aug 16, 2024

View reviewed changes

Cryoris mentioned this pull request Aug 16, 2024

Fix multi-control gates attributes preservation in QPY #12489

Open

alexanderivrii added 3 commits August 20, 2024 16:19

renaming mcphase to v24

6bb46d5

removing unncessary checks

e5cd0b8

addressing the rest of review comments

d6226b9

alexanderivrii requested a review from Cryoris August 20, 2024 13:29

and of course updating qasm checking after we've slightly changed the…

9278d26

… decomposition

Cryoris reviewed Aug 20, 2024

View reviewed changes

alexanderivrii and others added 6 commits August 20, 2024 17:19

yet another renaming

3879cdd

Update qiskit/circuit/library/standard_gates/x.py

1c05061

Co-authored-by: Julien Gacon <gaconju@gmail.com>

Update qiskit/circuit/library/standard_gates/x.py

40228f0

Co-authored-by: Julien Gacon <gaconju@gmail.com>

Update releasenotes/notes/add-mcx-plugins-85e5b248692a36db.yaml

0649bc9

Co-authored-by: Julien Gacon <gaconju@gmail.com>

release notes

5a8ba64

formatting

5422990

ShellyGarion reviewed Aug 21, 2024

View reviewed changes

alexanderivrii added 2 commits August 21, 2024 11:16

fixing docs

e0765ec

Merge branch 'main' into mcx-plugins

5f14493

alexanderivrii requested review from ShellyGarion and Cryoris August 22, 2024 06:14

alexanderivrii added 2 commits August 22, 2024 09:55

removing references from the first sentence of plugin descriptions

82586cb

Merge branch 'mcx-plugins' of github.com:alexanderivrii/qiskit-terra …

c0746ec

…into mcx-plugins

Cryoris approved these changes Aug 22, 2024

View reviewed changes

ShellyGarion added this pull request to the merge queue Aug 22, 2024

Merged via the queue into Qiskit:main with commit 072548f Aug 22, 2024
15 checks passed

Cryoris mentioned this pull request Aug 27, 2024

Circuit library modernization #13046

Open

ShellyGarion added the Changelog: New Feature Include in the "Added" section of the changelog label Nov 5, 2024

ryanhill1 mentioned this pull request Dec 3, 2024

[FEATURE] Update qiskit requirement from <1.3,>=0.44 to >=0.44,<1.4 qBraid/qBraid#842

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding MCX synthesis plugins #12961

Adding MCX synthesis plugins #12961

alexanderivrii commented Aug 15, 2024 •

edited

Loading

qiskit-bot commented Aug 15, 2024

alexanderivrii commented Aug 15, 2024

coveralls commented Aug 15, 2024 •

edited

Loading

alexanderivrii commented Aug 15, 2024 •

edited

Loading

ShellyGarion left a comment

ShellyGarion Aug 16, 2024

Cryoris Aug 16, 2024

alexanderivrii Aug 16, 2024

ShellyGarion Aug 16, 2024

alexanderivrii Aug 18, 2024

ShellyGarion Aug 19, 2024

alexanderivrii Aug 20, 2024

Cryoris Aug 20, 2024

alexanderivrii commented Aug 20, 2024 •

edited

Loading

ShellyGarion left a comment •

edited

Loading

alexanderivrii commented Aug 22, 2024

ShellyGarion commented Aug 22, 2024

alexanderivrii commented Aug 22, 2024

Cryoris left a comment

		return qc


		def synth_mcx_mcphase(num_ctrl_qubits: int) -> QuantumCircuit:

Adding MCX synthesis plugins #12961

Adding MCX synthesis plugins #12961

Conversation

alexanderivrii commented Aug 15, 2024 • edited Loading

Summary

Details and comments

qiskit-bot commented Aug 15, 2024

alexanderivrii commented Aug 15, 2024

coveralls commented Aug 15, 2024 • edited Loading

Pull Request Test Coverage Report for Build 10503316607

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

alexanderivrii commented Aug 15, 2024 • edited Loading

ShellyGarion left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexanderivrii commented Aug 20, 2024 • edited Loading

ShellyGarion left a comment • edited Loading

Choose a reason for hiding this comment

alexanderivrii commented Aug 22, 2024

ShellyGarion commented Aug 22, 2024

alexanderivrii commented Aug 22, 2024

Cryoris left a comment

Choose a reason for hiding this comment

alexanderivrii commented Aug 15, 2024 •

edited

Loading

coveralls commented Aug 15, 2024 •

edited

Loading

alexanderivrii commented Aug 15, 2024 •

edited

Loading

alexanderivrii commented Aug 20, 2024 •

edited

Loading

ShellyGarion left a comment •

edited

Loading