Deprecate `qiskit.extensions` #10725

Cryoris · 2023-08-29T12:48:04Z

Summary

Deprecates the qiskit.extensions submodule. Contents are either moved to the circuit library or deprecated. In future it would be nice to build high-level synthesis passes for algorithms that synthesis the same type of operation. E.g. isometry could be a synthesis for unitaries (or for state initialization).

Details and comments

Here's a detailed list of moves:

Moved to generalized gates

uc<any>.py: These are multiplexed gates, as such they are generalizations of gates we have in the standard gate library
unitary.py: General unitary gate (hence generalized gate)
isometry.py: Implements isometries, and as subset of this also unitaries, so it should live in the same place as UnitaryGate.
mcg_up_diag.py: Implements a multicontrolled gate up to a diagonal, hence a generalization of controlled gates.
diagonal.py: Moved the DiagonalGate into the same file as the Diagonal circuit

Moved to data preparation

initializer.py: Prepares an arbitray initial state and should be next to StatePreparation, which is a data preparation operation. Could also live next to UnitaryGate, but then we'd also have to move the state preparation.

Moved to circuit library root:

hamiltonian_gate.py: Implements an exact operator evolution and should be next to PauliEvolutionGate.

Deprecated:

squ.py: Implements a 1q-unitary matrix and thus a duplicate functionality of UnitaryGate. Also not used anywhere in the source code.
snapshot.py: Superseded by Aer's save_* instructions.

Monkey-patched circuit methods:

Deprecated: diagonal, hamiltonian, uc, ucrx, ucry, ucrz, squ, snapshot
Moved to the circuit class as they are frequently used: unitary, initialize

qiskit-bot · 2023-08-29T12:48:08Z

One or more of the the following people are requested to review this:

@enavarro51
@Cryoris
@Qiskit/terra-core
@ajavadia
@ikkoham
@levbishop
@mtreinish
@nkanazawa1989
@t-imamichi
@woodsp-ibm

Cryoris · 2023-08-29T12:49:24Z

qiskit/circuit/library/__init__.py

@@ -181,6 +181,7 @@
   :template: autosummary/class_no_inherited_members.rst

   Diagonal
+   DiagonalGate


I would've liked to deprecate this as the Diagonal circuit exists, but DiagonalGate seems to be used in the Aer simulators.

imo it should be the circuit that gets removed not the gate, since circuits inherently define an eager synthesis, but that's not important.

Agreed, maybe this would best be part of an overhaul to consistently use Gate or Circuits (probably the first) 🙂

I agree that this is quite confusing. Maybe it's worth to add a comment somewhere about the difference between them, and which one will be deprecated?
(although we also have Permutation and PermutationGate)

I think we had the plans to deprecate Permutation circuit once PermutationGate is around. Do you think it's a good idea?

qiskit/circuit/library/generalized_gates/mcg_up_to_diagonal.py

Cryoris · 2023-08-29T12:50:34Z

qiskit/circuit/library/hamiltonian_gate.py

We could consider creating an evolutions submodule containing this and the PauliEvolutionGate.

Cryoris · 2023-08-29T12:51:31Z

qiskit/circuit/library/hamiltonian_gate.py

+        data = np.array(data, dtype=complex)
+        # Check input is unitary
+        if not is_hermitian_matrix(data):
+            raise ValueError("Input matrix is not Hermitian.")


Some errors were changed from ExtensionsError to ValueError, which is strictly speaking not backwards compatible. It seemed small enough to be still fine, but we could also create an intermediate class, covering both, for the deprecation period.

qiskit/circuit/library/data_preparation/initializer.py

qiskit/extensions/quantum_initializer/initializer.py

qiskit/assembler/disassemble.py

jakelishman · 2023-08-29T13:04:28Z

qiskit/circuit/library/__init__.py

@@ -181,6 +181,7 @@
   :template: autosummary/class_no_inherited_members.rst

   Diagonal
+   DiagonalGate


imo it should be the circuit that gets removed not the gate, since circuits inherently define an eager synthesis, but that's not important.

qiskit/circuit/library/data_preparation/initializer.py

coveralls · 2023-08-30T15:09:33Z

