qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/circuit/library/overlap.py

@@ -0,0 +1,182 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 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.
+
+"""Unitary overlap circuit."""
+
+from qiskit.circuit import QuantumCircuit, Gate
+from qiskit.circuit.parametervector import ParameterVector
+from qiskit.circuit.exceptions import CircuitError
+from qiskit.circuit import Barrier
+from qiskit.utils.deprecation import deprecate_func
+
+
+class UnitaryOverlap(QuantumCircuit):
+    r"""Circuit that returns the overlap between two unitaries :math:`U_2^{\dag} U_1`.
+
+    The input quantum circuits must represent unitary operations, since they must be invertible.
+    If the inputs will have parameters, they are replaced by :class:`.ParameterVector`\s with
+    names `"p1"` (for circuit ``unitary1``) and `"p2"` (for circuit ``unitary_2``) in the output
+    circuit.
+
+    This circuit is usually employed in computing the fidelity:
+
+    .. math::
+
+        \left|\langle 0| U_2^{\dag} U_1|0\rangle\right|^{2}
+
+    by computing the probability of being in the all-zeros bit-string, or equivalently,
+    the expectation value of projector :math:`|0\rangle\langle 0|`.
+
+    Example::
+
+        import numpy as np
+        from qiskit.circuit.library import EfficientSU2, UnitaryOverlap
+        from qiskit.primitives import Sampler
+
+        # get two circuit to prepare states of which we compute the overlap
+        circuit = EfficientSU2(2, reps=1)
+        unitary1 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+        unitary2 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+
+        # create the overlap circuit
+        overlap = UnitaryOverlap(unitary1, unitary2)
+
+        # sample from the overlap
+        sampler = Sampler(options={"shots": 100})
+        result = sampler.run(overlap).result()
+
+        # the fidelity is the probability to measure 0
+        fidelity = result.quasi_dists[0].get(0, 0)
+
+    """
+
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.unitary_overlap instead.",
+        pending=True,
+    )
+    def __init__(
+        self,
+        unitary1: QuantumCircuit,
+        unitary2: QuantumCircuit,
+        prefix1: str = "p1",
+        prefix2: str = "p2",
+        insert_barrier: bool = False,
+    ):
+        """
+        Args:
+            unitary1: Unitary acting on the ket vector.
+            unitary2: Unitary whose inverse operates on the bra vector.
+            prefix1: The name of the parameter vector associated to ``unitary1``,
+                if it is parameterized. Defaults to ``"p1"``.
+            prefix2: The name of the parameter vector associated to ``unitary2``,
+                if it is parameterized. Defaults to ``"p2"``.
+            insert_barrier: Whether to insert a barrier between the two unitaries.
+
+        Raises:
+            CircuitError: Number of qubits in ``unitary1`` and ``unitary2`` does not match.
+            CircuitError: Inputs contain measurements and/or resets.
+        """
+        circuit = unitary_overlap(unitary1, unitary2, prefix1, prefix2, insert_barrier)
+        super().__init__(*circuit.qregs, name=circuit.name)
+        self.compose(circuit, qubits=self.qubits, inplace=True)
+
+
+def _check_unitary(circuit):
+    """Check a circuit is unitary by checking if all operations are of type ``Gate``."""
+
+    for instruction in circuit.data:
+        if not isinstance(instruction.operation, (Gate, Barrier)):
+            raise CircuitError(
+                "One or more instructions cannot be converted to"
+                f' a gate. "{instruction.operation.name}" is not a gate instruction'
+            )
+
+
+def unitary_overlap(
+    unitary1: QuantumCircuit,
+    unitary2: QuantumCircuit,
+    prefix1: str = "p1",
+    prefix2: str = "p2",
+    insert_barrier: bool = False,
+) -> QuantumCircuit:
+    r"""Circuit that returns the overlap between two unitaries :math:`U_2^{\dag} U_1`.
+
+    The input quantum circuits must represent unitary operations, since they must be invertible.
+    If the inputs will have parameters, they are replaced by :class:`.ParameterVector`\s with
+    names `"p1"` (for circuit ``unitary1``) and `"p2"` (for circuit ``unitary_2``) in the output
+    circuit.
+
+    This circuit is usually employed in computing the fidelity:
+
+    .. math::
+
+        \left|\langle 0| U_2^{\dag} U_1|0\rangle\right|^{2}
+
+    by computing the probability of being in the all-zeros bit-string, or equivalently,
+    the expectation value of projector :math:`|0\rangle\langle 0|`.
+
+    **Reference Circuit:**
+
+    .. plot::
+        :include-source:
+
+        import numpy as np
+        from qiskit.circuit.library import EfficientSU2, unitary_overlap
+
+        # get two circuit to prepare states of which we compute the overlap
+        circuit = EfficientSU2(2, reps=1)
+        unitary1 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+        unitary2 = circuit.assign_parameters(np.random.random(circuit.num_parameters))
+
+        # create the overlap circuit
+        overlap = unitary_overlap(unitary1, unitary2)
+        overlap.draw('mpl')
+
+    Args:
+        unitary1: Unitary acting on the ket vector.
+        unitary2: Unitary whose inverse operates on the bra vector.
+        prefix1: The name of the parameter vector associated to ``unitary1``,
+            if it is parameterized. Defaults to ``"p1"``.
+        prefix2: The name of the parameter vector associated to ``unitary2``,
+            if it is parameterized. Defaults to ``"p2"``.
+        insert_barrier: Whether to insert a barrier between the two unitaries.
+
+    Raises:
+        CircuitError: Number of qubits in ``unitary1`` and ``unitary2`` does not match.
+        CircuitError: Inputs contain measurements and/or resets.
+    """
+    # check inputs are valid
+    if unitary1.num_qubits != unitary2.num_qubits:
+        raise CircuitError(
+            f"Number of qubits in unitaries does "
+            f"not match: {unitary1.num_qubits} != {unitary2.num_qubits}."
+        )
+
+    unitaries = [unitary1, unitary2]
+    for unitary in unitaries:
+        _check_unitary(unitary)
+
+    # Vectors of new parameters, if any. Need the unitaries in a list here to ensure
+    # we can overwrite them.
+    for i, prefix in enumerate([prefix1, prefix2]):
+        if unitaries[i].num_parameters > 0:
+            new_params = ParameterVector(prefix, unitaries[i].num_parameters)
+            unitaries[i] = unitaries[i].assign_parameters(new_params)
+
+    # Generate the actual overlap circuit
+    circuit = QuantumCircuit(unitaries[0].num_qubits, name="UnitaryOverlap")
+    circuit.compose(unitaries[0], inplace=True)
+    if insert_barrier:
+        circuit.barrier()
+    circuit.compose(unitaries[1].inverse(), inplace=True)
+    return circuit

