qiskit 1.3.0b1__cp39-abi3-macosx_10_9_x86_64.whl

qiskit/synthesis/two_qubit/xx_decompose/utilities.py

@@ -0,0 +1,40 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021
+#
+# 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.
+
+"""
+Depository for generic utility snippets.
+"""
+
+from __future__ import annotations
+import warnings
+
+import numpy as np
+
+
+EPSILON = 1e-6  # Fraction(1, 1_000_000)
+
+
+# TODO: THIS IS A STOPGAP!!!
+def safe_arccos(numerator, denominator):
+    """
+    Computes arccos(n/d) with different (better?) numerical stability.
+    """
+    threshold = 0.005
+
+    if abs(numerator) > abs(denominator) and abs(numerator - denominator) < threshold:
+        return 0.0
+    elif abs(numerator) > abs(denominator) and abs(numerator + denominator) < threshold:
+        return np.pi
+    else:
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=RuntimeWarning)
+            return np.arccos(numerator / denominator)

qiskit/synthesis/two_qubit/xx_decompose/weyl.py

@@ -0,0 +1,133 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021
+#
+# 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.
+
+"""
+Simple circuit constructors for Weyl reflections.
+"""
+
+from __future__ import annotations
+import numpy as np
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit.library.standard_gates import RXGate, RYGate, RZGate
+
+
+reflection_options = {
+    "no reflection": ([1, 1, 1], 1, []),
+    "reflect XX, YY": ([-1, -1, 1], 1, [RZGate]),
+    "reflect XX, ZZ": ([-1, 1, -1], 1, [RYGate]),
+    "reflect YY, ZZ": ([1, -1, -1], 1, [RXGate]),
+}
+"""
+A table of available reflection transformations on canonical coordinates.
+Entries take the form
+
+    readable_name: (reflection scalars, global phase, [gate constructors]),
+
+where reflection scalars (a, b, c) model the map (x, y, z) |-> (ax, by, cz),
+global phase is a complex unit, and gate constructors are applied in sequence
+and by conjugation to the first qubit and are passed pi as a parameter.
+"""
+
+shift_options = {
+    "no shift": ([0, 0, 0], 1, []),
+    "Z shift": ([0, 0, 1], 1j, [RZGate]),
+    "Y shift": ([0, 1, 0], -1j, [RYGate]),
+    "Y,Z shift": ([0, 1, 1], 1, [RYGate, RZGate]),
+    "X shift": ([1, 0, 0], -1j, [RXGate]),
+    "X,Z shift": ([1, 0, 1], 1, [RXGate, RZGate]),
+    "X,Y shift": ([1, 1, 0], -1, [RXGate, RYGate]),
+    "X,Y,Z shift": ([1, 1, 1], -1j, [RXGate, RYGate, RZGate]),
+}
+"""
+A table of available shift transformations on canonical coordinates.  Entries
+take the form
+
+    readable name: (shift scalars, global phase, [gate constructors]),
+
+where shift scalars model the map
+
+    (x, y, z) |-> (x + a pi / 2, y + b pi / 2, z + c pi / 2) ,
+
+global phase is a complex unit, and gate constructors are applied to the first
+and second qubits and are passed pi as a parameter.
+"""
+
+
+def apply_reflection(reflection_name, coordinate):
+    """
+    Given a reflection type and a canonical coordinate, applies the reflection
+    and describes a circuit which enacts the reflection + a global phase shift.
+    """
+    reflection_scalars, reflection_phase_shift, source_reflection_gates = reflection_options[
+        reflection_name
+    ]
+    reflected_coord = [x * y for x, y in zip(reflection_scalars, coordinate)]
+    source_reflection = QuantumCircuit(2)
+    for gate in source_reflection_gates:
+        source_reflection.append(gate(np.pi), [0])
+
+    return reflected_coord, source_reflection, reflection_phase_shift
+
+
+def apply_shift(shift_name, coordinate):
+    """
+    Given a shift type and a canonical coordinate, applies the shift and
+    describes a circuit which enacts the shift + a global phase shift.
+    """
+    shift_scalars, shift_phase_shift, source_shift_gates = shift_options[shift_name]
+    shifted_coord = [np.pi / 2 * x + y for x, y in zip(shift_scalars, coordinate)]
+
+    source_shift = QuantumCircuit(2)
+    for gate in source_shift_gates:
+        source_shift.append(gate(np.pi), [0])
+        source_shift.append(gate(np.pi), [1])
+
+    return shifted_coord, source_shift, shift_phase_shift
+
+
+def canonical_rotation_circuit(first_index, second_index):
+    """
+    Given a pair of distinct indices 0 ≤ (first_index, second_index) ≤ 2,
+    produces a two-qubit circuit which rotates a canonical gate
+
+        a0 XX + a1 YY + a2 ZZ
+
+    into
+
+        a[first] XX + a[second] YY + a[other] ZZ .
+    """
+    conj = QuantumCircuit(2)
+
+    if (0, 1) == (first_index, second_index):
+        pass  # no need to do anything
+    elif (0, 2) == (first_index, second_index):
+        conj.rx(-np.pi / 2, [0])
+        conj.rx(np.pi / 2, [1])
+    elif (1, 0) == (first_index, second_index):
+        conj.rz(-np.pi / 2, [0])
+        conj.rz(-np.pi / 2, [1])
+    elif (1, 2) == (first_index, second_index):
+        conj.rz(np.pi / 2, [0])
+        conj.rz(np.pi / 2, [1])
+        conj.ry(np.pi / 2, [0])
+        conj.ry(-np.pi / 2, [1])
+    elif (2, 0) == (first_index, second_index):
+        conj.rz(np.pi / 2, [0])
+        conj.rz(np.pi / 2, [1])
+        conj.rx(np.pi / 2, [0])
+        conj.rx(-np.pi / 2, [1])
+    elif (2, 1) == (first_index, second_index):
+        conj.ry(np.pi / 2, [0])
+        conj.ry(-np.pi / 2, [1])
+
+    return conj

