qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/library/phase_oracle.py

@@ -0,0 +1,239 @@
+# 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.
+
+"""Phase Oracle object."""
+
+from __future__ import annotations
+
+from qiskit.circuit import QuantumCircuit, Gate
+
+from qiskit.synthesis.boolean.boolean_expression import BooleanExpression
+
+
+class PhaseOracle(QuantumCircuit):
+    r"""Phase Oracle.
+
+    The Phase Oracle object constructs circuits for any arbitrary
+    input logical expressions. A logical expression is composed of logical operators
+    `&` (logical `AND`), `|` (logical  `OR`),
+    `~` (logical  `NOT`), and `^` (logical  `XOR`).
+    as well as symbols for literals (variables).
+    For example, `'a & b'`, and `(v0 | ~v1) & (~v2 & v3)`
+    are both valid string representation of boolean logical expressions.
+
+    A phase oracle for a boolean function `f(x)` performs the following
+    quantum operation:
+
+    .. math::
+
+            |x\rangle \mapsto (-1)^{f(x)}|x\rangle
+
+    For convenience, this oracle, in addition to parsing arbitrary logical expressions,
+    also supports input strings in the `DIMACS CNF format
+    <https://web.archive.org/web/20190325181937/https://www.satcompetition.org/2009/format-benchmarks2009.html>`__,
+    which is the standard format for specifying SATisfiability (SAT) problem instances in
+    `Conjunctive Normal Form (CNF) <https://en.wikipedia.org/wiki/Conjunctive_normal_form>`__,
+    which is a conjunction of one or more clauses, where a clause is a disjunction of one
+    or more literals. See :meth:`qiskit.circuit.library.phase_oracle.PhaseOracle.from_dimacs_file`.
+
+    From 16 variables on, possible performance issues should be expected when using the
+    default synthesizer.
+    """
+
+    def __init__(
+        self,
+        expression: str,
+        var_order: list[str] | None = None,
+    ) -> None:
+        """
+        Args:
+            expression: A Python-like boolean expression.
+            var_order: A list with the order in which variables will be created.
+               (default: by appearance)
+        """
+        self.boolean_expression = BooleanExpression(expression, var_order=var_order)
+        oracle = self.boolean_expression.synth(circuit_type="phase")
+
+        super().__init__(oracle.num_qubits, name="Phase Oracle")
+
+        self.compose(oracle, inplace=True, copy=False)
+
+    def evaluate_bitstring(self, bitstring: str) -> bool:
+        """Evaluate the oracle on a bitstring.
+        This evaluation is done classically without any quantum circuit.
+
+        Args:
+            bitstring: The bitstring for which to evaluate. The input bitstring is expected to be
+                in little-endian order.
+
+        Returns:
+            True if the bitstring is a good state, False otherwise.
+        """
+        return self.boolean_expression.simulate(bitstring[::-1])
+
+    @classmethod
+    def from_dimacs_file(cls, filename: str):
+        r"""Create a PhaseOracle from the string in the DIMACS format.
+
+        It is possible to build a PhaseOracle from a file in `DIMACS CNF format
+        <https://web.archive.org/web/20190325181937/https://www.satcompetition.org/2009/format-benchmarks2009.html>`__,
+        which is the standard format for specifying SATisfiability (SAT) problem instances in
+        `Conjunctive Normal Form (CNF) <https://en.wikipedia.org/wiki/Conjunctive_normal_form>`__,
+        which is a conjunction of one or more clauses, where a clause is a disjunction of one
+        or more literals.
+
+        The following is an example of a CNF expressed in the DIMACS format:
+
+        .. code:: text
+
+          c DIMACS CNF file with 3 satisfying assignments: 1 -2 3, -1 -2 -3, 1 2 -3.
+          p cnf 3 5
+          -1 -2 -3 0
+          1 -2 3 0
+          1 2 -3 0
+          1 -2 -3 0
+          -1 2 3 0
+
+        The first line, following the `c` character, is a comment. The second line specifies that
+        the CNF is over three boolean variables --- let us call them  :math:`x_1, x_2, x_3`, and
+        contains five clauses.  The five clauses, listed afterwards, are implicitly joined by the
+        logical `AND` operator, :math:`\land`, while the variables in each clause, represented by
+        their indices, are implicitly disjoined by the logical `OR` operator, :math:`lor`. The
+        :math:`-` symbol preceding a boolean variable index corresponds to the logical `NOT`
+        operator, :math:`lnot`. Character `0` (zero) marks the end of each clause.  Essentially,
+        the code above corresponds to the following CNF:
+
+        :math:`(\lnot x_1 \lor \lnot x_2 \lor \lnot x_3)
+        \land (x_1 \lor \lnot x_2 \lor x_3)
+        \land (x_1 \lor x_2 \lor \lnot x_3)
+        \land (x_1 \lor \lnot x_2 \lor \lnot x_3)
+        \land (\lnot x_1 \lor x_2 \lor x_3)`.
+
+
+        Args:
+            filename: A file in DIMACS format.
+
+        Returns:
+            PhaseOracle: A quantum circuit with a phase oracle.
+        """
+        expr = BooleanExpression.from_dimacs_file(filename)
+        return cls(expr)
+
+
+class PhaseOracleGate(Gate):
+    r"""Implements a phase oracle.
+
+    The Phase Oracle Gate object constructs circuits for any arbitrary
+    input logical expressions. A logical expression is composed of logical operators
+    `&` (logical `AND`), `|` (logical  `OR`),
+    `~` (logical  `NOT`), and `^` (logical  `XOR`).
+    as well as symbols for literals (variables).
+    For example, `'a & b'`, and `(v0 | ~v1) & (~v2 & v3)`
+    are both valid string representation of boolean logical expressions.
+
+    A phase oracle for a boolean function `f(x)` performs the following
+    quantum operation:
+
+    .. math::
+
+            |x\rangle \mapsto (-1)^{f(x)}|x\rangle
+
+    For convenience, this oracle, in addition to parsing arbitrary logical expressions,
+    also supports input strings in the `DIMACS CNF format
+    <https://web.archive.org/web/20190325181937/https://www.satcompetition.org/2009/format-benchmarks2009.html>`__,
+    which is the standard format for specifying SATisfiability (SAT) problem instances in
+    `Conjunctive Normal Form (CNF) <https://en.wikipedia.org/wiki/Conjunctive_normal_form>`__,
+    which is a conjunction of one or more clauses, where a clause is a disjunction of one
+    or more literals. See :meth:`qiskit.circuit.library.phase_oracle.PhaseOracleGate.from_dimacs_file`.
+
+    From 16 variables on, possible performance issues should be expected when using the
+    default synthesizer.
+    """
+
+    def __init__(
+        self,
+        expression: str,
+        var_order: list[str] | None = None,
+        label: str | None = None,
+    ) -> None:
+        """
+        Args:
+            expression: A Python-like boolean expression.
+            var_order: A list with the order in which variables will be created.
+               (default: by appearance)
+            label: A label for the gate to display in visualizations. Per default, the label is
+                set to display the textual represntation of the boolean expression (truncated if needed)
+        """
+        self.boolean_expression = BooleanExpression(expression, var_order=var_order)
+
+        if label is None:
+            short_expr_for_name = (expression[:15] + "...") if len(expression) > 15 else expression
+            label = short_expr_for_name
+
+        super().__init__(
+            name="Phase Oracle",
+            num_qubits=self.boolean_expression.num_bits,
+            params=[],
+            label=label,
+        )
+
+    def _define(self):
+        """Defined by the synthesized phase oracle"""
+        self.definition = self.boolean_expression.synth(circuit_type="phase")
+
+    @classmethod
+    def from_dimacs_file(cls, filename: str) -> PhaseOracleGate:
+        r"""Create a PhaseOracle from the string in the DIMACS format.
+
+        It is possible to build a PhaseOracle from a file in `DIMACS CNF format
+        <https://web.archive.org/web/20190325181937/https://www.satcompetition.org/2009/format-benchmarks2009.html>`__,
+        which is the standard format for specifying SATisfiability (SAT) problem instances in
+        `Conjunctive Normal Form (CNF) <https://en.wikipedia.org/wiki/Conjunctive_normal_form>`__,
+        which is a conjunction of one or more clauses, where a clause is a disjunction of one
+        or more literals.
+
+        The following is an example of a CNF expressed in the DIMACS format:
+
+        .. code:: text
+
+          c DIMACS CNF file with 3 satisfying assignments: 1 -2 3, -1 -2 -3, 1 2 -3.
+          p cnf 3 5
+          -1 -2 -3 0
+          1 -2 3 0
+          1 2 -3 0
+          1 -2 -3 0
+          -1 2 3 0
+
+        The first line, following the `c` character, is a comment. The second line specifies that
+        the CNF is over three boolean variables --- let us call them  :math:`x_1, x_2, x_3`, and
+        contains five clauses.  The five clauses, listed afterwards, are implicitly joined by the
+        logical `AND` operator, :math:`\land`, while the variables in each clause, represented by
+        their indices, are implicitly disjoined by the logical `OR` operator, :math:`\lor`. The
+        :math:`-` symbol preceding a boolean variable index corresponds to the logical `NOT`
+        operator, :math:`\lnot`. Character `0` (zero) marks the end of each clause.  Essentially,
+        the code above corresponds to the following CNF:
+
+        :math:`(\lnot x_1 \lor \lnot x_2 \lor \lnot x_3)
+        \land (x_1 \lor \lnot x_2 \lor x_3)
+        \land (x_1 \lor x_2 \lor \lnot x_3)
+        \land (x_1 \lor \lnot x_2 \lor \lnot x_3)
+        \land (\lnot x_1 \lor x_2 \lor x_3)`.
+
+
+        Args:
+            filename: A file in DIMACS format.
+
+        Returns:
+            PhaseOracleGate: A quantum circuit with a phase oracle.
+        """
+        expr = BooleanExpression.from_dimacs_file(filename)
+        return cls(expr)

