6054434474

Committed 01 Sep 2023 08:10PM UTC coverage: 87.263% (-0.004%) from 87.267%

Build # 6054434474

Build Type

push

github

Committed by

web-flow

Commit Message

Upgrade to qiskit-sphinx-theme 1.16 (#10739) (#10762)

* Upgrade to qiskit-sphinx-theme 1.16

* Use stable release

(cherry picked from commit fed6a7a15)

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

Run Details

74130 of 84950 relevant lines covered (87.26%)

60831.55 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

93.75

/qiskit/extensions/unitary.py

# This code is part of Qiskit.
#
# (C) Copyright IBM 2017, 2019.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE.txt file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Arbitrary unitary circuit instruction.
"""

import numpy

from qiskit.circuit import Gate, ControlledGate
from qiskit.circuit import QuantumCircuit
from qiskit.circuit import QuantumRegister, Qubit
from qiskit.circuit.exceptions import CircuitError
from qiskit.circuit._utils import _compute_control_matrix
from qiskit.circuit.library.standard_gates import U3Gate
from qiskit.extensions.quantum_initializer import isometry
from qiskit.quantum_info.operators.predicates import matrix_equal
from qiskit.quantum_info.operators.predicates import is_unitary_matrix
from qiskit.quantum_info.synthesis.one_qubit_decompose import OneQubitEulerDecomposer
from qiskit.quantum_info.synthesis.two_qubit_decompose import two_qubit_cnot_decompose
from qiskit.extensions.exceptions import ExtensionError

_DECOMPOSER1Q = OneQubitEulerDecomposer("U3")


class UnitaryGate(Gate):
    """Class quantum gates specified by a unitary matrix.

    Example:

        We can create a unitary gate from a unitary matrix then add it to a
        quantum circuit. The matrix can also be directly applied to the quantum
        circuit, see :meth:`.QuantumCircuit.unitary`.

        .. code-block:: python

            from qiskit import QuantumCircuit
            from qiskit.extensions import UnitaryGate

            matrix = [[0, 0, 0, 1],
                      [0, 0, 1, 0],
                      [1, 0, 0, 0],
                      [0, 1, 0, 0]]
            gate = UnitaryGate(matrix)

            circuit = QuantumCircuit(2)
            circuit.append(gate, [0, 1])
    """

    def __init__(self, data, label=None):
        """Create a gate from a numeric unitary matrix.

        Args:
            data (matrix or Operator): unitary operator.
            label (str): unitary name for backend [Default: None].

        Raises:
            ExtensionError: if input data is not an N-qubit unitary operator.
        """
        if hasattr(data, "to_matrix"):
            # If input is Gate subclass or some other class object that has
            # a to_matrix method this will call that method.
            data = data.to_matrix()
        elif hasattr(data, "to_operator"):
            # If input is a BaseOperator subclass this attempts to convert
            # the object to an Operator so that we can extract the underlying
            # numpy matrix from `Operator.data`.
            data = data.to_operator().data
        # Convert to numpy array in case not already an array
        data = numpy.array(data, dtype=complex)
        # Check input is unitary
        if not is_unitary_matrix(data):
            raise ExtensionError("Input matrix is not unitary.")
        # Check input is N-qubit matrix
        input_dim, output_dim = data.shape
        num_qubits = int(numpy.log2(input_dim))
        if input_dim != output_dim or 2**num_qubits != input_dim:
            raise ExtensionError("Input matrix is not an N-qubit operator.")

        # Store instruction params
        super().__init__("unitary", num_qubits, [data], label=label)

    def __eq__(self, other):
        if not isinstance(other, UnitaryGate):
            return False
        if self.label != other.label:
            return False
        # Should we match unitaries as equal if they are equal
        # up to global phase?
        return matrix_equal(self.params[0], other.params[0], ignore_phase=True)

    def __array__(self, dtype=None):
        """Return matrix for the unitary."""
        # pylint: disable=unused-argument
        return self.params[0]

    def inverse(self):
        """Return the adjoint of the unitary."""
        return self.adjoint()

    def conjugate(self):
        """Return the conjugate of the unitary."""
        return UnitaryGate(numpy.conj(self.to_matrix()))

    def adjoint(self):
        """Return the adjoint of the unitary."""
        return self.transpose().conjugate()

    def transpose(self):
        """Return the transpose of the unitary."""
        return UnitaryGate(numpy.transpose(self.to_matrix()))

    def _define(self):
        """Calculate a subcircuit that implements this unitary."""
        if self.num_qubits == 1:
            q = QuantumRegister(1, "q")
            qc = QuantumCircuit(q, name=self.name)
            theta, phi, lam, global_phase = _DECOMPOSER1Q.angles_and_phase(self.to_matrix())
            qc._append(U3Gate(theta, phi, lam), [q[0]], [])
            qc.global_phase = global_phase
            self.definition = qc
        elif self.num_qubits == 2:
            self.definition = two_qubit_cnot_decompose(self.to_matrix())
        else:
            from qiskit.quantum_info.synthesis.qsd import (  # pylint: disable=cyclic-import
                qs_decomposition,
            )

            self.definition = qs_decomposition(self.to_matrix())

    def control(self, num_ctrl_qubits=1, label=None, ctrl_state=None):
        """Return controlled version of gate

        Args:
            num_ctrl_qubits (int): number of controls to add to gate (default=1)
            label (str): optional gate label
            ctrl_state (int or str or None): The control state in decimal or as a
                bit string (e.g. '1011'). If None, use 2**num_ctrl_qubits-1.

        Returns:
            UnitaryGate: controlled version of gate.

        Raises:
            QiskitError: Invalid ctrl_state.
            ExtensionError: Non-unitary controlled unitary.
        """
        mat = self.to_matrix()
        cmat = _compute_control_matrix(mat, num_ctrl_qubits, ctrl_state=None)
        iso = isometry.Isometry(cmat, 0, 0)
        return ControlledGate(
            "c-unitary",
            num_qubits=self.num_qubits + num_ctrl_qubits,
            params=[mat],
            label=label,
            num_ctrl_qubits=num_ctrl_qubits,
            definition=iso.definition,
            ctrl_state=ctrl_state,
            base_gate=self.copy(),
        )

    def _qasm2_decomposition(self):
        """Return an unparameterized version of ourselves, so the OQ2 exporter doesn't choke on the
        non-standard things in our `params` field."""
        out = self.definition.to_gate()
        out.name = self.name
        return out

    def validate_parameter(self, parameter):
        """Unitary gate parameter has to be an ndarray."""
        if isinstance(parameter, numpy.ndarray):
            return parameter
        else:
            raise CircuitError(f"invalid param type {type(parameter)} in gate {self.name}")


def unitary(self, obj, qubits, label=None):
    """Apply unitary gate specified by ``obj`` to ``qubits``.

    Args:
        obj (matrix or Operator): unitary operator.
        qubits (Union[int, Tuple[int]]): The circuit qubits to apply the
            transformation to.
        label (str): unitary name for backend [Default: None].

    Returns:
        QuantumCircuit: The quantum circuit.

    Raises:
        ExtensionError: if input data is not an N-qubit unitary operator.

    Example:

        Apply a gate specified by a unitary matrix to a quantum circuit

        .. code-block:: python

            from qiskit import QuantumCircuit
            matrix = [[0, 0, 0, 1],
                      [0, 0, 1, 0],
                      [1, 0, 0, 0],
                      [0, 1, 0, 0]]
            circuit = QuantumCircuit(2)
            circuit.unitary(matrix, [0, 1])
    """
    gate = UnitaryGate(obj, label=label)
    if isinstance(qubits, QuantumRegister):
        qubits = qubits[:]
    # for single qubit unitary gate, allow an 'int' or a 'list of ints' as qubits.
    if gate.num_qubits == 1:
        if isinstance(qubits, (int, Qubit)) or len(qubits) > 1:
            qubits = [qubits]
    return self.append(gate, qubits, [])


QuantumCircuit.unitary = unitary

1	# This code is part of Qiskit.
2	#
3	# (C) Copyright IBM 2017, 2019.
4	#
5	# This code is licensed under the Apache License, Version 2.0. You may
6	# obtain a copy of this license in the LICENSE.txt file in the root directory
7	# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8	#
9	# Any modifications or derivative works of this code must retain this
10	# copyright notice, and modified files need to carry a notice indicating
11	# that they have been altered from the originals.
12
13	"""	1✔
14	Arbitrary unitary circuit instruction.
15	"""
16
17	import numpy	1✔
18
19	from qiskit.circuit import Gate, ControlledGate	1✔
20	from qiskit.circuit import QuantumCircuit	1✔
21	from qiskit.circuit import QuantumRegister, Qubit	1✔
22	from qiskit.circuit.exceptions import CircuitError	1✔
23	from qiskit.circuit._utils import _compute_control_matrix	1✔
24	from qiskit.circuit.library.standard_gates import U3Gate	1✔
25	from qiskit.extensions.quantum_initializer import isometry	1✔
26	from qiskit.quantum_info.operators.predicates import matrix_equal	1✔
27	from qiskit.quantum_info.operators.predicates import is_unitary_matrix	1✔
28	from qiskit.quantum_info.synthesis.one_qubit_decompose import OneQubitEulerDecomposer	1✔
29	from qiskit.quantum_info.synthesis.two_qubit_decompose import two_qubit_cnot_decompose	1✔
30	from qiskit.extensions.exceptions import ExtensionError	1✔
31
32	_DECOMPOSER1Q = OneQubitEulerDecomposer("U3")	1✔
33
34
35	class UnitaryGate(Gate):	1✔
36	"""Class quantum gates specified by a unitary matrix.	1✔
37
38	Example:
39
40	We can create a unitary gate from a unitary matrix then add it to a
41	quantum circuit. The matrix can also be directly applied to the quantum
42	circuit, see :meth:`.QuantumCircuit.unitary`.
43
44	.. code-block:: python
45
46	from qiskit import QuantumCircuit
47	from qiskit.extensions import UnitaryGate
48
49	matrix = [[0, 0, 0, 1],
50	[0, 0, 1, 0],
51	[1, 0, 0, 0],
52	[0, 1, 0, 0]]
53	gate = UnitaryGate(matrix)
54
55	circuit = QuantumCircuit(2)
56	circuit.append(gate, [0, 1])
57	"""
58
59	def __init__(self, data, label=None):	1✔
60	"""Create a gate from a numeric unitary matrix.
61
62	Args:
63	data (matrix or Operator): unitary operator.
64	label (str): unitary name for backend [Default: None].
65
66	Raises:
67	ExtensionError: if input data is not an N-qubit unitary operator.
68	"""
69	if hasattr(data, "to_matrix"):	1✔
70	# If input is Gate subclass or some other class object that has
71	# a to_matrix method this will call that method.
72	data = data.to_matrix()	1✔
73	elif hasattr(data, "to_operator"):	1✔
74	# If input is a BaseOperator subclass this attempts to convert
75	# the object to an Operator so that we can extract the underlying
76	# numpy matrix from `Operator.data`.
77	data = data.to_operator().data	×
78	# Convert to numpy array in case not already an array
79	data = numpy.array(data, dtype=complex)	1✔
80	# Check input is unitary
81	if not is_unitary_matrix(data):	1✔
82	raise ExtensionError("Input matrix is not unitary.")	1✔
83	# Check input is N-qubit matrix
84	input_dim, output_dim = data.shape	1✔
85	num_qubits = int(numpy.log2(input_dim))	1✔
86	if input_dim != output_dim or 2**num_qubits != input_dim:	1✔
87	raise ExtensionError("Input matrix is not an N-qubit operator.")	×
88
89	# Store instruction params
90	super().__init__("unitary", num_qubits, [data], label=label)	1✔
91
92	def __eq__(self, other):	1✔
93	if not isinstance(other, UnitaryGate):	1✔
94	return False	×
95	if self.label != other.label:	1✔
96	return False	×
97	# Should we match unitaries as equal if they are equal
98	# up to global phase?
99	return matrix_equal(self.params[0], other.params[0], ignore_phase=True)	1✔
100
101	def __array__(self, dtype=None):	1✔
102	"""Return matrix for the unitary."""
103	# pylint: disable=unused-argument
104	return self.params[0]	1✔
105
106	def inverse(self):	1✔
107	"""Return the adjoint of the unitary."""
108	return self.adjoint()	1✔
109
110	def conjugate(self):	1✔
111	"""Return the conjugate of the unitary."""
112	return UnitaryGate(numpy.conj(self.to_matrix()))	1✔
113
114	def adjoint(self):	1✔
115	"""Return the adjoint of the unitary."""
116	return self.transpose().conjugate()	1✔
117
118	def transpose(self):	1✔
119	"""Return the transpose of the unitary."""
120	return UnitaryGate(numpy.transpose(self.to_matrix()))	1✔
121
122	def _define(self):	1✔
123	"""Calculate a subcircuit that implements this unitary."""
124	if self.num_qubits == 1:	1✔
125	q = QuantumRegister(1, "q")	1✔
126	qc = QuantumCircuit(q, name=self.name)	1✔
127	theta, phi, lam, global_phase = _DECOMPOSER1Q.angles_and_phase(self.to_matrix())	1✔
128	qc._append(U3Gate(theta, phi, lam), [q[0]], [])	1✔
129	qc.global_phase = global_phase	1✔
130	self.definition = qc	1✔
131	elif self.num_qubits == 2:	1✔
132	self.definition = two_qubit_cnot_decompose(self.to_matrix())	1✔
133	else:
134	from qiskit.quantum_info.synthesis.qsd import ( # pylint: disable=cyclic-import	1✔
135	qs_decomposition,
136	)
137
138	self.definition = qs_decomposition(self.to_matrix())	1✔
139
140	def control(self, num_ctrl_qubits=1, label=None, ctrl_state=None):	1✔
141	"""Return controlled version of gate
142
143	Args:
144	num_ctrl_qubits (int): number of controls to add to gate (default=1)
145	label (str): optional gate label
146	ctrl_state (int or str or None): The control state in decimal or as a
147	bit string (e.g. '1011'). If None, use 2**num_ctrl_qubits-1.
148
149	Returns:
150	UnitaryGate: controlled version of gate.
151
152	Raises:
153	QiskitError: Invalid ctrl_state.
154	ExtensionError: Non-unitary controlled unitary.
155	"""
156	mat = self.to_matrix()	1✔
157	cmat = _compute_control_matrix(mat, num_ctrl_qubits, ctrl_state=None)	1✔
158	iso = isometry.Isometry(cmat, 0, 0)	1✔
159	return ControlledGate(	1✔
160	"c-unitary",
161	num_qubits=self.num_qubits + num_ctrl_qubits,
162	params=[mat],
163	label=label,
164	num_ctrl_qubits=num_ctrl_qubits,
165	definition=iso.definition,
166	ctrl_state=ctrl_state,
167	base_gate=self.copy(),
168	)
169
170	def _qasm2_decomposition(self):	1✔
171	"""Return an unparameterized version of ourselves, so the OQ2 exporter doesn't choke on the
172	non-standard things in our `params` field."""
173	out = self.definition.to_gate()	1✔
174	out.name = self.name	1✔
175	return out	1✔
176
177	def validate_parameter(self, parameter):	1✔
178	"""Unitary gate parameter has to be an ndarray."""
179	if isinstance(parameter, numpy.ndarray):	1✔
180	return parameter	1✔
181	else:
182	raise CircuitError(f"invalid param type {type(parameter)} in gate {self.name}")	×
183
184
185	def unitary(self, obj, qubits, label=None):	1✔
186	"""Apply unitary gate specified by ``obj`` to ``qubits``.
187
188	Args:
189	obj (matrix or Operator): unitary operator.
190	qubits (Union[int, Tuple[int]]): The circuit qubits to apply the
191	transformation to.
192	label (str): unitary name for backend [Default: None].
193
194	Returns:
195	QuantumCircuit: The quantum circuit.
196
197	Raises:
198	ExtensionError: if input data is not an N-qubit unitary operator.
199
200	Example:
201
202	Apply a gate specified by a unitary matrix to a quantum circuit
203
204	.. code-block:: python
205
206	from qiskit import QuantumCircuit
207	matrix = [[0, 0, 0, 1],
208	[0, 0, 1, 0],
209	[1, 0, 0, 0],
210	[0, 1, 0, 0]]
211	circuit = QuantumCircuit(2)
212	circuit.unitary(matrix, [0, 1])
213	"""
214	gate = UnitaryGate(obj, label=label)	1✔
215	if isinstance(qubits, QuantumRegister):	1✔
216	qubits = qubits[:]	1✔
217	# for single qubit unitary gate, allow an 'int' or a 'list of ints' as qubits.
218	if gate.num_qubits == 1:	1✔
219	if isinstance(qubits, (int, Qubit)) or len(qubits) > 1:	1✔
220	qubits = [qubits]	1✔
221	return self.append(gate, qubits, [])	1✔
222
223
224	QuantumCircuit.unitary = unitary	1✔

Qiskit / qiskit / 6054434474

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous