Integration of HQS automatic backend selection

README.md

@@ -2,7 +2,7 @@
   <img alt="sQUlearn" src="https://raw.githubusercontent.com/sQUlearn/squlearn/main/docs/_static/logo.png" />
 </p>
 
-sQUlearn is a user-friendly, NISQ-ready Python library for quantum machine learning (QML), designed for seamless integration with classical machine learning tools like scikit-learn. The library's dual-layer architecture serves both QML researchers and practitioners, enabling efficient prototyping, experimentation, and pipelining. sQUlearn provides a comprehensive toolset that includes both quantum kernel methods and quantum neural networks, along with features like customizable data encoding strategies, automated execution handling, and specialized kernel regularization techniques. By focusing on NISQ-compatibility and end-to-end automation, sQUlearn aims to bridge the gap between current quantum computing capabilities and practical machine learning applications.
+sQUlearn is a user-friendly, NISQ-ready Python library for quantum machine learning (QML), designed for seamless integration with classical machine learning tools like scikit-learn. The library's dual-layer architecture serves both QML researchers and practitioners, enabling efficient prototyping, experimentation, and pipelining. sQUlearn provides a comprehensive tool set that includes both quantum kernel methods and quantum neural networks, along with features like customizable data encoding strategies, automated execution handling, and specialized kernel regularization techniques. By focusing on NISQ-compatibility and end-to-end automation, sQUlearn aims to bridge the gap between current quantum computing capabilities and practical machine learning applications.
 
 sQUlearn offers scikit-learn compatible high-level interfaces for various kernel methods and QNNs. They build on top of the low-level interfaces of the QNN engine and the quantum kernel engine. The executor is used to run experiments on simulated and real backends of the Qiskit or PennyLane frameworks.
 