qiskit/circuit/library/quantum_volume.py

@@ -0,0 +1,179 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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.
+
+"""Quantum Volume model circuit."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import numpy as np
+from qiskit.circuit import QuantumCircuit, CircuitInstruction
+from qiskit.circuit.library.generalized_gates import PermutationGate, UnitaryGate
+from qiskit._accelerate.circuit_library import quantum_volume as qv_rs
+
+
+class QuantumVolume(QuantumCircuit):
+    """A quantum volume model circuit.
+
+    The model circuits are random instances of circuits used to measure
+    the Quantum Volume metric, as introduced in [1].
+
+    The model circuits consist of layers of Haar random
+    elements of SU(4) applied between corresponding pairs
+    of qubits in a random bipartition.
+
+    **Reference Circuit:**
+
+    .. plot::
+       :alt: Diagram illustrating the previously described circuit.
+
+       from qiskit.circuit.library import QuantumVolume
+       circuit = QuantumVolume(5, 6, seed=10)
+       circuit.draw('mpl')
+
+    **Expanded Circuit:**
+
+    .. plot::
+       :alt: Diagram illustrating the previously described circuit.
+
+       from qiskit.circuit.library import QuantumVolume
+       from qiskit.visualization.library import _generate_circuit_library_visualization
+       circuit = QuantumVolume(5, 6, seed=10, classical_permutation=False)
+       _generate_circuit_library_visualization(circuit.decompose())
+
+    **References:**
+
+    [1] A. Cross et al. Validating quantum computers using
+    randomized model circuits, Phys. Rev. A 100, 032328 (2019).
+    [`arXiv:1811.12926 <https://arxiv.org/abs/1811.12926>`_]
+    """
+
+    def __init__(
+        self,
+        num_qubits: int,
+        depth: Optional[int] = None,
+        seed: Optional[Union[int, np.random.Generator]] = None,
+        classical_permutation: bool = True,
+        *,
+        flatten: bool = False,
+    ) -> None:
+        """Create quantum volume model circuit of size num_qubits x depth.
+
+        Args:
+            num_qubits: number of active qubits in model circuit.
+            depth: layers of SU(4) operations in model circuit.
+            seed: Random number generator or generator seed.
+            classical_permutation: use classical permutations at every layer,
+                rather than quantum.
+            flatten: If ``False`` (the default), construct a circuit that contains a single
+                instruction, which in turn has the actual volume structure.  If ``True``, construct
+                the volume structure directly.
+        """
+        import scipy.stats
+
+        # Parameters
+        depth = depth or num_qubits  # how many layers of SU(4)
+        width = num_qubits // 2  # how many SU(4)s fit in each layer
+        rng = seed if isinstance(seed, np.random.Generator) else np.random.default_rng(seed)
+        seed_name = seed
+        if seed_name is None:
+            # Get the internal entropy used to seed the default RNG, if no seed was given.  This
+            # stays in the output name, so effectively stores a way of regenerating the circuit.
+            # This is just best-effort only, for backwards compatibility, and isn't critical (if
+            # someone needs full reproducibility, they should be manually controlling the seeding).
+            seed_name = getattr(getattr(rng.bit_generator, "seed_seq", None), "entropy", None)
+
+        super().__init__(
+            num_qubits,
+            name="quantum_volume_" + str([num_qubits, depth, seed_name]).replace(" ", ""),
+        )
+        if classical_permutation:
+            if seed is not None:
+                max_value = np.iinfo(np.int64).max
+                seed = rng.integers(max_value, dtype=np.int64)
+            qv_circ = quantum_volume(num_qubits, depth, seed)
+            qv_circ.name = self.name
+            if flatten:
+                self.compose(qv_circ, inplace=True)
+            else:
+                self._append(CircuitInstruction(qv_circ.to_instruction(), tuple(self.qubits)))
+        else:
+            if seed is None:
+                seed = seed_name
+
+            base = self if flatten else QuantumCircuit(num_qubits, name=self.name)
+
+            # For each layer, generate a permutation of qubits
+            # Then generate and apply a Haar-random SU(4) to each pair
+            unitaries = scipy.stats.unitary_group.rvs(4, depth * width, rng).reshape(
+                depth, width, 4, 4
+            )
+            qubits = tuple(base.qubits)
+            for row in unitaries:
+                perm = rng.permutation(num_qubits)
+                base._append(CircuitInstruction(PermutationGate(perm), qubits))
+                for w, unitary in enumerate(row):
+                    gate = UnitaryGate(unitary, check_input=False, num_qubits=2)
+                    qubit = 2 * w
+                    base._append(CircuitInstruction(gate, qubits[qubit : qubit + 2]))
+            if not flatten:
+                self._append(CircuitInstruction(base.to_instruction(), tuple(self.qubits)))
+
+
+def quantum_volume(
+    num_qubits: int,
+    depth: int | None = None,
+    seed: int | np.random.Generator | None = None,
+) -> QuantumCircuit:
+    """A quantum volume model circuit.
+
+    The model circuits are random instances of circuits used to measure
+    the Quantum Volume metric, as introduced in [1].
+
+    The model circuits consist of layers of Haar random
+    elements of SU(4) applied between corresponding pairs
+    of qubits in a random bipartition.
+
+    This function is multithreaded and will launch a thread pool with threads equal to the number
+    of CPUs by default. You can tune the number of threads with the ``RAYON_NUM_THREADS``
+    environment variable. For example, setting ``RAYON_NUM_THREADS=4`` would limit the thread pool
+    to 4 threads.
+
+    Args:
+        num_qubits: The number qubits to use for the generated circuit.
+        depth: The number of layers for the generated circuit. If this
+            is not specified it will default to ``num_qubits`` layers.
+        seed: An optional RNG seed used for generating the random SU(4)
+            matrices used in the output circuit. This can be either an
+            integer or a numpy generator. If an integer is specfied it must
+            be an value between 0 and 2**64 - 1.
+
+    **Reference Circuit:**
+
+    .. plot::
+       :alt: Diagram illustrating the previously described circuit.
+
+       from qiskit.circuit.library import quantum_volume
+       circuit = quantum_volume(5, 6, seed=10)
+       circuit.draw('mpl')
+
+    **References:**
+
+    [1] A. Cross et al. Validating quantum computers using
+    randomized model circuits, Phys. Rev. A 100, 032328 (2019).
+    `arXiv:1811.12926 <https://arxiv.org/abs/1811.12926>`__
+    """
+    if isinstance(seed, np.random.Generator):
+        seed = seed.integers(0, dtype=np.uint64)
+    depth = depth or num_qubits
+    return QuantumCircuit._from_circuit_data(qv_rs(num_qubits, depth, seed))

qiskit/circuit/library/standard_gates/__init__.py

@@ -0,0 +1,141 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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.
+
+"""
+Standard gates
+"""
+
+from .h import HGate, CHGate
+from .i import IGate
+from .p import PhaseGate, CPhaseGate, MCPhaseGate
+from .r import RGate
+from .rx import RXGate, CRXGate
+from .rxx import RXXGate
+from .ry import RYGate, CRYGate
+from .ryy import RYYGate
+from .rz import RZGate, CRZGate
+from .rzz import RZZGate
+from .rzx import RZXGate
+from .xx_minus_yy import XXMinusYYGate
+from .xx_plus_yy import XXPlusYYGate
+from .ecr import ECRGate
+from .s import SGate, SdgGate, CSGate, CSdgGate
+from .swap import SwapGate, CSwapGate
+from .iswap import iSwapGate
+from .sx import SXGate, SXdgGate, CSXGate
+from .dcx import DCXGate
+from .t import TGate, TdgGate
+from .u import UGate, CUGate
+from .u1 import U1Gate, CU1Gate, MCU1Gate
+from .u2 import U2Gate
+from .u3 import U3Gate, CU3Gate
+from .x import XGate, CXGate, CCXGate, C3XGate, C3SXGate, C4XGate, RCCXGate, RC3XGate
+from .x import MCXGate, MCXGrayCode, MCXRecursive, MCXVChain
+from .y import YGate, CYGate
+from .z import ZGate, CZGate, CCZGate
+from .global_phase import GlobalPhaseGate
+
+
+def get_standard_gate_name_mapping():
+    """Return a dictionary mapping the name of standard gates and instructions to an object for
+    that name.
+
+    Examples:
+
+        .. code-block:: python
+
+            from qiskit.circuit.library import get_standard_gate_name_mapping
+
+            gate_name_map = get_standard_gate_name_mapping()
+            cx_object = gate_name_map["cx"]
+
+            print(cx_object)
+            print(type(cx_object))
+
+        .. code-block:: text
+
+            Instruction(name='cx', num_qubits=2, num_clbits=0, params=[])
+            _SingletonCXGate
+    """
+
+    from qiskit.circuit.parameter import Parameter
+    from qiskit.circuit.measure import Measure
+    from qiskit.circuit.delay import Delay
+    from qiskit.circuit.reset import Reset
+
+    lambda_ = Parameter("λ")
+    theta = Parameter("ϴ")
+    phi = Parameter("φ")
+    gamma = Parameter("γ")
+    beta = Parameter("β")
+    time = Parameter("t")
+
+    # Standard gates library mapping, multicontrolled gates not included since they're
+    # variable width
+    gates = [
+        IGate(),
+        SXGate(),
+        XGate(),
+        CXGate(),
+        RZGate(lambda_),
+        RGate(theta, phi),
+        C3SXGate(),
+        CCXGate(),
+        DCXGate(),
+        CHGate(),
+        CPhaseGate(theta),
+        CRXGate(theta),
+        CRYGate(theta),
+        CRZGate(theta),
+        CSwapGate(),
+        CSXGate(),
+        CUGate(theta, phi, lambda_, gamma),
+        CU1Gate(lambda_),
+        CU3Gate(theta, phi, lambda_),
+        CYGate(),
+        CZGate(),
+        CCZGate(),
+        GlobalPhaseGate(theta),
+        HGate(),
+        PhaseGate(theta),
+        RCCXGate(),
+        RC3XGate(),
+        RXGate(theta),
+        RXXGate(theta),
+        RYGate(theta),
+        RYYGate(theta),
+        RZZGate(theta),
+        RZXGate(theta),
+        XXMinusYYGate(theta, beta),
+        XXPlusYYGate(theta, beta),
+        ECRGate(),
+        SGate(),
+        SdgGate(),
+        CSGate(),
+        CSdgGate(),
+        SwapGate(),
+        iSwapGate(),
+        SXdgGate(),
+        TGate(),
+        TdgGate(),
+        UGate(theta, phi, lambda_),
+        U1Gate(lambda_),
+        U2Gate(phi, lambda_),
+        U3Gate(theta, phi, lambda_),
+        YGate(),
+        ZGate(),
+        Delay(time),
+        Reset(),
+        Measure(),
+    ]
+    name_mapping = {gate.name: gate for gate in gates}
+    return name_mapping

qiskit/circuit/library/standard_gates/dcx.py

@@ -0,0 +1,76 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2020.
+#
+# 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.
+
+"""Double-CNOT gate."""
+
+from qiskit.circuit.singleton import SingletonGate, stdlib_singleton_key
+from qiskit.circuit._utils import with_gate_array
+from qiskit._accelerate.circuit import StandardGate
+
+
+@with_gate_array([[1, 0, 0, 0], [0, 0, 0, 1], [0, 1, 0, 0], [0, 0, 1, 0]])
+class DCXGate(SingletonGate):
+    r"""Double-CNOT gate.
+
+    A 2-qubit Clifford gate consisting of two back-to-back
+    CNOTs with alternate controls.
+
+    Can be applied to a :class:`~qiskit.circuit.QuantumCircuit`
+    with the :meth:`~qiskit.circuit.QuantumCircuit.dcx` method.
+
+    .. code-block:: text
+
+                  ┌───┐
+        q_0: ──■──┤ X ├
+             ┌─┴─┐└─┬─┘
+        q_1: ┤ X ├──■──
+             └───┘
+
+    This is a classical logic gate, equivalent to a CNOT-SWAP (CNS) sequence,
+    and locally equivalent to an iSWAP.
+
+    .. math::
+
+        DCX\ q_0, q_1 =
+            \begin{pmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0
+            \end{pmatrix}
+    """
+
+    _standard_gate = StandardGate.DCX
+
+    def __init__(self, label=None):
+        """Create new DCX gate."""
+        super().__init__("dcx", 2, [], label=label)
+
+    _singleton_lookup_key = stdlib_singleton_key()
+
+    def _define(self):
+        """Default definition"""
+        # pylint: disable=cyclic-import
+        from qiskit.circuit import QuantumCircuit
+
+        #           ┌───┐
+        # q_0: ──■──┤ X ├
+        #      ┌─┴─┐└─┬─┘
+        # q_1: ┤ X ├──■──
+        #      └───┘
+
+        self.definition = QuantumCircuit._from_circuit_data(
+            StandardGate.DCX._get_definition(self.params), add_regs=True, name=self.name
+        )
+
+    def __eq__(self, other):
+        return isinstance(other, DCXGate)