Merge pull request #328 from Refactor Gate class (2)

The original PR #325 was split into 2, for the previous set of changes look at that PR description.

- Defined `__slots__` for all the Abstract Gate classes and standard gate classes for better memory efficiency and faster lookup time.

- Added boolean `is_controlled`, `is_parametric` methods to the `Gate` class.

- Added the concept and implementation of namespaces for operations. This is done because at several places earlier gate.name was being used for comparison. Each operation (gate for now) must now be defined in a namespace or if it is a temporary gate, namespace can be set to None. This allows the user to define a faulty version of standard gates or follow their own convention for certain Parametric gates. The concept of namespace is much broader. Currently the parent namespace is "std", under it only "gates" is set as of now. In future we can make other namespaces under "std" like for Arithmetic Ops, Ansatz Ops etc. For the idea of Ops look at #263 (comment) Though it hasn't been implemented yet. In a way std namespace will work like a standard library for different operations and the user can also define their own implementation for operations in a different namespace.

- Added caching in `get_qobj` method for standard gates. This is done for two reasons.
```
@staticmethod
def get_qobj() -> Qobj:
    return Qobj([[1, 0], [0, -1]])
```
If you run it multiple times and check `id()` for each obj, they will be different. This leads to higher memory consumption for large circuit simulations, even though all of them represent the Z gate's qobj in this case. Additonally different qobjs will each need to be garbage collected. Memory and lookup are an even larger bottleneck in VQA circuits where several times many gates share the same parameter.  

- Added `dtype` to `get_qobj(dtype="dense")` method, . This might be useful if the circuit simulation is run on a different backend like JAX, CUDA.

- Made `Gate` non initialised by default i.e. `__init__` raise will raise an Error. Obviously`ParametricGate` and its controlled versions are initialisable. This makes sense because target, controls have been removed from gates and `x1=X()`, `x2=X()` now represent the same thing. Also good from a memory point of view.

- Added `Sdag`, `Tdag`, `SQRTXdag`, `ISWAPdag`, `SQRTSWAPdag`, `BERKELEYdag` to the standard gates. They have been added to the documentation table and in the circuit draw (colour config for them).

- Added `inverse` method for `Gate` class. Also implemented inverse for all standard gates and tests for the same. For controlled gates, the inverse is auto calculated based on the target gate. Closes #301 

- Renamed `unitary_gate` to `get_unitary_gate` and added checks for all the input arguments. 

- The control value for a gate is now baked into the control gate itself. The user can always generate his own version of controlled gate e.g. `controlled(gates.X, num_ctrl_qubits=2, control_value=0b10)`. For more detail check out #308 (comment)

- For all Controlled gates, the (target_gate, num_ctrl_qubit, ctrl_value) is used as another key in the namespace to reference that controlled gate. This is done in order to prevent regeneration of the controlled gate class for a given target gate with known (num_ctrl_qubit, ctrl_value). Since the namespace is used by default, there is no overhead.

- Renamed `controlled_gate` to `controlled_gate_unitary` and resolved the bug which didn't allow for generating the correct qobj if number of controls > 1.

- Added gate equivalence checking for `ParametricGate`, `ControlledGate`. And added `__eq__`, `__hash__` in Gate metaclass as well. Replaced gate.name = "X" search with gate == X now.

- Corrected inconsistency between Gate and Type[Gate] from previous PRs. Gate refers to an instantiated object while type[Gate] refers to a Gate class or subclass in accordance with Python's typehinting.

- Added several more checks in `__init_subclass__`, `add_gate` method.

- Added tests in `test_gates.py` and `test_circuit.py` for mostly incorrect cases like num_qubits being negative etc., which should raise an Error. Since Gates are used throughout the codebase, their normal usage is already mostly covered.

**Maintainence and Bug Fixes:**

- `gate_product` had a clear bug that `tensor_list` was not defined but was being used, fixed that and also moved the entire `gate_product` logic to operations, which was split in circuit-simulator utils, operations but was always being imported from operations as per `__init__` even in `mat_mul_simulator.py`.

- Removed deprecated arguments and functions that were deprecated 3 years back. This was checked in the git commit history.