qiskit/synthesis/unitary/__init__.py

@@ -0,0 +1,13 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2023.
+#
+# 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.
+
+"""Module containing unitary synthesis methods."""

qiskit/synthesis/unitary/aqc/__init__.py

@@ -0,0 +1,177 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+
+r"""
+=====================================================================
+Approximate Quantum Compiler (:mod:`qiskit.synthesis.unitary.aqc`)
+=====================================================================
+
+.. currentmodule:: qiskit.synthesis.unitary.aqc
+
+Implementation of Approximate Quantum Compiler as described in the paper [1].
+
+Interface
+=========
+
+The main public interface of this module is reached by passing ``unitary_synthesis_method='aqc'`` to
+:func:`~.compiler.transpile`.  This will swap the synthesis method to use
+:class:`~.transpiler.passes.synthesis.AQCSynthesisPlugin`.
+The individual classes are:
+
+.. autosummary::
+    :toctree: ../stubs
+    :template: autosummary/class_no_inherited_members.rst
+
+    AQC
+    ApproximateCircuit
+    ApproximatingObjective
+    CNOTUnitCircuit
+    CNOTUnitObjective
+    DefaultCNOTUnitObjective
+    FastCNOTUnitObjective
+
+
+Mathematical Detail
+===================
+
+We are interested in compiling a quantum circuit, which we formalize as finding the best
+circuit representation in terms of an ordered gate sequence of a target unitary matrix
+:math:`U\in U(d)`, with some additional hardware constraints. In particular, we look at
+representations that could be constrained in terms of hardware connectivity, as well
+as gate depth, and we choose a gate basis in terms of CNOT and rotation gates.
+We recall that the combination of CNOT and rotation gates is universal in :math:`SU(d)` and
+therefore it does not limit compilation.
+
+To properly define what we mean by best circuit representation, we define the metric
+as the Frobenius norm between the unitary matrix of the compiled circuit :math:`V` and
+the target unitary matrix :math:`U`, i.e., :math:`\|V - U\|_{\mathrm{F}}`. This choice
+is motivated by mathematical programming considerations, and it is related to other
+formulations that appear in the literature. Let's take a look at the problem in more details.
+
+Let :math:`n` be the number of qubits and :math:`d=2^n`. Given a CNOT structure :math:`ct`
+and a vector of rotation angles :math:`\theta`, the parametric circuit forms a matrix
+:math:`Vct(\theta)\in SU(d)`. If we are given a target circuit forming a matrix
+:math:`U\in SU(d)`, then we would like to compute
+
+.. math::
+
+    \mathrm{argmax}_{\theta}\frac{1}{d}|\langle Vct(\theta),U\rangle|
+
+where the inner product is the Frobenius inner product. Note that
+:math:`|\langle V,U\rangle|\leq d` for all unitaries :math:`U` and :math:`V`, so the objective
+has range in :math:`[0,1]`.
+
+Our strategy is to maximize
+
+.. math::
+
+    \frac{1}{d}\Re \langle Vct(\theta),U\rangle
+
+using its gradient. We will now discuss the specifics by going through an example.
+
+While the range of :math:`Vct` is a subset of :math:`SU(d)` by construction, the target
+circuit may form a general unitary matrix. However, for any :math:`U\in U(d)`,
+
+.. math::
+
+    \frac{\exp(2\pi i k/d)}{\det(U)^{1/d}}U\in SU(d)\text{ for all }k\in\{0,\ldots,d-1\}.
+
+Thus, we should normalize the target circuit by its global phase and then approximately
+compile the normalized circuit. We can add the global phase back in afterwards.
+
+In the algorithm let :math:`U'` denote the un-normalized target matrix and :math:`U`
+the normalized  target matrix. Now that we have :math:`U`, we give the gradient function
+to the Nesterov's method optimizer and compute :math:`\theta`.
+
+To add the global phase back in, we can form the control circuit as
+
+.. math::
+
+    \frac{\langle Vct(\theta),U'\rangle}{|\langle Vct(\theta),U'\rangle|}Vct(\theta).
+
+Note that while we optimized using Nesterov's method in the paper, this was for its convergence
+guarantees, not its speed in practice. It is much faster to use L-BFGS which is used as a
+default optimizer in this implementation.
+
+A basic usage of the AQC algorithm should consist of the following steps::
+
+    # Define a target circuit as a unitary matrix
+    unitary = ...
+
+    # Define a number of qubits for the algorithm, at least 3 qubits
+    num_qubits = round(math.log2(unitary.shape[0]))
+
+    # Choose a layout of the CNOT structure for the approximate circuit, e.g. ``spin`` for
+    # a linear layout.
+    layout = options.get("layout") or "spin"
+
+    # Choose a connectivity type, e.g. ``full`` for full connectivity between qubits.
+    connectivity = options.get("connectivity") or "full"
+
+    # Define a targeted depth of the approximate circuit in the number of CNOT units.
+    depth = int(options.get("depth") or 0)
+
+    # Generate a network made of CNOT units
+    cnots = make_cnot_network(
+        num_qubits=num_qubits,
+        network_layout=layout,
+        connectivity_type=connectivity,
+        depth=depth
+    )
+
+    # Create an optimizer to be used by AQC
+    optimizer = partial(scipy.optimize.minimize, method="L-BFGS-B")
+
+    # Create an instance
+    aqc = AQC(optimizer)
+
+    # Create a template circuit that will approximate our target circuit
+    approximate_circuit = CNOTUnitCircuit(num_qubits=num_qubits, cnots=cnots)
+
+    # Create an objective that defines our optimization problem
+    approximating_objective = DefaultCNOTUnitObjective(num_qubits=num_qubits, cnots=cnots)
+
+    # Run optimization process to compile the unitary
+    aqc.compile_unitary(
+        target_matrix=unitary,
+        approximate_circuit=approximate_circuit,
+        approximating_objective=approximating_objective
+    )
+
+Now ``approximate_circuit`` is a circuit that approximates the target unitary to a certain
+degree and can be used instead of the original matrix.
+
+This uses a helper function, :obj:`make_cnot_network`.
+
+.. autofunction:: make_cnot_network
+
+One can take advantage of accelerated version of objective function. It implements the same
+mathematical algorithm as the default one ``DefaultCNOTUnitObjective`` but runs several times
+faster. Instantiation of accelerated objective function class is similar to the default case:
+
+    # Create an objective that defines our optimization problem
+    approximating_objective = FastCNOTUnitObjective(num_qubits=num_qubits, cnots=cnots)
+
+The rest of the code in the above example does not change.
+
+References:
+
+    [1]: Liam Madden, Andrea Simonetto, Best Approximate Quantum Compiling Problems.
+        `arXiv:2106.05649 <https://arxiv.org/abs/2106.05649>`_
+"""
+
+from .approximate import ApproximateCircuit, ApproximatingObjective
+from .aqc import AQC
+from .cnot_structures import make_cnot_network
+from .cnot_unit_circuit import CNOTUnitCircuit
+from .cnot_unit_objective import CNOTUnitObjective, DefaultCNOTUnitObjective
+from .fast_gradient.fast_gradient import FastCNOTUnitObjective

qiskit/synthesis/unitary/aqc/approximate.py

@@ -0,0 +1,116 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+"""Base classes for an approximate circuit definition."""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Optional, SupportsFloat
+import numpy as np
+
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+
+
+class ApproximateCircuit(QuantumCircuit, ABC):
+    """A base class that represents an approximate circuit."""
+
+    def __init__(self, num_qubits: int, name: Optional[str] = None) -> None:
+        """
+        Args:
+            num_qubits: number of qubit this circuit will span.
+            name: a name of the circuit.
+        """
+        super().__init__(num_qubits, name=name)
+
+    @property
+    @abstractmethod
+    def thetas(self) -> np.ndarray:
+        """
+        The property is not implemented and raises a ``NotImplementedException`` exception.
+
+        Returns:
+            a vector of parameters of this circuit.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def build(self, thetas: np.ndarray) -> None:
+        """
+        Constructs this circuit out of the parameters(thetas). Parameter values must be set before
+            constructing the circuit.
+
+        Args:
+            thetas: a vector of parameters to be set in this circuit.
+        """
+        raise NotImplementedError
+
+
+class ApproximatingObjective(ABC):
+    """
+    A base class for an optimization problem definition. An implementing class must provide at least
+    an implementation of the ``objective`` method. In such case only gradient free optimizers can
+    be used. Both method, ``objective`` and ``gradient``, preferable to have in an implementation.
+    """
+
+    def __init__(self) -> None:
+        # must be set before optimization
+        self._target_matrix: np.ndarray | None = None
+
+    @abstractmethod
+    def objective(self, param_values: np.ndarray) -> SupportsFloat:
+        """
+        Computes a value of the objective function given a vector of parameter values.
+
+        Args:
+            param_values: a vector of parameter values for the optimization problem.
+
+        Returns:
+            a float value of the objective function.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def gradient(self, param_values: np.ndarray) -> np.ndarray:
+        """
+        Computes a gradient with respect to parameters given a vector of parameter values.
+
+        Args:
+            param_values: a vector of parameter values for the optimization problem.
+
+        Returns:
+            an array of gradient values.
+        """
+        raise NotImplementedError
+
+    @property
+    def target_matrix(self) -> np.ndarray:
+        """
+        Returns:
+            a matrix being approximated
+        """
+        return self._target_matrix
+
+    @target_matrix.setter
+    def target_matrix(self, target_matrix: np.ndarray) -> None:
+        """
+        Args:
+            target_matrix: a matrix to approximate in the optimization procedure.
+        """
+        self._target_matrix = target_matrix
+
+    @property
+    @abstractmethod
+    def num_thetas(self) -> int:
+        """
+
+        Returns:
+            the number of parameters in this optimization problem.
+        """
+        raise NotImplementedError

qiskit/synthesis/unitary/aqc/aqc.py

@@ -0,0 +1,175 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022, 2023.
+#
+# 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.
+"""A generic implementation of Approximate Quantum Compiler."""
+from __future__ import annotations
+
+import typing
+from functools import partial
+
+from collections.abc import Callable
+from typing import Protocol
+
+import numpy as np
+
+from qiskit.quantum_info import Operator
+
+from .approximate import ApproximateCircuit, ApproximatingObjective
+
+if typing.TYPE_CHECKING:
+    import scipy.optimize
+
+
+class Minimizer(Protocol):
+    """Callable Protocol for minimizer.
+
+    This interface is based on `SciPy's optimize module
+    <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html>`__.
+
+     This protocol defines a callable taking the following parameters:
+
+         fun
+             The objective function to minimize.
+         x0
+             The initial point for the optimization.
+         jac
+             The gradient of the objective function.
+         bounds
+             Parameters bounds for the optimization. Note that these might not be supported
+             by all optimizers.
+
+     and which returns a SciPy minimization result object.
+    """
+
+    def __call__(
+        self,
+        fun: Callable[[np.ndarray], float],
+        x0: np.ndarray,  # pylint: disable=invalid-name
+        jac: Callable[[np.ndarray], np.ndarray] | None = None,
+        bounds: list[tuple[float, float]] | None = None,
+    ) -> scipy.optimize.OptimizeResult:
+        """Minimize the objective function.
+
+        This interface is based on `SciPy's optimize module <https://docs.scipy.org/doc
+        /scipy/reference/generated/scipy.optimize.minimize.html>`__.
+
+        Args:
+            fun: The objective function to minimize.
+            x0: The initial point for the optimization.
+            jac: The gradient of the objective function.
+            bounds: Parameters bounds for the optimization. Note that these might not be supported
+                by all optimizers.
+
+        Returns:
+             The SciPy minimization result object.
+        """
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+class AQC:
+    """
+    A generic implementation of the Approximate Quantum Compiler. This implementation is agnostic of
+    the underlying implementation of the approximate circuit, objective, and optimizer. Users may
+    pass corresponding implementations of the abstract classes:
+
+    * The *optimizer* is an implementation of the :class:`~.Minimizer` protocol, a callable used to run
+      the optimization process. The choice of optimizer may affect overall convergence, required time
+      for the optimization process and achieved objective value.
+
+    * The *approximate circuit* represents a template which parameters we want to optimize.  Currently,
+      there's only one implementation based on 4-rotations CNOT unit blocks:
+      :class:`.CNOTUnitCircuit`. See the paper for more details.
+
+    * The *approximate objective* is tightly coupled with the approximate circuit implementation and
+      provides two methods for computing objective function and gradient with respect to approximate
+      circuit parameters. This objective is passed to the optimizer. Currently, there are two
+      implementations based on 4-rotations CNOT unit blocks: :class:`.DefaultCNOTUnitObjective` and
+      its accelerated version :class:`.FastCNOTUnitObjective`. Both implementations share the same
+      idea of maximization the Hilbert-Schmidt product between the target matrix and its
+      approximation. The former implementation approach should be considered as a baseline one. It
+      may suffer from performance issues, and is mostly suitable for a small number of qubits
+      (up to 5 or 6), whereas the latter, accelerated one, can be applied to larger problems.
+
+    * One should take into consideration the exponential growth of matrix size with the number of
+      qubits because the implementation not only creates a potentially large target matrix, but
+      also allocates a number of temporary memory buffers comparable in size to the target matrix.
+    """
+
+    def __init__(
+        self,
+        optimizer: Minimizer | None = None,
+        seed: int | None = None,
+    ):
+        """
+        Args:
+            optimizer: an optimizer to be used in the optimization procedure of the search for
+                the best approximate circuit. By default, the scipy minimizer with the
+                ``L-BFGS-B`` method is used with max iterations set to 1000.
+            seed: a seed value to be used by a random number generator.
+        """
+        import scipy.optimize
+
+        super().__init__()
+        self._optimizer = optimizer or partial(
+            scipy.optimize.minimize, args=(), method="L-BFGS-B", options={"maxiter": 1000}
+        )
+
+        self._seed = seed
+
+    def compile_unitary(
+        self,
+        target_matrix: np.ndarray,
+        approximate_circuit: ApproximateCircuit,
+        approximating_objective: ApproximatingObjective,
+        initial_point: np.ndarray | None = None,
+    ) -> None:
+        """
+        Approximately compiles a circuit represented as a unitary matrix by solving an optimization
+        problem defined by ``approximating_objective`` and using ``approximate_circuit`` as a
+        template for the approximate circuit.
+
+        Args:
+            target_matrix: a unitary matrix to approximate.
+            approximate_circuit: a template circuit that will be filled with the parameter values
+                obtained in the optimization procedure.
+            approximating_objective: a definition of the optimization problem.
+            initial_point: initial values of angles/parameters to start optimization from.
+        """
+        matrix_dim = target_matrix.shape[0]
+        # check if it is actually a special unitary matrix
+        target_det = np.linalg.det(target_matrix)
+        if not np.isclose(target_det, 1):
+            su_matrix = target_matrix / np.power(target_det, (1 / matrix_dim), dtype=complex)
+            global_phase_required = True
+        else:
+            su_matrix = target_matrix
+            global_phase_required = False
+
+        # set the matrix to approximate in the algorithm
+        approximating_objective.target_matrix = su_matrix
+
+        if initial_point is None:
+            np.random.seed(self._seed)
+            initial_point = np.random.uniform(0, 2 * np.pi, approximating_objective.num_thetas)
+
+        opt_result = self._optimizer(
+            fun=approximating_objective.objective,
+            x0=initial_point,
+            jac=approximating_objective.gradient,
+        )
+
+        approximate_circuit.build(opt_result.x)
+
+        approx_matrix = Operator(approximate_circuit).data
+
+        if global_phase_required:
+            alpha = np.angle(np.trace(np.dot(approx_matrix.conj().T, target_matrix)))
+            approximate_circuit.global_phase = alpha