qiskit/circuit/library/pauli_evolution.py

@@ -0,0 +1,186 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021, 2024.
+#
+# 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 gate to implement time-evolution of operators."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+import numpy as np
+
+from qiskit.circuit.gate import Gate
+from qiskit.circuit.quantumcircuit import ParameterValueType
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit.quantum_info import Pauli, SparsePauliOp
+
+if TYPE_CHECKING:
+    from qiskit.synthesis.evolution import EvolutionSynthesis
+
+
+class PauliEvolutionGate(Gate):
+    r"""Time-evolution of an operator consisting of Paulis.
+
+    For an operator :math:`H` consisting of Pauli terms and (real) evolution time :math:`t`
+    this gate implements
+
+    .. math::
+
+        U(t) = e^{-itH}.
+
+    This gate serves as a high-level definition of the evolution and can be synthesized into
+    a circuit using different algorithms.
+
+    The evolution gates are related to the Pauli rotation gates by a factor of 2. For example
+    the time evolution of the Pauli :math:`X` operator is connected to the Pauli :math:`X` rotation
+    :math:`R_X` by
+
+    .. math::
+
+        U(t) = e^{-itX} = R_X(2t).
+
+    **Examples:**
+
+    .. code-block:: python
+
+        from qiskit.circuit import QuantumCircuit
+        from qiskit.circuit.library import PauliEvolutionGate
+        from qiskit.quantum_info import SparsePauliOp
+
+        X = SparsePauliOp("X")
+        Z = SparsePauliOp("Z")
+        I = SparsePauliOp("I")
+
+        # build the evolution gate
+        operator = (Z ^ Z) - 0.1 * (X ^ I)
+        evo = PauliEvolutionGate(operator, time=0.2)
+
+        # plug it into a circuit
+        circuit = QuantumCircuit(2)
+        circuit.append(evo, range(2))
+        print(circuit.draw())
+
+    The above will print (note that the ``-0.1`` coefficient is not printed!)::
+
+             ┌──────────────────────────┐
+        q_0: ┤0                         ├
+             │  exp(-it (ZZ + XI))(0.2) │
+        q_1: ┤1                         ├
+             └──────────────────────────┘
+
+
+    **References:**
+
+    [1] G. Li et al. Paulihedral: A Generalized Block-Wise Compiler Optimization
+    Framework For Quantum Simulation Kernels (2021).
+    [`arXiv:2109.03371 <https://arxiv.org/abs/2109.03371>`_]
+    """
+
+    def __init__(
+        self,
+        operator: Pauli | SparsePauliOp | list[Pauli | SparsePauliOp],
+        time: ParameterValueType = 1.0,
+        label: str | None = None,
+        synthesis: EvolutionSynthesis | None = None,
+    ) -> None:
+        """
+        Args:
+            operator (Pauli | SparsePauliOp | list):
+                The operator to evolve. Can also be provided as list of non-commuting
+                operators where the elements are sums of commuting operators.
+                For example: ``[XY + YX, ZZ + ZI + IZ, YY]``.
+            time: The evolution time.
+            label: A label for the gate to display in visualizations. Per default, the label is
+                set to ``exp(-it <operators>)`` where ``<operators>`` is the sum of the Paulis.
+                Note that the label does not include any coefficients of the Paulis. See the
+                class docstring for an example.
+            synthesis: A synthesis strategy. If None, the default synthesis is the Lie-Trotter
+                product formula with a single repetition.
+        """
+        if isinstance(operator, list):
+            operator = [_to_sparse_pauli_op(op) for op in operator]
+        else:
+            operator = _to_sparse_pauli_op(operator)
+
+        if label is None:
+            label = _get_default_label(operator)
+
+        num_qubits = operator[0].num_qubits if isinstance(operator, list) else operator.num_qubits
+        super().__init__(name="PauliEvolution", num_qubits=num_qubits, params=[time], label=label)
+        self.operator = operator
+
+        if synthesis is None:
+            # pylint: disable=cyclic-import
+            from qiskit.synthesis.evolution import LieTrotter
+
+            synthesis = LieTrotter()
+
+        self.synthesis = synthesis
+
+    @property
+    def time(self) -> ParameterValueType:
+        """Return the evolution time as stored in the gate parameters.
+
+        Returns:
+            The evolution time.
+        """
+        return self.params[0]
+
+    @time.setter
+    def time(self, time: ParameterValueType) -> None:
+        """Set the evolution time.
+
+        Args:
+            time: The evolution time.
+        """
+        self.params = [time]
+
+    def _define(self):
+        """Unroll, where the default synthesis is matrix based."""
+        self.definition = self.synthesis.synthesize(self)
+
+    def validate_parameter(self, parameter: ParameterValueType) -> ParameterValueType:
+        """Gate parameters should be int, float, or ParameterExpression"""
+        if isinstance(parameter, int):
+            parameter = float(parameter)
+
+        return super().validate_parameter(parameter)
+
+
+def _to_sparse_pauli_op(operator):
+    """Cast the operator to a SparsePauliOp."""
+
+    if isinstance(operator, Pauli):
+        sparse_pauli = SparsePauliOp(operator)
+    elif isinstance(operator, SparsePauliOp):
+        sparse_pauli = operator
+    else:
+        raise ValueError(f"Unsupported operator type for evolution: {type(operator)}.")
+
+    if any(np.iscomplex(sparse_pauli.coeffs)):
+        raise ValueError("Operator contains complex coefficients, which are not supported.")
+    if any(isinstance(coeff, ParameterExpression) for coeff in sparse_pauli.coeffs):
+        raise ValueError("Operator contains ParameterExpression, which are not supported.")
+
+    return sparse_pauli
+
+
+def _get_default_label(operator):
+    if isinstance(operator, list):
+        label = f"exp(-it ({[' + '.join(op.paulis.to_labels()) for op in operator]}))"
+    else:
+        if len(operator.paulis) == 1:
+            label = f"exp(-it {operator.paulis.to_labels()[0]})"
+        # for just a single Pauli don't add brackets around the sum
+        else:
+            label = f"exp(-it ({' + '.join(operator.paulis.to_labels())}))"
+
+    return label