Pull Request Test Coverage Report for Build 6248054115

312 of 378 (82.54%) changed or added relevant lines in 38 files are covered.
11 unchanged lines in 3 files lost coverage.
Overall coverage decreased (-0.02%) to 87.274%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/circuit/library/data_preparation/initializer.py	30	32	93.75%
qiskit/circuit/library/generalized_gates/unitary.py	14	16	87.5%
qiskit/circuit/library/generalized_gates/diagonal.py	28	31	90.32%
qiskit/circuit/library/hamiltonian_gate.py	20	23	86.96%
qiskit/circuit/quantumcircuit.py	109	165	66.06%

Files with Coverage Reduction	New Missed Lines	%
qiskit/extensions/exceptions.py	2	72.73%
qiskit/qpy/binary_io/circuits.py	4	92.38%
crates/qasm2/src/lex.rs	5	90.91%

Totals
Change from base Build 6246166195:	-0.02%
Covered Lines:	74306
Relevant Lines:	85141

💛 - Coveralls

qiskit/circuit/quantumcircuit.py

releasenotes/notes/deprecate-extensions-d7ab3fca19962e2e.yaml

- capture warning of SQU - update reno to explicitly mention pending deprecation, add DiagonalGate and ExtensionError

alexanderivrii · 2023-09-28T15:43:19Z

I think this is ready to be merged: all the review comments have been addressed. @Cryoris, thanks for the massive work on this, I am personally very excited to see the qiskit.extensions module finally being deprecated.

jakelishman

Thanks Sasha, Shelly and Elena for reviewing this and Julien for doing it! In general, this was a complex deprecation, and it looks like it's gone fairly well.

I think I was meant to look over this before it merged, just as a final check, so I've done so now, and I just left a couple of notes (nothing major that really needs changing). Top level stuff:

There's a lot of unrelated code changes in here (type hints, renaming standard imports, refactoring the moved gates) that probably would have been better in separate PRs, especially because some of them will have (minor) behavioural changes.
The title of this PR / commit as it merged was kind of wrong - most of qiskit.extensions isn't deprecated this release, it's pending because this PR is more about moving everything into new places.

jakelishman · 2023-09-29T09:49:22Z

qiskit/__init__.py

-# The qiskit.extensions.x imports needs to be placed here due to the
-# mechanism for adding gates dynamically.
-import qiskit.extensions


Removing this in conjunction with all the rest of the work on removing uses of qiskit.extensions actually was a bit of a breaking change, because qiskit.extensions is no longer available just by having done import qiskit. In other words:

import qiskit qiskit.extensions.CXGate

would have worked without error before, and now it'll say

AttributeError: module 'qiskit' has no attribute 'extensions'

and require you to do import qiskit.extensions.

That's minor and we can probably get away with it, but it was a dedicated submodule that was previously automatically imported, so just pointing out that these removals can cause issues.

jakelishman · 2023-09-29T09:53:00Z

qiskit/circuit/library/generalized_gates/diagonal.py

-    def __init__(self, diag: list[complex] | np.ndarray) -> None:
-        """Create a new Diagonal circuit.
-
+    def __init__(self, diag: Sequence[complex]) -> None:
+        r"""


Sequence isn't the correct type hint. ndarray is not a Sequence, and Diagonal._check_input requires the input to be list | ndarray anyway.

jakelishman · 2023-09-29T09:56:37Z

qiskit/circuit/library/generalized_gates/diagonal.py

-        if not isinstance(diag, (list, np.ndarray)):
-            raise CircuitError("Diagonal entries must be in a list or numpy array.")
-        num_qubits = np.log2(len(diag))
-        if num_qubits < 1 or not num_qubits.is_integer():
-            raise CircuitError("The number of diagonal entries is not a positive power of 2.")
-        if not np.allclose(np.abs(diag), 1, atol=_EPS):
-            raise CircuitError("A diagonal element does not have absolute value one.")
-


It might have been a bit better to make any code refactors like these in a follow-up PR, rather than squashed into a +1.5k,-1.3k changeset that notionally shouldn't have any effect on the objects.

jakelishman · 2023-09-29T10:00:20Z

qiskit/circuit/library/generalized_gates/mcmt.py

+
+# pylint: disable=cyclic-import
 from ..standard_gates import XGate, YGate, ZGate, HGate, TGate, TdgGate, SGate, SdgGate


This extra suppression is indicative to me that we've put a gate somewhere in the wrong place - I suspect it's UnitaryGate, which it might have been cleaner to give special treatment, since it's used by the base Gate class. standard_gates shouldn't need to cyclically import generalized_gates.

We can re-arrange things in other PRs, though, no worries.

This might also be unnecessary -- after moving the gates there were loads of cyclic imports, and I might have added one too many ignores.... 🙈

I think it's probably a true one - UnitaryGate being inside generalized_gates is one of the things we maybe want to reconsider before the actual release; it's kind of a base gate, and while I can see the argument for calling it "generalized", it's fundamental to a lot of how synthesis and the Gate class works, whereas everything else in generalized_gates is rather higher level and should be 100% safe to import after standard_gates.

jakelishman · 2023-09-29T10:08:13Z

qiskit/circuit/library/generalized_gates/unitary.py

        if not is_unitary_matrix(data):
-            raise ExtensionError("Input matrix is not unitary.")
+            raise ValueError("Input matrix is not unitary.")


This feels like an error people could conceivably have been catching as part of a validation workflow. During the deprecation period, we might have wanted to use a custom error type that derived both ExtensionError and ValueError, and only switched the documentation over to saying it raised ValueError.

Yeah, I pointed this out in #10725 (comment) as I wasn't sure whether we should take this precaution 🤔

jakelishman · 2023-09-29T10:18:04Z

qiskit/circuit/quantumcircuit.py

+        # catch deprecation warning from instantiating the Snapshot instruction,
+        # as a warning is already triggered from this method
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=DeprecationWarning)
+            snap = Snapshot(
+                label, snapshot_type=snapshot_type, num_qubits=len(qubits), params=params
+            )


We shouldn't really do this in general; it just slows things down for no real gain. The stacklevel of the Snapshot warning should be set correctly such that the QuantumCircuit.snapshot method is "blamed", which will mean that the inner warning is not shown to users.

In that case it would show the deprecations warnings of both QC.snapshot and Snapshot or only the first?

The standard Python warning filters only show DeprecationWarnings if the stacklevel causes the "blamed" code to be in the module __main__ (the name for the script file being executed / code typed into the interpreter / Jupyter cells / etc). If the stack level of Snapshot's warning is set correctly, then the warning will blame the QuantumCircuit.snapshot method, whose module is qiskit.circuit.quantumcircuit, and so it won't be shown to users.

jakelishman · 2023-09-29T10:19:43Z

qiskit/circuit/quantumcircuit.py

+# isometry is an alias for iso
+QuantumCircuit.isometry = QuantumCircuit.iso


Not important at all, just saying: it might have been a shade cleaner to do this within the definition of QuantumCircuit -

class QuantumCircuit: def iso(self, ...): ... # isometry is an alias for iso isometry = iso

jakelishman · 2023-09-29T10:30:48Z

qiskit/synthesis/discrete_basis/gate_sequence.py

-from qiskit.extensions import UnitaryGate
+from qiskit.circuit.library.generalized_gates.unitary import UnitaryGate


Not too important, but imo this is is too specific an import - the documented location is qiskit.circuit.library, and hyperspecific import locations like this are part of the reason it's difficult to reorganise code in the future. If it doesn't import without the hyperspecificity, it's a strong sign that the objects have been put in the wrong place, and there are true cyclic-import problems.

This might again be a side effect of Pylint's cyclic import complaints...

Yeah, I'm saying that in this case, this would be pylint flagging something that's actually a real problem with our logical organisation - generalized_gates should depend on standard_gates, not vice versa. UnitaryGate is a core gate; it's used in the definition of Gate itself, so it probably would have been better for it to be given special treatment in the hierarchy, such as being in the top level of qiskit.circuit.library or the like.

jakelishman · 2023-09-29T10:33:38Z

releasenotes/notes/deprecate-extensions-d7ab3fca19962e2e.yaml