@@ -39,7 +39,7 @@ pip install .[examples]
 ```
 
 ## Contribute to sQUlearn
-Thanks for considering to contribute to sQUlearn! Please read our [contribution guidelines](https://github.com/sQUlearn/squlearn/blob/main/.github/CONTRIBUTING.md) before you submit a pull request.
+Thanks for considering contributing to sQUlearn! Please read our [contribution guidelines](https://github.com/sQUlearn/squlearn/blob/main/.github/CONTRIBUTING.md) before you submit a pull request.
 
 ---
 ## License
@@ -61,11 +61,6 @@ For general questions regarding sQUlearn, use the [GitHub Discussions](https://g
 ---
 ## Acknowledgements
 
-This project was supported by the German Federal Ministry
-of Economic Affairs and Climate Action through the
-projects AutoQML (grant no. 01MQ22002A) and AQUAS
-(grant no. 01MQ22003D), as well as the German Federal 
-Ministry of Education and Research through the project
-H2Giga Degrad-EL3 (grant no. 03HY110D).
+This project was supported by the German Federal Ministry of Economic Affairs and Climate Action through the projects AutoQML (grant no. 01MQ22002A) and AQUAS (grant no. 01MQ22003D), as well as the German Federal Ministry of Education and Research through the project H2Giga Degrad-EL3 (grant no. 03HY110D).
 
----
+---

docs/conf.py

@@ -106,10 +106,12 @@ def setup(app):
 
 # intersphinx
 intersphinx_mapping = {
-    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", None),
+    "pennylane": ("https://docs.pennylane.ai/en/stable/", None),
+    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/1.1/", None),
     "qiskit-aer": ("https://qiskit.github.io/qiskit-aer/", None),
+    "qiskit-ibm-runtime": ("https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/0.27/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
-    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "sklearn": ("https://scikit-learn.org/1.4/", None),
 }
 
 suppress_warnings = ["myst.header", "config.cache"]

docs/modules/classes.rst

@@ -145,6 +145,8 @@ Execution Tools
    :template: class.rst
 
    Executor
+   util.executor.ExecutorEstimator
+   util.executor.ExecutorSampler
 
 
 Core

pyproject.toml

@@ -25,17 +25,19 @@ classifiers = [
 ]
 keywords = ["quantum", "machine learning", "qml"]
 dependencies = [
+    "bayesian-optimization>=1.4.3",
     "dill>=0.3",
-    "numpy>=1.17,<2.0",
-    "qiskit>=0.43.0,<1.1.0",
+    "mapomatic>=0.10.0",
+    "networkx>=3.0",
+    "numpy>=1.17",
+    "pennylane>=0.34.0",
+    "qiskit>=0.43.0,<1.2.0",
     "qiskit-aer>=0.12.0",
     "qiskit-algorithms>=0.3.0",
-    "qiskit-ibm-runtime>=0.15.1",
+    "qiskit-ibm-runtime>=0.15.1,<0.28.0",
     "qiskit-machine-learning>=0.6.1",
-    "pennylane>=0.34.0",
     "scipy>=1.5",
     "scikit-learn>=1.0,<1.4.2",
-    "bayesian-optimization>=1.4.3",
     "tqdm>=4.0",
 ]
 requires-python = ">=3.9"
@@ -60,6 +62,7 @@ examples = [
 ]
 docs = [
     "ipykernel",
+    "jupyter-sphinx",
     "matplotlib>=3.5",
     "myst-parser",
     "nbsphinx",
@@ -69,7 +72,6 @@ docs = [
     "sphinxcontrib-spelling",
     "sphinx-rtd-theme<3.0.0",
     "sphinx-sitemap",
-    "jupyter-sphinx",
 ]
 
 [project.urls]

src/squlearn/kernel/matrix/fidelity_kernel.py

@@ -116,6 +116,11 @@ def __init__(
             self._enc_circ = self._encoding_circuit.get_circuit(
                 self._feature_vector, self._parameter_vector
             )
+
+            # Automatic select backend if not chosen
+            if not self._executor.backend_chosen:
+                self._enc_circ, _ = self._executor.select_backend(self._enc_circ)
+
             if self._executor.is_statevector:
                 if self._parameter_vector is None:
                     self._quantum_kernel = FidelityStatevectorKernel(

src/squlearn/observables/observable_base.py

@@ -45,6 +45,7 @@ def set_map(self, qubit_map: Union[list, dict], num_all_qubits: int):
                                            qubits are mapped to the output qubits.
             num_all_qubits (int): The total number of qubits in the system.
         """
+
         self._qubit_map = qubit_map
         self._num_all_qubits = num_all_qubits
         self._is_mapped = True

src/squlearn/qnn/base_qnn.py

@@ -44,6 +44,11 @@ class BaseQNN(BaseEstimator, ABC):
         callback (Union[Callable, str, None], default=None): A callback for the optimization loop.
             Can be either a Callable, "pbar" (which uses a :class:`tqdm.tqdm` process bar) or None.
             If None, the optimizers (default) callback will be used.
+        primitive : The Qiskit primitive that is utilized in the qnn, if a Qiskit backend
+                    is used in the executor (not supported for PennyLane backends)
+                    Default primitive is the one specified in the executor initialization,
+                    if nothing is specified, the estimator will used.
+                    Possible values are ``"estimator"`` or ``"sampler"``.
     """
 
     def __init__(
@@ -65,6 +70,7 @@ def __init__(
         caching: bool = True,
         pretrained: bool = False,
         callback: Union[Callable, str, None] = None,
+        primitive: Union[str, None] = None,
         **kwargs,
     ) -> None:
         super().__init__()
@@ -117,6 +123,7 @@ def __init__(
         self.caching = caching
         self.pretrained = pretrained
 
+        self.primitive = primitive
         self.executor = executor
 
         self.shot_control = shot_control
@@ -324,7 +331,11 @@ def _fit(self, X, y, weights: np.ndarray = None) -> None:
 
     def _initialize_lowlevel_qnn(self):
         self._qnn = LowLevelQNN(
-            self.encoding_circuit, self.operator, self.executor, caching=self.caching
+            self.encoding_circuit,
+            self.operator,
+            self.executor,
+            caching=self.caching,
+            primitive=self.primitive,
         )
 
     def _validate_input(self, X, y, incremental, reset):

src/squlearn/qnn/lowlevel_qnn.py

@@ -34,6 +34,9 @@ def __new__(
     ):
 
         if executor.quantum_framework == "pennylane":
+            if "primitive" in kwargs:
+                RuntimeError("Warning: Primitive argument is not supported for PennyLane")
+                kwargs.pop("primitive")
             return LowLevelQNNPennyLane(
                 parameterized_quantum_circuit, observable, executor, *args, **kwargs
             )

src/squlearn/qnn/lowlevel_qnn_qiskit.py

@@ -19,6 +19,8 @@
 
 from .lowlevel_qnn_base import LowLevelQNNBase
 
+import copy
+
 
 class Expec:
     """Data structure that holds the set-up of derivative of the expectation value.
@@ -275,6 +277,9 @@ class LowLevelQNNQiskit(LowLevelQNNBase):
         executor (Executor) : Executor that is used for the evaluation of the QNN
         caching : Caching of the result for each `x`, `param`, `param_op` combination
             (default = True)
+        primitive (str): Primitive that is used for the evaluation of the QNN. Possible values are
+            ``"estimator"`` or ``"sampler"``. If None, the primitive is set according to the
+            executor. (default = None)
 
     Attributes:
     -----------
@@ -300,25 +305,65 @@ def __init__(
         operator: Union[ObservableBase, list],
         executor: Executor,
         caching=True,
+        primitive: Union[str, None] = None,
     ) -> None:
 
-        parameterized_quantum_circuit = TranspiledEncodingCircuit(
-            parameterized_quantum_circuit, executor.backend
-        )
+        self.caching = caching
+
+        if executor.backend_chosen:
+            # Skip transpilation for parallel qpu execution
+            if not executor.qpu_parallelization:
+                parameterized_quantum_circuit = TranspiledEncodingCircuit(
+                    parameterized_quantum_circuit, executor.backend
+                )
+        else:
+            # Automatically select backend (also returns a TranspiledEncodingCircuit except
+            # for parallel qpu execution)
+            parameterized_quantum_circuit, _ = executor.select_backend(
+                parameterized_quantum_circuit
+            )
+
         super().__init__(parameterized_quantum_circuit, operator, executor)
 
-        self.caching = caching
+        self.operator = copy.deepcopy(operator)
 
         # Set-Up Executor
-        if self._executor.optree_executor == "estimator":
-            self._estimator = self._executor.get_estimator()
-            self._sampler = None
-        else:
-            self._sampler = self._executor.get_sampler()
-            self._estimator = None
+        self._set_primitive(primitive)
 
+        # Initialize derivative classes
         self._initilize_derivative()
 
+    def _set_primitive(self, primitive: Union[str, None] = None) -> None:
+        """
+        Sets the primitive for evaluating the of the QNN.
+
+        Args:
+            primitive (str): Primitive that is used for the evaluation of the QNN.
+                Can be ``"estimator"`` or ``"sampler"``. If None, the primitive is set
+                according to the executor. (default = None)
+
+        """
+        if primitive is None:
+            if self._executor.optree_executor == "estimator":
+                self._estimator = self._executor.get_estimator()
+                self._sampler = None
+                self._primitive = "estimator"
+            else:
+                self._sampler = self._executor.get_sampler()
+                self._estimator = None
+                self._primitive = "sampler"
+        else:
+            if primitive.lower() == "estimator":
+                self._estimator = self._executor.get_estimator()
+                self._sampler = None
+                self._primitive = "estimator"
+            elif primitive.lower() == "sampler":
+                self._sampler = self._executor.get_sampler()
+                self._estimator = None
+                self._primitive = "sampler"
+            else:
+                raise ValueError("Unknown primitive:", primitive)
+
     def get_params(self, deep: bool = True) -> dict:
         """Returns the dictionary of the hyper-parameters of the QNN.
 
@@ -327,6 +372,7 @@ def get_params(self, deep: bool = True) -> dict:
 
         """
         params = dict(num_qubits=self.num_qubits)
+        params["primitive"] = self._primitive
 
         if deep:
             params.update(self._pqc.get_params())
@@ -360,6 +406,10 @@ def set_params(self, **params) -> None:
                     f"Valid parameters are {sorted(valid_params)!r}."
                 )
 
+        if "primitive" in params:
+            self._set_primitive(params["primitive"])
+            params.pop("primitive")
+
         # Set parameters of the PQC
         dict_pqc = {}
         for key, value in params.items():

src/squlearn/qnn/qnnc.py

@@ -57,6 +57,10 @@ class QNNClassifier(BaseQNN, ClassifierMixin):
         callback (Union[Callable, str, None], default=None): A callback for the optimization loop.
             Can be either a Callable, "pbar" (which uses a :class:`tqdm.tqdm` process bar) or None.
             If None, the optimizers (default) callback will be used.
+        primitive (Union[str,None], default=None): The primitive that is utilized in the qnn.
+            Default primitive is the one specified in the executor initialization, if nothing is
+            specified, the estimator will used. Possible values are ``"estimator"`` or
+            ``"sampler"``.
 
     See Also
     --------
@@ -115,6 +119,7 @@ def __init__(
         caching: bool = True,
         pretrained: bool = False,
         callback: Union[Callable, str, None] = "pbar",
+        primitive: Union[str, None] = None,
         **kwargs,
     ) -> None:
         super().__init__(

src/squlearn/qnn/qnnr.py

@@ -58,6 +58,10 @@ class QNNRegressor(BaseQNN, RegressorMixin):
         callback (Union[Callable, str, None], default=None): A callback for the optimization loop.
             Can be either a Callable, "pbar" (which uses a :class:`tqdm.tqdm` process bar) or None.
             If None, the optimizers (default) callback will be used.
+        primitive (Union[str,None], default=None): The primitive that is utilized in the qnn.
+            Default primitive is the one specified in the executor initialization, if nothing is
+            specified, the estimator will used. Possible values are ``"estimator"`` or
+            ``"sampler"``.
 
     See Also
     --------
@@ -165,6 +169,7 @@ def __init__(
         caching: bool = True,
         pretrained: bool = False,
         callback: Union[Callable, str, None] = "pbar",
+        primitive: Union[str, None] = None,
         **kwargs,
     ) -> None:
         super().__init__(
@@ -185,6 +190,7 @@ def __init__(
             caching=caching,
             pretrained=pretrained,
             callback=callback,
+            primitive=primitive,
             **kwargs,
         )
 

src/squlearn/util/execution/__init__.py

@@ -0,0 +1,9 @@
+from .backend_auto_selection import AutoSelectionBackend
+from .parallel_estimator import ParallelEstimator
+from .parallel_sampler import ParallelSampler
+
+__all__ = [
+    "AutoSelectionBackend",
+    "ParallelEstimator",
+    "ParallelSampler",
+]