qiskit/circuit/library/phase_estimation.py

@@ -0,0 +1,175 @@
+# 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.
+
+"""Phase estimation circuit."""
+
+from __future__ import annotations
+
+from qiskit.circuit import QuantumCircuit, QuantumRegister
+from qiskit.utils.deprecation import deprecate_func
+from qiskit.circuit.library import QFT
+
+
+class PhaseEstimation(QuantumCircuit):
+    r"""Phase Estimation circuit.
+
+    In the Quantum Phase Estimation (QPE) algorithm [1, 2, 3], the Phase Estimation circuit is used
+    to estimate the phase :math:`\phi` of an eigenvalue :math:`e^{2\pi i\phi}` of a unitary operator
+    :math:`U`, provided with the corresponding eigenstate :math:`|\psi\rangle`.
+    That is
+
+    .. math::
+
+        U|\psi\rangle = e^{2\pi i\phi} |\psi\rangle
+
+    This estimation (and thereby this circuit) is a central routine to several well-known
+    algorithms, such as Shor's algorithm or Quantum Amplitude Estimation.
+
+    **References:**
+
+    [1]: Kitaev, A. Y. (1995). Quantum measurements and the Abelian Stabilizer Problem. 1–22.
+        `quant-ph/9511026 <http://arxiv.org/abs/quant-ph/9511026>`_
+
+    [2]: Michael A. Nielsen and Isaac L. Chuang. 2011.
+         Quantum Computation and Quantum Information: 10th Anniversary Edition (10th ed.).
+         Cambridge University Press, New York, NY, USA.
+
+    [3]: Qiskit
+        `textbook <https://github.com/Qiskit/textbook/blob/main/notebooks/ch-algorithms/
+        quantum-phase-estimation.ipynb>`_
+
+    """
+
+    @deprecate_func(
+        since="1.3",
+        additional_msg="Use qiskit.circuit.library.phase_estimation instead.",
+        pending=True,
+    )
+    def __init__(
+        self,
+        num_evaluation_qubits: int,
+        unitary: QuantumCircuit,
+        iqft: QuantumCircuit | None = None,
+        name: str = "QPE",
+    ) -> None:
+        """
+        Args:
+            num_evaluation_qubits: The number of evaluation qubits.
+            unitary: The unitary operation :math:`U` which will be repeated and controlled.
+            iqft: A inverse Quantum Fourier Transform, per default the inverse of
+                :class:`~qiskit.circuit.library.QFT` is used. Note that the QFT should not include
+                the usual swaps!
+            name: The name of the circuit.
+
+        .. note::
+
+            The inverse QFT should not include a swap of the qubit order.
+
+        Reference Circuit:
+            .. plot::
+
+               from qiskit.circuit import QuantumCircuit
+               from qiskit.circuit.library import PhaseEstimation
+               from qiskit.visualization.library import _generate_circuit_library_visualization
+               unitary = QuantumCircuit(2)
+               unitary.x(0)
+               unitary.y(1)
+               circuit = PhaseEstimation(3, unitary)
+               _generate_circuit_library_visualization(circuit)
+        """
+        qr_eval = QuantumRegister(num_evaluation_qubits, "eval")
+        qr_state = QuantumRegister(unitary.num_qubits, "q")
+        circuit = QuantumCircuit(qr_eval, qr_state, name=name)
+
+        if iqft is None:
+            iqft = QFT(num_evaluation_qubits, inverse=True, do_swaps=False).reverse_bits()
+
+        circuit.h(qr_eval)  # hadamards on evaluation qubits
+
+        for j in range(num_evaluation_qubits):  # controlled powers
+            circuit.compose(unitary.power(2**j).control(), qubits=[j] + qr_state[:], inplace=True)
+
+        circuit.compose(iqft, qubits=qr_eval[:], inplace=True)  # final QFT
+
+        super().__init__(*circuit.qregs, name=circuit.name)
+        self.compose(circuit.to_gate(), qubits=self.qubits, inplace=True)
+
+
+def phase_estimation(
+    num_evaluation_qubits: int,
+    unitary: QuantumCircuit,
+    name: str = "QPE",
+) -> QuantumCircuit:
+    r"""Phase Estimation circuit.
+
+    In the Quantum Phase Estimation (QPE) algorithm [1, 2, 3], the Phase Estimation circuit is used
+    to estimate the phase :math:`\phi` of an eigenvalue :math:`e^{2\pi i\phi}` of a unitary operator
+    :math:`U`, provided with the corresponding eigenstate :math:`|\psi\rangle`.
+    That is
+
+    .. math::
+
+        U|\psi\rangle = e^{2\pi i\phi} |\psi\rangle
+
+    This estimation (and thereby this circuit) is a central routine to several well-known
+    algorithms, such as Shor's algorithm or Quantum Amplitude Estimation.
+
+    Args:
+        num_evaluation_qubits: The number of evaluation qubits.
+        unitary: The unitary operation :math:`U` which will be repeated and controlled.
+        name: The name of the circuit.
+
+    **Reference Circuit:**
+
+    .. plot::
+       :include-source:
+
+       from qiskit.circuit import QuantumCircuit
+       from qiskit.circuit.library import phase_estimation
+       unitary = QuantumCircuit(2)
+       unitary.x(0)
+       unitary.y(1)
+       circuit = phase_estimation(3, unitary)
+       circuit.draw('mpl')
+
+    **References:**
+
+    [1]: Kitaev, A. Y. (1995). Quantum measurements and the Abelian Stabilizer Problem. 1–22.
+        `quant-ph/9511026 <http://arxiv.org/abs/quant-ph/9511026>`_
+
+    [2]: Michael A. Nielsen and Isaac L. Chuang. 2011.
+         Quantum Computation and Quantum Information: 10th Anniversary Edition (10th ed.).
+         Cambridge University Press, New York, NY, USA.
+
+    [3]: Qiskit
+        `textbook <https://github.com/Qiskit/textbook/blob/main/notebooks/ch-algorithms/
+        quantum-phase-estimation.ipynb>`_
+
+    """
+    # pylint: disable=cyclic-import
+    from qiskit.circuit.library import PermutationGate, QFTGate
+
+    qr_eval = QuantumRegister(num_evaluation_qubits, "eval")
+    qr_state = QuantumRegister(unitary.num_qubits, "q")
+    circuit = QuantumCircuit(qr_eval, qr_state, name=name)
+
+    circuit.h(qr_eval)  # hadamards on evaluation qubits
+
+    for j in range(num_evaluation_qubits):  # controlled powers
+        circuit.compose(unitary.power(2**j).control(), qubits=[j] + qr_state[:], inplace=True)
+
+    circuit.append(QFTGate(num_evaluation_qubits).inverse(), qr_eval[:])
+
+    reversal_pattern = list(reversed(range(num_evaluation_qubits)))
+    circuit.append(PermutationGate(reversal_pattern), qr_eval[:])
+
+    return circuit