- Remove mutable default values from function arguments across the codebase, this is a common Python bug. Something like targets = [], can often lead to an error. For details check out this blog https://medium.com/@matbrizolla/beware-of-the-hidden-trap-understanding-mutable-default-arguments-in-python-d10e8b0a7b72

- Corrected several `isInstance` checks in the codebase. `Iterable` and `Sequence` were being used interchangeably at several places especially in qasm. This led to several unexpected behaviours and errors during gate refactoring.

- Moved pytest.ini to the root, this is what pytest themselves recommend https://docs.pytest.org/en/stable/explanation/goodpractices.html#choosing-a-test-layout-import-rules . The reason was that placing pytest.ini in `tests/` led to certain sys path issues, for reference check https://docs.pytest.org/en/stable/explanation/pythonpath.html. This caused an error when standard gates were designated to a namespace and pytest was trying to redefine them and reassign them to the same namespace.

*Edit: Some more changes*

- Separated IDLE (meant for Pulse level simulation) and Identity gate (standard Identity matrix).

- In Pulse compiler instead of `gate.name`, `gates` are themselves being used as keys.

- Removed expand argument from `inverse()` in Parametric Gates.

- Renamed `controlled` to `get_controlled_gate`.

Author: BoxiLi

doc/pulse-paper/qft.py

@@ -42,9 +42,9 @@ def get_control_latex(model):
     num_qubits = model.num_qubits
     num_coupling = model._get_num_coupling()
     return [
-        {f"sx{m}": r"$\sigma_x^{}$".format(m) for m in range(num_qubits)},
-        {f"sz{m}": r"$\sigma_z^{}$".format(m) for m in range(num_qubits)},
-        {f"g{m}": r"$g_{}$".format(m) for m in range(num_coupling)},
+        {f"sx{m}": rf"$\sigma_x^{m}$" for m in range(num_qubits)},
+        {f"sz{m}": rf"$\sigma_z^{m}$" for m in range(num_qubits)},
+        {f"g{m}": rf"$g_{m}$" for m in range(num_coupling)},
     ]
 
 

doc/source/apidoc/qutip_qip.operations.rst

@@ -50,6 +50,6 @@ qutip\_qip.operations
 
    .. autosummary::
 
-      controlled_gate
+      controlled_gate_unitary
       expand_operator
       gate_sequence_product

doc/source/qip-basics.rst

@@ -139,38 +139,51 @@ The pre-defined gates for the class :class:`~.operations.Gate` are shown in the
 ====================  ========================================
 Gate name                           Description
 ====================  ========================================
-"RX"                  Rotation around x axis
-"RY"                  Rotation around y axis
-"RZ"                  Rotation around z axis
-"R"                   Arbitrary single qubit rotation
 "X"                   Pauli-X gate
 "Y"                   Pauli-Y gate
 "Z"                   Pauli-Z gate
+"H"                   Hadamard gate
 "S"                   Single-qubit rotation or Z90
+"Sdag"                Inverse of S gate
 "T"                   Square root of S gate
+"Tdag"                Inverse of T gate
 "SQRTX"               Square root of X gate
-"H"                   Hadamard gate
-"PHASEGATE"           Add a phase one the state 1
-"CRX"                 Controlled rotation around x axis
-"CRY"                 Controlled rotation around y axis
-"CRZ"                 Controlled rotation around z axis
-"CX"                  Controlled X gate (also called CNOT)
+"SQRTXdag"            Inverse of SQRTX gate
+"RX"                  Rotation around x axis
+"RY"                  Rotation around y axis
+"RZ"                  Rotation around z axis
+"PHASE"               Adds a relative phase to ket 1
+"R"                   Arbitrary single qubit rotation
+"QASMU"               U rotation gate used as a primitive in the QASM standard
+"CX"                  (CNOT) Controlled X gate
 "CY"                  Controlled Y gate
 "CZ"                  Controlled Z gate
+"CH"                  Controlled H gate
 "CS"                  Controlled S gate
+"CSdag"               Controlled Sdag gate
 "CT"                  Controlled T gate
-"CPHASE"              Controlled phase gate
-"QASMU"               U rotation gate used as a primitive in the QASM standard
-"BERKELEY"            Berkeley gate
-"SWAPalpha"           SWAPalpha gate
+"CTdag"               Controlled Tdag gate
+"CRX"                 Controlled rotation around x axis
+"CRY"                 Controlled rotation around y axis
+"CRZ"                 Controlled rotation around z axis
+"CPHASE"              Controlled Phase gate
+"CQASMU"              Controlled QASMU gate
 "SWAP"                Swap the states of two qubits
 "ISWAP"               Swap gate with additional phase for 01 and 10 states
+"ISWAPdag"            Inverse of ISWAP gate
 "SQRTSWAP"            Square root of the SWAP gate
+"SQRTSWAPdag"         Inverse of SQRTSWAP gate
 "SQRTISWAP"           Square root of the ISWAP gate
+"SQRTISWAPdag"        Inverse of SQRTISWAP gate
+"BERKELEY"            Berkeley gate
+"BERKELEYdag"         Inverse of BERKELEY gate
+"SWAPALPHA"           SWAPALPHA gate
 "MS"                  Mølmer-Sørensen gate
+"RZX"                 RZX gate
+"TOFFOLI"             (CCX) Toffoli gate
 "FREDKIN"             Fredkin gate
-"TOFFOLI"             Toffoli gate
-"GLOBALPHASE"         Global phase
+"GLOBALPHASE"         Global phase gate
+"IDENTITY"            Identity gate
 ====================  ========================================
 
 For some of the gates listed above, :class:`.QubitCircuit` also has a primitive :func:`.QubitCircuit.resolve_gates()` method that decomposes them into elementary gate sets such as CX or SWAP with single-qubit gates (RX, RY and RZ). However, this method is not fully optimized. It is very likely that the depth of the circuit can be further reduced by merging quantum gates. It is required that the gate resolution be carried out before the measurements to the circuit are added.

tests/pytest.ini pytest.initests/pytest.ini renamed to pytest.ini

@@ -1,22 +1,19 @@
 [pytest]
 markers =
     slow: Mark a test as taking a long time to run, and so can be skipped with `pytest -m "not slow"`.
-    repeat(n): Repeat the given test 'n' times.
     requires_cython: Mark that the given test requires Cython to be installed.  Such tests will be skipped if Cython is not available.
+
 filterwarnings =
     error
     ; ImportWarning: PyxImporter.find_spec() not found
     ignore:PyxImporter:ImportWarning
-    ; DeprecationWarning: Please use `upcast` from the `scipy.sparse` namespace
-    ignore::DeprecationWarning:qutip.fastsparse*:
+    ignore::UserWarning:
     ignore:matplotlib not found:UserWarning
     ignore:the imp module is deprecated in favour of importlib:DeprecationWarning
     ignore:Dedicated options class are no longer needed, options should be passed as dict to solvers.:FutureWarning
     ignore::DeprecationWarning:qiskit.utils.algorithm_globals:
-    # Deprecation warning for python = 3.9 with matplotlib 3.9.4
-    ignore:'mode' parameter is deprecated
     # Deprecation warning for scipy disp interface, will be removed in scipy 1.18
     ignore:.*`disp` and `iprint` options.*L-BFGS-B.*deprecated.*:DeprecationWarning
 
-
-
+pythonpath = src
+testpaths = tests

src/qutip_qip/algorithms/bit_flip.py

@@ -1,5 +1,5 @@
 from qutip_qip.circuit import QubitCircuit
-from qutip_qip.operations import CX, TOFFOLI, X
+from qutip_qip.operations.gates import CX, TOFFOLI, X
 
 
 class BitFlipCode:

src/qutip_qip/algorithms/phase_flip.py

@@ -1,5 +1,5 @@
 from qutip_qip.circuit import QubitCircuit
-from qutip_qip.operations import CX, H
+from qutip_qip.operations.gates import CX, H
 
 
 class PhaseFlipCode:

src/qutip_qip/algorithms/qft.py

