qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/transpiler/synthesis/aqc/__init__.py

@@ -0,0 +1,178 @@
+# 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.transpiler.synthesis.aqc`)
+=====================================================================
+
+.. currentmodule:: qiskit.transpiler.synthesis.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
+:obj:`~.compiler.transpile`.  This will swap the synthesis method to use :obj:`AQCSynthesisPlugin`.
+The individual classes are:
+
+.. autosummary::
+    :toctree: ../stubs
+    :template: autosummary/class_no_inherited_members.rst
+
+    AQC
+    AQCSynthesisPlugin
+    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::
+
+    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 = int(round(np.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 = 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 .aqc_plugin import AQCSynthesisPlugin
+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/transpiler/synthesis/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 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/transpiler/synthesis/aqc/aqc.py

@@ -0,0 +1,170 @@
+# 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
+
+from functools import partial
+
+from collections.abc import Callable
+from typing import Protocol
+
+import numpy as np
+from scipy.optimize import OptimizeResult, minimize
+
+from qiskit.quantum_info import Operator
+
+from .approximate import ApproximateCircuit, ApproximatingObjective
+
+
+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,
+    ) -> 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.
+        """
+        super().__init__()
+        self._optimizer = optimizer or partial(
+            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

qiskit/transpiler/synthesis/aqc/aqc_plugin.py

@@ -0,0 +1,146 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021, 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.
+"""
+An AQC synthesis plugin to Qiskit's transpiler.
+"""
+from functools import partial
+import numpy as np
+
+from qiskit.converters import circuit_to_dag
+from qiskit.transpiler.passes.synthesis.plugin import UnitarySynthesisPlugin
+
+
+class AQCSynthesisPlugin(UnitarySynthesisPlugin):
+    """
+    An AQC-based Qiskit unitary synthesis plugin.
+
+    This plugin is invoked by :func:`~.compiler.transpile` when the ``unitary_synthesis_method``
+    parameter is set to ``"aqc"``.
+
+    This plugin supports customization and additional parameters can be passed to the plugin
+    by passing a dictionary as the ``unitary_synthesis_plugin_config`` parameter of
+    the :func:`~qiskit.compiler.transpile` function.
+
+    Supported parameters in the dictionary:
+
+    network_layout (str)
+        Type of network geometry, one of {``"sequ"``, ``"spin"``, ``"cart"``, ``"cyclic_spin"``,
+        ``"cyclic_line"``}. Default value is ``"spin"``.
+
+    connectivity_type (str)
+        type of inter-qubit connectivity, {``"full"``, ``"line"``, ``"star"``}.  Default value
+        is ``"full"``.
+
+    depth (int)
+        depth of the CNOT-network, i.e. the number of layers, where each layer consists of a
+        single CNOT-block.
+
+    optimizer (:class:`~.Minimizer`)
+        An implementation of the ``Minimizer`` protocol to be used in the optimization process.
+
+    seed (int)
+        A random seed.
+
+    initial_point (:class:`~numpy.ndarray`)
+        Initial values of angles/parameters to start the optimization process from.
+    """
+
+    @property
+    def max_qubits(self):
+        """Maximum number of supported qubits is ``14``."""
+        return 14
+
+    @property
+    def min_qubits(self):
+        """Minimum number of supported qubits is ``3``."""
+        return 3
+
+    @property
+    def supports_natural_direction(self):
+        """The plugin does not support natural direction,
+        it assumes bidirectional two qubit gates."""
+        return False
+
+    @property
+    def supports_pulse_optimize(self):
+        """The plugin does not support optimization of pulses."""
+        return False
+
+    @property
+    def supports_gate_lengths(self):
+        """The plugin does not support gate lengths."""
+        return False
+
+    @property
+    def supports_gate_errors(self):
+        """The plugin does not support gate errors."""
+        return False
+
+    @property
+    def supported_bases(self):
+        """The plugin does not support bases for synthesis."""
+        return None
+
+    @property
+    def supports_basis_gates(self):
+        """The plugin does not support basis gates and by default it synthesizes a circuit using
+        ``["rx", "ry", "rz", "cx"]`` gate basis."""
+        return False
+
+    @property
+    def supports_coupling_map(self):
+        """The plugin does not support coupling maps."""
+        return False
+
+    def run(self, unitary, **options):
+
+        # Runtime imports to avoid the overhead of these imports for
+        # plugin discovery and only use them if the plugin is run/used
+        from scipy.optimize import minimize
+        from qiskit.transpiler.synthesis.aqc.aqc import AQC
+        from qiskit.transpiler.synthesis.aqc.cnot_structures import make_cnot_network
+        from qiskit.transpiler.synthesis.aqc.cnot_unit_circuit import CNOTUnitCircuit
+        from qiskit.transpiler.synthesis.aqc.cnot_unit_objective import DefaultCNOTUnitObjective
+
+        num_qubits = int(round(np.log2(unitary.shape[0])))
+
+        config = options.get("config") or {}
+
+        network_layout = config.get("network_layout", "spin")
+        connectivity_type = config.get("connectivity_type", "full")
+        depth = config.get("depth", 0)
+
+        cnots = make_cnot_network(
+            num_qubits=num_qubits,
+            network_layout=network_layout,
+            connectivity_type=connectivity_type,
+            depth=depth,
+        )
+
+        default_optimizer = partial(minimize, args=(), method="L-BFGS-B", options={"maxiter": 1000})
+        optimizer = config.get("optimizer", default_optimizer)
+        seed = config.get("seed")
+        aqc = AQC(optimizer, seed)
+
+        approximate_circuit = CNOTUnitCircuit(num_qubits=num_qubits, cnots=cnots)
+        approximating_objective = DefaultCNOTUnitObjective(num_qubits=num_qubits, cnots=cnots)
+
+        initial_point = config.get("initial_point")
+        aqc.compile_unitary(
+            target_matrix=unitary,
+            approximate_circuit=approximate_circuit,
+            approximating_objective=approximating_objective,
+            initial_point=initial_point,
+        )
+
+        dag_circuit = circuit_to_dag(approximate_circuit)
+        return dag_circuit