qiskit/circuit/library/phase_oracle.py

@@ -0,0 +1,153 @@
+# 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."""
+
+# Needed to avoid type hints from erroring when `classicalfunction` might not be available.
+from __future__ import annotations
+
+from typing import Union, Callable, Optional, TYPE_CHECKING
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.utils import optionals as _optionals
+
+if TYPE_CHECKING:
+    from qiskit.circuit.classicalfunction.boolean_expression import BooleanExpression
+    from qiskit.circuit.classicalfunction.classical_element import ClassicalElement
+
+
+@_optionals.HAS_TWEEDLEDUM.require_in_instance
+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
+    `&` (`AND`), `|` (`OR`), `~` (`NOT`), and `^` (`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.
+
+    For convenience, this oracle, in addition to parsing arbitrary logical expressions,
+    also supports input strings in the `DIMACS CNF format
+    <http://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: Union[str, ClassicalElement],
+        synthesizer: Optional[Callable[[BooleanExpression], QuantumCircuit]] = None,
+        var_order: list = None,
+    ) -> None:
+        """Creates a PhaseOracle object
+
+        Args:
+            expression: A Python-like boolean expression.
+            synthesizer: Optional. A function to convert a BooleanExpression into a QuantumCircuit
+               If None is provided, Tweedledum's `pkrm_synth` with `phase_esop` will be used.
+            var_order(list): A list with the order in which variables will be created.
+               (default: by appearance)
+        """
+        from qiskit.circuit.classicalfunction.boolean_expression import BooleanExpression
+        from qiskit.circuit.classicalfunction.classical_element import ClassicalElement
+
+        if not isinstance(expression, ClassicalElement):
+            expression = BooleanExpression(expression, var_order=var_order)
+
+        self.boolean_expression = expression
+
+        if synthesizer is None:
+
+            def synthesizer(boolean_expression):
+                from tweedledum.synthesis import pkrm_synth  # pylint: disable=import-error
+                from qiskit.circuit.classicalfunction.utils import tweedledum2qiskit
+
+                truth_table = boolean_expression._tweedledum_bool_expression.truth_table(
+                    output_bit=0
+                )
+                tweedledum_circuit = pkrm_synth(truth_table, {"pkrm_synth": {"phase_esop": True}})
+                return tweedledum2qiskit(tweedledum_circuit)
+
+        oracle = expression.synth(synthesizer=synthesizer)
+
+        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
+        <http://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.
+        """
+        from qiskit.circuit.classicalfunction.boolean_expression import BooleanExpression
+
+        expr = BooleanExpression.from_dimacs_file(filename)
+        return cls(expr)