+    To streamline the structure of Qiskit's gates and operations, the :mod:`qiskit.extensions`
+    module is pending deprecation and will be deprecated in a future release.
+    The following objects have been moved to :mod:`qiskit.circuit.library`


All of qiskit.circuit.library is accessible from qiskit.extensions as well via a star import - it might have been good to mention that all not-immediately-deprecated gates from qiskit.extensions should be imported from qiskit.circuit.library.

* big moves, import still works * most tests pass (some I cannot seem to run locally) * fix tests -- how to remove DiagonalGate? * typehints and docs * more type hints * Deprecate SQU * deprecate Snapshot * Fix missing future annotations import * minimize deprecation effort * Change to pending deprecation, no exact-location import supported * fix MCG<->MGC typo and snapshot deprecation * fix pylint, try fixing docs * remove gates from extensions toctree * Add reno, fully deprecate SQU and Snapshot * Apply Sasha's review comments - fix usage of .squ and .snapshot w/o import - fix docstring usage of extensions - fix tests * capture snapshot deprecation warning * review comments - capture warning of SQU - update reno to explicitly mention pending deprecation, add DiagonalGate and ExtensionError * missed `diagonal` method --------- Co-authored-by: Alexander Ivrii <[email protected]>

) ### Summary After `qiskit.extensions` was deprecated in Qiskit/qiskit#10725, this PR updates the path of `HamiltonianGate` so tests against Qiskit main pass again. This also adds `atol` and `rtol` tolerance parameters to `PulseBackend` for speeding up slow tests.

…skit-community#1280) ### Summary After `qiskit.extensions` was deprecated in Qiskit/qiskit#10725, this PR updates the path of `HamiltonianGate` so tests against Qiskit main pass again. This also adds `atol` and `rtol` tolerance parameters to `PulseBackend` for speeding up slow tests.

) ### Summary After `qiskit.extensions` was deprecated in Qiskit/qiskit#10725, this PR updates the path of `HamiltonianGate` so tests against Qiskit main pass again. This also adds `atol` and `rtol` tolerance parameters to `PulseBackend` for speeding up slow tests. (cherry picked from commit 73d0a03) # Conflicts: # qiskit_experiments/test/__init__.py # test/library/calibration/test_half_angle.py # test/library/calibration/test_rough_amplitude.py

Cryoris added 8 commits August 18, 2023 12:11

big moves, import still works

29cc524

most tests pass (some I cannot seem to run locally)

9e000bb

fix tests -- how to remove DiagonalGate?

1afc35c

typehints and docs

5fe1a8b

more type hints

4ffea01

Deprecate SQU

ec48a1b

deprecate Snapshot

90ffaf2

Merge branch 'main' into deprecate-extensions

3a988da

Cryoris requested review from ikkoham, t-imamichi, a team, nonhermitian, alexanderivrii, ShellyGarion, jyu00 and woodsp-ibm as code owners August 29, 2023 12:48

Cryoris added this to the 0.45.0 milestone Aug 29, 2023

Cryoris commented Aug 29, 2023

View reviewed changes

qiskit/circuit/library/generalized_gates/mcg_up_to_diagonal.py Outdated Show resolved Hide resolved

Cryoris commented Aug 29, 2023

View reviewed changes

qiskit/circuit/library/data_preparation/initializer.py Show resolved Hide resolved

Fix missing future annotations import

dd47bde

jakelishman reviewed Aug 29, 2023

View reviewed changes

Cryoris added 2 commits August 30, 2023 09:03

minimize deprecation effort

f9112a3

Merge branch 'main' into deprecate-extensions

26e0683

ShellyGarion linked an issue Sep 1, 2023 that may be closed by this pull request

Deprecate qiskit.extensions #6861

Closed

Change to pending deprecation, no exact-location import supported

5f672b7

Cryoris requested a review from ElePT September 22, 2023 08:17

ElePT reviewed Sep 22, 2023

View reviewed changes

qiskit/circuit/quantumcircuit.py Outdated Show resolved Hide resolved

releasenotes/notes/deprecate-extensions-d7ab3fca19962e2e.yaml Outdated Show resolved Hide resolved

ShellyGarion reviewed Sep 26, 2023

View reviewed changes