@@ -3,10 +3,11 @@
 """
 
 import numpy as np
-from qutip_qip.operations import H, RZ, CX, CPHASE, SWAP, expand_operator
-from qutip_qip.circuit import QubitCircuit
 from qutip import Qobj
+from qutip_qip.circuit import QubitCircuit
 from qutip_qip.decompose import decompose_one_qubit_gate
+from qutip_qip.operations import expand_operator
+from qutip_qip.operations.gates import H, RZ, CX, CPHASE, SWAP
 
 
 def qft(N=1):
@@ -66,7 +67,7 @@ def qft_steps(N=1, swapping=True):
             for j in range(i):
                 U_step_list.append(
                     expand_operator(
-                        CPHASE(np.pi / (2 ** (i - j))).get_qobj(),
+                        CPHASE(theta=np.pi / (2 ** (i - j))).get_qobj(),
                         dims=[2] * N,
                         targets=[i, j],
                     )
@@ -113,7 +114,10 @@ def qft_gate_sequence(N=1, swapping=True, to_cnot=False):
             for j in range(i):
                 if not to_cnot:
                     qc.add_gate(
-                        CPHASE(np.pi / (2 ** (i - j)), arg_label=r"{\pi/2^{%d}}" % (i - j)),
+                        CPHASE(
+                            theta=np.pi / (2 ** (i - j)),
+                            arg_label=r"{\pi/2^{%d}}" % (i - j),
+                        ),
                         targets=[j],
                         controls=[i],
                     )
@@ -136,6 +140,6 @@ def _cphase_to_cnot(targets, controls, arg_value, qc: QubitCircuit):
     qc.add_gate(decomposed_gates[4], targets=targets)
     qc.add_gate(CX, targets=targets, controls=controls)
     qc.add_gate(RZ(arg_value / 2), targets=controls)
-    gate = decomposed_gates[7]
-    gate.arg_value[0] += arg_value / 4
+    gate = decomposed_gates[7]  # This is a GLOBALPHASE Gate
+    gate.arg_value = gate.arg_value[0] + arg_value / 4
     qc.add_gate(gate, targets=targets)

src/qutip_qip/algorithms/qpe.py

@@ -1,7 +1,8 @@
 import numpy as np
-from qutip_qip.circuit import QubitCircuit
 from qutip_qip.algorithms import qft_gate_sequence
-from qutip_qip.operations import custom_gate_factory, controlled_gate_factory, H
+from qutip_qip.circuit import QubitCircuit
+from qutip_qip.operations import get_unitary_gate, get_controlled_gate
+from qutip_qip.operations.gates import H
 
 
 def qpe(U, num_counting_qubits, target_qubits=None, to_cnot=False):
@@ -41,7 +42,7 @@ def qpe(U, num_counting_qubits, target_qubits=None, to_cnot=False):
         target_qubits = list(
             range(num_counting_qubits, num_counting_qubits + num_target_qubits)
         )
-    elif isinstance(target_qubits, int):
+    elif type(target_qubits) is int:
         target_qubits = [target_qubits]
         num_target_qubits = 1
     else:
@@ -61,11 +62,11 @@ def qpe(U, num_counting_qubits, target_qubits=None, to_cnot=False):
         U_power = U if power == 1 else U**power
 
         # Add controlled-U^power gate
-        controlled_u = controlled_gate_factory(
-            gate=custom_gate_factory(
-                gate_name="U^power gate",
+        controlled_u = get_controlled_gate(
+            gate=get_unitary_gate(
+                gate_name=f"U^{power}",
                 U=U_power,
-            )(),
+            ),
         )
         qc.add_gate(controlled_u, targets=target_qubits, controls=[i])
 

src/qutip_qip/circuit/__init__.py

@@ -1,40 +1,12 @@
 """Circuit representation and simulation at the gate level."""
 
-import warnings
-
 from .instruction import (
     CircuitInstruction,
     GateInstruction,
     MeasurementInstruction,
 )
 from .simulator import CircuitResult, CircuitSimulator
 from .circuit import QubitCircuit
-from qutip_qip.operations import Gate, Measurement
-
-
-def _add_deprecation(fun, msg):
-    def newfun(*args, **kwargs):
-        warnings.warn(
-            msg,
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return fun(*args, **kwargs)
-
-    return newfun
-
-
-Gate = _add_deprecation(
-    Gate,
-    "The class Gate has been moved to qutip_qip.operations."
-    "Please use update the import statement.\n",
-)
-Measurement = _add_deprecation(
-    Measurement,
-    "The class Measurement has been moved to qutip_qip.operations."
-    "Please use update the import statement.\n",
-)
-
 
 __all__ = [
     "CircuitSimulator",