pyqit 0.1.0__py3-none-any.whl

pyqit/__init__.py

@@ -0,0 +1,19 @@
+from importlib.metadata import version as _version
+import logging
+
+__version__ = _version("pyqit")
+
+logging.getLogger("pyqit").addHandler(logging.NullHandler())
+
+from pyqit.core.config import get_backend, set_backend, set_seed
+from pyqit.core.trainer import Trainer
+from pyqit.data.datamodule import DataModule
+
+__all__ = [
+    "DataModule",
+    "Trainer",
+    "__version__",
+    "get_backend",
+    "set_backend",
+    "set_seed",
+]

pyqit/ansatzes/__init__.py

@@ -0,0 +1,18 @@
+"""A module for quantum ansatzes."""
+
+from pyqit.ansatzes.base import BaseAnsatz
+from pyqit.ansatzes.basic_entangler import BasicEntanglerAnsatz
+from pyqit.ansatzes.cnot_ladder import CNOTLadderAnsatz
+from pyqit.ansatzes.hardware_efficient import EfficientSU2Ansatz, RealAmplitudesAnsatz
+from pyqit.ansatzes.sel import SELAnsatz
+from pyqit.ansatzes.simplified_two_design import SimplifiedTwoDesignAnsatz
+
+__all__ = [
+    "BaseAnsatz",
+    "BasicEntanglerAnsatz",
+    "CNOTLadderAnsatz",
+    "EfficientSU2Ansatz",
+    "RealAmplitudesAnsatz",
+    "SELAnsatz",
+    "SimplifiedTwoDesignAnsatz",
+]

pyqit/ansatzes/base.py

@@ -0,0 +1,60 @@
+from abc import abstractmethod
+
+from pyqit.base.base_object import _PyQitObject
+
+
+class BaseAnsatz(_PyQitObject):
+    """Base class for a parameterized quantum circuit block."""
+
+    _tags = {
+        "object_type": "ansatz",
+        "ansatz_type": None,
+        "n_qubits_min": 1,
+        "differentiable": None,
+    }
+
+    def __init__(self, n_qubits: int, n_layers: int = 1):
+        """
+        Base configuration for any Quantum Ansatz.
+
+        Parameters
+        ----------
+            n_qubits: int
+                The number of wires in the circuit.
+            n_layers: int
+                The depth of the circuit (repeating blocks).
+        """
+        self.n_qubits = n_qubits
+        self.n_layers = n_layers
+        super().__init__()
+
+    @abstractmethod
+    def build_circuit(self, weights):
+        """
+        The actual PennyLane circuit logic.
+
+        Parameters
+        ----------
+            weights:
+                Trainable parameters.
+        """
+        pass
+
+    @abstractmethod
+    def get_weight_shapes(self) -> dict:
+        """
+        Returns the shape of trainable weights required by this ansatz.
+        Used by wrappers to initialize parameters.
+
+        Returns
+        -------
+            dict:
+                e.g., {"weights": (n_layers, n_qubits, 3)}
+        """
+        pass
+
+    def get_circuit_func(self):
+        """
+        Returns the bound method to be passed to a QNode.
+        """
+        return self.build_circuit

pyqit/ansatzes/basic_entangler.py