releasenotes/notes/deprecate-extensions-d7ab3fca19962e2e.yaml Outdated Show resolved Hide resolved

Cryoris added 2 commits September 28, 2023 11:57

review comments

80ace24

- capture warning of SQU - update reno to explicitly mention pending deprecation, add DiagonalGate and ExtensionError

missed diagonal method

e2e7807

Merge branch 'main' into deprecate-extensions

4bd902b

alexanderivrii enabled auto-merge September 28, 2023 15:43

alexanderivrii approved these changes Sep 29, 2023

View reviewed changes

alexanderivrii added this pull request to the merge queue Sep 29, 2023

Merged via the queue into Qiskit:main with commit 35d0936 Sep 29, 2023
14 checks passed

jakelishman reviewed Sep 29, 2023

View reviewed changes

Cryoris deleted the deprecate-extensions branch September 29, 2023 13:49

coruscating mentioned this pull request Oct 1, 2023

Update HamiltonianGate path and add tolerance to PulseBackend qiskit-community/qiskit-experiments#1280

Merged

evmckinney9 mentioned this pull request Oct 6, 2023

Deprecated qiskit.extensions.unitary CQCL/pytket-qiskit#184

Closed

ShellyGarion mentioned this pull request Oct 22, 2023

Migrate transpiler/synthesis #11079

Closed

ElePT added the Changelog: Deprecation Include in "Deprecated" section of changelog label Nov 1, 2023

This was referenced Dec 26, 2023

Deprecate qiskit/transpiler/synthesis and move to qiskit/synthesis #11426

Merged

Deprecate qiskit/quantum_info/synthesis and move to qiskit/synthesis #11460

Merged

Cryoris mentioned this pull request Jan 8, 2024

Remove usage of qiskit.extensions Qiskit/qiskit-aer#2023

Merged

Cryoris mentioned this pull request Jan 23, 2024

QuantumCircuit initialize() links to StatePreparation and Initialize need fixing #11611

Closed

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deprecate `qiskit.extensions` #10725

Deprecate `qiskit.extensions` #10725

Cryoris commented Aug 29, 2023 •

edited

Loading

qiskit-bot commented Aug 29, 2023

Cryoris Aug 29, 2023

jakelishman Aug 29, 2023

Cryoris Sep 6, 2023

ShellyGarion Sep 11, 2023 •

edited

Loading

alexanderivrii Sep 18, 2023

Cryoris Aug 29, 2023

Cryoris Aug 29, 2023

jakelishman Aug 29, 2023

coveralls commented Aug 30, 2023 •

edited

Loading

alexanderivrii commented Sep 28, 2023

jakelishman left a comment

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

Cryoris Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

Cryoris Sep 29, 2023

jakelishman Sep 29, 2023

Cryoris Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023

Cryoris Sep 29, 2023

jakelishman Sep 29, 2023

jakelishman Sep 29, 2023


		# pylint: disable=cyclic-import
		from ..standard_gates import XGate, YGate, ZGate, HGate, TGate, TdgGate, SGate, SdgGate

		# isometry is an alias for iso
		QuantumCircuit.isometry = QuantumCircuit.iso

		from qiskit.extensions import UnitaryGate
		from qiskit.circuit.library.generalized_gates.unitary import UnitaryGate

Deprecate qiskit.extensions #10725

Deprecate qiskit.extensions #10725

Conversation

Cryoris commented Aug 29, 2023 • edited Loading

Summary

Details and comments

Moved to generalized gates

Moved to data preparation

Moved to circuit library root:

Deprecated:

Monkey-patched circuit methods:

qiskit-bot commented Aug 29, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion Sep 11, 2023 • edited Loading

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

coveralls commented Aug 30, 2023 • edited Loading

Pull Request Test Coverage Report for Build 6248054115

💛 - Coveralls

alexanderivrii commented Sep 28, 2023

jakelishman 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

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

Deprecate `qiskit.extensions` #10725

Deprecate `qiskit.extensions` #10725

Cryoris commented Aug 29, 2023 •

edited

Loading

ShellyGarion Sep 11, 2023 •

edited

Loading

coveralls commented Aug 30, 2023 •

edited

Loading