@@ -0,0 +1,46 @@
+import pennylane as qml
+
+from pyqit.ansatzes.base import BaseAnsatz
+
+
+class BasicEntanglerAnsatz(BaseAnsatz):
+    """Basic entangler layers: one rotation per qubit and a CNOT ring per layer.
+
+    Wraps PennyLane's `BasicEntanglerLayers` (Schuld et al. 2020 lineage).
+    The weights are one tensor, `weights`, of shape `(n_layers, n_qubits)`.
+
+    Parameters
+    ----------
+    n_qubits : int
+    n_layers : int, default 2
+    rotation : type, optional
+        Single-qubit rotation gate class. PennyLane's default is `qml.RX`.
+
+    Examples
+    --------
+    >>> import pennylane as qml
+    >>> from pyqit.ansatzes import BasicEntanglerAnsatz
+    >>> ansatz = BasicEntanglerAnsatz(n_qubits=4, n_layers=2, rotation=qml.RY)
+    >>> ansatz.get_weight_shapes()
+    {'weights': (2, 4)}
+    """
+
+    def __init__(self, n_qubits: int, n_layers: int = 2, rotation=None):
+        self.rotation = rotation
+        super().__init__(n_qubits, n_layers)
+
+    def build_circuit(self, weights):
+        """Apply the layers. Expects `weights["weights"]` of shape
+        `(n_layers, n_qubits)`."""
+        qml.BasicEntanglerLayers(
+            weights["weights"], wires=range(self.n_qubits), rotation=self.rotation
+        )
+
+    def get_weight_shapes(self) -> dict:
+        """Return `{"weights": (n_layers, n_qubits)}`."""
+        return {"weights": qml.BasicEntanglerLayers.shape(self.n_layers, self.n_qubits)}
+
+    @classmethod
+    def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
+        return [{"n_qubits": 3, "n_layers": 2}, {"n_qubits": 2, "rotation": qml.RY}]

pyqit/ansatzes/cnot_ladder.py

@@ -0,0 +1,45 @@
+import pennylane as qml
+
+from pyqit.ansatzes.base import BaseAnsatz
+
+
+class CNOTLadderAnsatz(BaseAnsatz):
+    """The variational block of Mari et al. (2020): a CNOT ladder, then RY.
+
+    Each layer applies CNOT to the wire pairs ``(0, 1), (2, 3), ...``, then to
+    ``(1, 2), (3, 4), ...``, then one RY per wire.
+
+    Parameters
+    ----------
+    n_qubits : int
+    n_layers : int, default 6
+        ``q_depth`` in the paper.
+
+    References
+    ----------
+    Mari, Bromley, Izaac, Schuld, Killoran, "Transfer learning in hybrid
+    classical-quantum neural networks", Quantum 4, 340 (2020). PennyLane's
+    "Quantum transfer learning" demo is the reference implementation.
+    """
+
+    def __init__(self, n_qubits: int, n_layers: int = 6):
+        super().__init__(n_qubits, n_layers)
+
+    def build_circuit(self, weights):
+        """Apply the layers. Expects `weights["weights"]` of shape
+        `(n_layers, n_qubits)`."""
+        for layer in range(self.n_layers):
+            for start in (0, 1):
+                for i in range(start, self.n_qubits - 1, 2):
+                    qml.CNOT(wires=[i, i + 1])
+            for w in range(self.n_qubits):
+                qml.RY(weights["weights"][layer, w], wires=w)
+
+    def get_weight_shapes(self) -> dict:
+        """Return `{"weights": (n_layers, n_qubits)}`."""
+        return {"weights": (self.n_layers, self.n_qubits)}
+
+    @classmethod
+    def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
+        return [{"n_qubits": 3, "n_layers": 2}, {"n_qubits": 2}]

pyqit/ansatzes/hardware_efficient.py

@@ -0,0 +1,101 @@
+import pennylane as qml
+from skbase.utils.dependencies import _check_soft_dependencies
+
+from pyqit.ansatzes.base import BaseAnsatz
+
+
+class RealAmplitudesAnsatz(BaseAnsatz):
+    """Qiskit's `RealAmplitudes`: RY layers separated by CX entanglers.
+
+    The hardware-efficient ansatz of Kandala et al. 2017 (Nature) as Qiskit's
+    circuit library builds it, and the default ansatz of Qiskit ML's `VQC`.
+    The circuit is Qiskit's own, converted through the `pennylane-qiskit`
+    plugin, so it needs the `qiskit` extra and Python 3.11 or newer.
+
+    The weights are Qiskit's flat parameter vector, `weights`, of shape
+    `(n_qubits * (n_layers + 1),)`. With `skip_final_rotation_layer` it is
+    `(n_qubits * n_layers,)`.
+
+    Parameters
+    ----------
+    n_qubits : int
+    n_layers : int, default 3
+        Qiskit's `reps`: the number of entangling blocks. Rotation layers
+        number `n_layers + 1` unless `skip_final_rotation_layer`.
+    entanglement : str, default "reverse_linear"
+        Any entanglement Qiskit accepts, e.g. `"linear"`, `"full"`,
+        `"circular"`.
+    skip_final_rotation_layer : bool, default False
+
+    References
+    ----------
+    Kandala et al., "Hardware-efficient variational quantum eigensolver for
+    small molecules and quantum magnets", Nature 549, 242 (2017).
+
+    Examples
+    --------
+    >>> from pyqit.ansatzes import RealAmplitudesAnsatz
+    >>> from pyqit.core import ZZFeatureMap
+    >>> from pyqit.models import VQCClassifier
+    >>> model = VQCClassifier(
+    ...     n_qubits=2, ansatz=RealAmplitudesAnsatz, encoder=ZZFeatureMap
+    ... )
+    """
+
+    _tags = {"python_dependencies": "pennylane-qiskit"}
+    _qiskit_circuit = "real_amplitudes"
+
+    def __init__(
+        self,
+        n_qubits: int,
+        n_layers: int = 3,
+        entanglement: str = "reverse_linear",
+        skip_final_rotation_layer: bool = False,
+    ):
+        self.entanglement = entanglement
+        self.skip_final_rotation_layer = skip_final_rotation_layer
+        super().__init__(n_qubits, n_layers)
+
+        if not _check_soft_dependencies("pennylane-qiskit", severity="none"):
+            raise ImportError(
+                f"{type(self).__name__} wraps Qiskit's circuit through the "
+                "pennylane-qiskit plugin, which is not installed. Install it with "
+                "`pip install pyqit[qiskit]`"
+            )
+        from qiskit.circuit import library
+
+        self.circuit = getattr(library, self._qiskit_circuit)(
+            n_qubits,
+            entanglement=entanglement,
+            reps=n_layers,
+            skip_final_rotation_layer=skip_final_rotation_layer,
+        )
+        self._template = qml.from_qiskit(self.circuit)
+
+    def build_circuit(self, weights):
+        """Apply the circuit. Expects `weights["weights"]` as a flat vector in
+        the order of `circuit.parameters`."""
+        self._template(weights["weights"])
+
+    def get_weight_shapes(self) -> dict:
+        """Return `{"weights": (n_params,)}`, Qiskit's flat parameter vector."""
+        return {"weights": (len(self.circuit.parameters),)}
+
+    @classmethod
+    def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
+        return [
+            {"n_qubits": 3, "n_layers": 2},
+            {"n_qubits": 2, "n_layers": 1, "entanglement": "circular"},
+        ]
+
+
+class EfficientSU2Ansatz(RealAmplitudesAnsatz):
+    """Qiskit's `EfficientSU2`: RY and RZ layers separated by CX entanglers.
+
+    `RealAmplitudesAnsatz` with an RZ layer after every RY layer, Qiskit's
+    default `su2_gates`. Same parameters and the same reference. The second
+    rotation doubles the weight vector to `(2 * n_qubits * (n_layers + 1),)`.
+    """
+
+    _qiskit_circuit = "efficient_su2"

pyqit/ansatzes/sel.py

@@ -0,0 +1,72 @@
+import pennylane as qml
+
+from pyqit.ansatzes.base import BaseAnsatz
+
+
+class SELAnsatz(BaseAnsatz):
+    """Strongly entangling layers of Schuld et al. (2020).
+
+    Wraps PennyLane's `StronglyEntanglingLayers`. Each layer applies three
+    rotations to every qubit, then a CNOT layer whose range grows with the
+    layer index. The weights are one tensor, `weights`, of shape
+    `(n_layers, n_qubits, 3)`.
+
+    Parameters
+    ----------
+    n_qubits : int
+    n_layers : int, default 2
+
+    References
+    ----------
+    Schuld, Bocharov, Svore, Wiebe, "Circuit-centric quantum classifiers",
+    Phys. Rev. A 101, 032308 (2020).
+
+    Examples
+    --------
+    >>> from pyqit.ansatzes import SELAnsatz
+    >>> from pyqit.models import VQCClassifier
+    >>> model = VQCClassifier(n_qubits=4, n_layers=3, ansatz=SELAnsatz)
+    """
+
+    def __init__(self, n_qubits: int, n_layers: int = 2):
+        super().__init__(n_qubits, n_layers)
+
+    def build_circuit(self, weights):
+        """
+        Construct and apply the strongly entangling layers to the quantum circuit.
+
+        Parameters
+        ----------
+        weights : dict
+            A dictionary containing the parameter tensors. Must include the
+            key `"weights"` with a tensor of shape `(n_layers, n_qubits, 3)`.
+
+        """
+        w_tensor = weights["weights"]
+        qml.templates.StronglyEntanglingLayers(w_tensor, wires=range(self.n_qubits))
+
+    def get_weight_shapes(self) -> dict:
+        """
+        Get the shapes of the trainable weights required by the ansatz.
+
+        Returns
+        -------
+        dict
+            A dictionary mapping the weight parameter name (`"weights"`) to
+            its expected shape tuple `(n_layers, n_qubits, 3)`.
+        """
+        shape = (self.n_layers, self.n_qubits, 3)
+        return {"weights": shape}
+
+    @classmethod
+    def get_test_params(cls):
+        """
+        Retrieve a set of default parameters for testing the ansatz.
+
+        Returns
+        -------
+        list of dict
+            A list containing a dictionary of valid initialization parameters
+            for the class.
+        """
+        return [{"n_qubits": 3, "n_layers": 2}]

pyqit/ansatzes/simplified_two_design.py

@@ -0,0 +1,59 @@
+import pennylane as qml
+
+from pyqit.ansatzes.base import BaseAnsatz
+
+
+class SimplifiedTwoDesignAnsatz(BaseAnsatz):
+    """Simplified two-design ansatz of Cerezo et al. 2021 (Nat. Commun.).
+
+    Wraps PennyLane's `SimplifiedTwoDesign`: an initial RY layer, then
+    `n_layers` of controlled-Z gates on alternating pairs each followed by RY
+    rotations. This is the circuit the local-cost trainability result was
+    proved on, so it pairs with the barren-plateau diagnostic.
+
+    There are two weight tensors, `initial_layer_weights` of shape
+    `(n_qubits,)` and `weights` of shape `(n_layers, n_qubits - 1, 2)`.
+
+    Parameters
+    ----------
+    n_qubits : int
+        At least 2.
+    n_layers : int, default 2
+
+    References
+    ----------
+    Cerezo, Sone, Volkoff, Cincio, Coles, "Cost function dependent barren
+    plateaus in shallow parametrized quantum circuits", Nat. Commun. 12, 1791
+    (2021).
+
+    Examples
+    --------
+    >>> from pyqit.ansatzes import SimplifiedTwoDesignAnsatz
+    >>> SimplifiedTwoDesignAnsatz(n_qubits=3, n_layers=2).get_weight_shapes()
+    {'initial_layer_weights': (3,), 'weights': (2, 2, 2)}
+    """
+
+    _tags = {"n_qubits_min": 2}
+
+    def __init__(self, n_qubits: int, n_layers: int = 2):
+        super().__init__(n_qubits, n_layers)
+
+    def build_circuit(self, weights):
+        """Apply the layers. Expects `weights["initial_layer_weights"]` of shape
+        `(n_qubits,)` and `weights["weights"]` of shape `(n_layers, n_qubits - 1, 2)`.
+        """
+        qml.SimplifiedTwoDesign(
+            weights["initial_layer_weights"],
+            weights["weights"],
+            wires=range(self.n_qubits),
+        )
+
+    def get_weight_shapes(self) -> dict:
+        """Return the two weight shapes, `initial_layer_weights` and `weights`."""
+        initial, layers = qml.SimplifiedTwoDesign.shape(self.n_layers, self.n_qubits)
+        return {"initial_layer_weights": initial, "weights": layers}
+
+    @classmethod
+    def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
+        return [{"n_qubits": 3, "n_layers": 2}, {"n_qubits": 2, "n_layers": 1}]

pyqit/base/__init__.py

@@ -0,0 +1,4 @@
+"""Base module for PyQit."""
+
+from pyqit.base._tags import OBJECT_TAGS, object_overview
+from pyqit.base.base_object import _PyQitObject, all_objects