squlearn 0.8.0__tar.gz → 0.8.1__tar.gz

{squlearn-0.8.0 → squlearn-0.8.1}/.github/workflows/publish_docs.yml

@@ -25,7 +25,7 @@ jobs:
             with:
               docs-folder: "docs/"
               pre-build-command: "pip3 install .[docs]"
-              build-command: "sphinx-build -b html . _build -W"
+              build-command: "sphinx-build -E -b html . _build -W"
           - name: Commit Files
             run: |
               cd docs/_build

{squlearn-0.8.0 → squlearn-0.8.1}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: squlearn
-Version: 0.8.0
-Summary: A library for quantum machine learning following the scikit-learnstandard.
+Version: 0.8.1
+Summary: A library for quantum machine learning following the scikit-learn standard.
 Keywords: quantum,machine learning,qml
 Author-email: David Kreplin <david.kreplin@ipa.fraunhofer.de>, Moritz Willmann <moritz.willmann@ipa.fraunhofer.de>, Jan Schnabel <jan.schnabel@ipa.fraunhofer.de>, Frederic Rapp <frederic.rapp@ipa.fraunhofer.de>, Manuel Hagelüken <manuel.hagelueken@ipa.fraunhofer.de>, Marco Roth <marco.roth@ipa.fraunhofer.de>
 Maintainer-email: David Kreplin <david.kreplin@ipa.fraunhofer.de>, Moritz Willmann <moritz.willmann@ipa.fraunhofer.de>
@@ -58,10 +58,10 @@ Provides-Extra: examples
 
 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.
+sQUlearn offers scikit-learn compatible high-level interfaces for various kernel methods, QNNs and quantum reservoir computing. 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.
 
 <p align="center">
-  <img width=500px alt="sQUlearn schematic" src="https://raw.githubusercontent.com/sQUlearn/squlearn/main/docs/_static/schematic.png" />
+  <img width=600px alt="sQUlearn schematic" src="https://raw.githubusercontent.com/sQUlearn/squlearn/main/docs/_static/schematic.png" />
 </p>
 
 ---

{squlearn-0.8.0 → squlearn-0.8.1}/README.md

@@ -4,10 +4,10 @@
 
 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.
+sQUlearn offers scikit-learn compatible high-level interfaces for various kernel methods, QNNs and quantum reservoir computing. 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.
 
 <p align="center">
-  <img width=500px alt="sQUlearn schematic" src="https://raw.githubusercontent.com/sQUlearn/squlearn/main/docs/_static/schematic.png" />
+  <img width=600px alt="sQUlearn schematic" src="https://raw.githubusercontent.com/sQUlearn/squlearn/main/docs/_static/schematic.png" />
 </p>
 
 ---

{squlearn-0.8.0 → squlearn-0.8.1}/docs/conf.py

@@ -107,9 +107,9 @@ latex_elements = {
 # intersphinx
 intersphinx_mapping = {
     "pennylane": ("https://docs.pennylane.ai/en/stable/", None),
-    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/1.1/", None),
+    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", 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),
+    "qiskit-ibm-runtime": ("https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "sklearn": ("https://scikit-learn.org/1.4/", None),
 }

squlearn-0.8.1/docs/examples/example_qnn_ode_solver.nblink

@@ -0,0 +1,6 @@
+{
+    "path": "../../examples/tutorials/qnn_ode_solver.ipynb",
+    "extra-media": [
+        "../../examples/tutorials/images"
+    ]
+}

{squlearn-0.8.0 → squlearn-0.8.1}/docs/examples/examples_index.rst

@@ -10,4 +10,5 @@ Examples
     example_kernel_digit_classification
     example_kernel_grid_search
     example_quantum_bayesian_optimization
-    example_qnn_backend_mitigation
+    example_qnn_backend_mitigation
+    example_qnn_ode_solver

{squlearn-0.8.0 → squlearn-0.8.1}/docs/user_guide/kernel_methods.rst

@@ -50,6 +50,21 @@ state [1]. In the quantum computational practice, the Hilbert-Schmidt inner prod
 measurements. Consequently, in quantum computing, access to the Hilbert space of quantum states is
 given by measurements.
 
+.. _figure 1:
+.. figure:: ../_static/qkm/QKM_scheme_pic.jpg
+    :alt: Quantum Kernel Methods
+    :width: 500
+    :align: center
+
+    **Figure 1** Schematic illustration of the function principle of quantum kernel methods, which can be formally embedded in the rich
+    mathematical framework of conventional kernel theory. Data points  :math:`\symbf{x}` are mapped to the quantum Hilbert space by
+    encoding them into a quantum state  :math:`\ket{\symbf{\psi}(\symbf{x})}`. Access to the quantum Hilbert space is granted by
+    measurements. :math:`\symbf{Left:}` In quantum mechanics measurements are expressed through Hilbert-Schmidt inner products. 
+    Quantum kernels, which are defined using this fidelity-type metric are thus referred to as fidelity quantum kernels (FQKs).
+    More on FQKs in sQUlearn will be discussed below. :math:`\symbf{Right:}` When projecting the quantum states to an approximate
+    classical representation using, e.g., reduced physical observables this gives rise to a family of projected quantum kernels (PQKs).
+    These will be also subject to discussion in the sQUlearn context below.
+
 
 .. currentmodule:: squlearn.kernel.ml
 

{squlearn-0.8.0 → squlearn-0.8.1}/docs/user_guide/quantum_neural_networks.rst

@@ -15,13 +15,13 @@ minimized by a classical optimizer. The resultant QNN can then be employed to pr
 for new input data.
 
 In many cases, QNNs adhere to a layered design, akin to classical neural networks, as illustrated
-in `figure 1`_. However, it is essential to note that they do not adhere to the concept of
+in `figure_qnn 1`_. However, it is essential to note that they do not adhere to the concept of
 neurons as seen in classical neural networks. Therefore, the term "Quantum Neural Network" may
 be somewhat misleading, as QNNs do not conform to the traditional neural network paradigm.
 Nevertheless, their application domain closely resembles that of classical neural networks,
 which explains the established nomenclature.
 
-.. _figure 1:
+.. _figure_qnn 1:
 .. figure:: ../_static/qnn/qnn.svg
     :alt: Quantum Neural Network (QNN)
     :width: 600
@@ -57,7 +57,7 @@ It's worth noting that both the embedding layers :math:`U_i({x})` and the observ
 
 To train Quantum Neural Networks (QNNs), a hybrid quantum-classical approach is employed.
 The training process consists of two phases: quantum circuit evaluation and classical optimization
-(as illustrated in `figure 1`_).
+(as illustrated in `figure_qnn 1`_).
 
 In the quantum circuit evaluation phase, the QNN and its gradient with respect to the parameters
 are assessed using a quantum computer or simulator. The gradient can be obtained using the
@@ -292,13 +292,13 @@ The noise level of the model thus depends on its variance, which can be calculat
     \sigma_f^2 = \langle\Psi\lvert\hat{C}^2\rvert\Psi\rangle -
     \langle\Psi\lvert\hat{C}\rvert\Psi\rangle^2 \text{.}
 
-`Figure 2`_ shows the output of a :class:`QNNRegressor` fit to a logarithm
+`Figure_qnn 3`_ shows the output of a :class:`QNNRegressor` fit to a logarithm
 with :class:`SquaredLoss <squlearn.qnn.loss.SquaredLoss>` evaluated on Qiskit's
 :class:`QasmSimulator <qiskit_aer.QasmSimulator>`.
 The model has been trained with a noise-free simulator, but evaluating it on a noisy simulator
 yields a high variance in the model output.
 
-.. _figure 2:
+.. _figure_qnn 2:
 .. plot::
     :caption: **Figure 2** Logarithm and output of :class:`QNNRegressor` :math:`f(\theta, x)` evaluated on Qiskit's
               :class:`QasmSimulator <qiskit_aer.QasmSimulator>`. The QNN output has a high variance.
@@ -359,9 +359,9 @@ takes the keyword argument ``iteration`` to dynamically adjust the factor. Value
 :math:`10^{-2}` and :math:`10^{-4}` have shown to yield satisfying results. `[1]`_
 
 Evaluation on Qiskit's :class:`QasmSimulator <qiskit_aer.QasmSimulator>` now yields less variance
-in the model, as depicted in `figure 3`_.
+in the model, as depicted in `figure_qnn 3`_.
 
-.. _figure 3:
+.. _figure_qnn 3:
 .. plot::
     :caption: **Figure 3** Logarithm and output of :class:`QNNRegressor` :math:`f(\theta, x)`, trained with variance
               regularization, evaluated on Qiskit's :class:`QasmSimulator <qiskit_aer.QasmSimulator>`.

squlearn-0.8.1/docs/user_guide/quantum_reservoir_computing.rst

@@ -0,0 +1,264 @@
+.. _quantum_reservoir_computing:
+
+.. currentmodule:: squlearn.qrc
+
+===========================
+Quantum Reservoir Computing
+===========================
+
+Reservoir Computing (RC) in general leverages a fixed, randomly connected network structure called the 'reservoir.'
+This is in strong contrast to conventional deep learning architectures, which performe the optimization of weight across all layers.
+In RC, the reservoir enables dynamic, nonlinear transformations of input data into a high-dimensional feature space, followed by linear regression to produce the output.
+Quantum Reservoir Computing (QRC) tries to take advantage of the exponential scaling dimension of the Hilbert space in the quantum computing context 
+to potentially provide an advantage over the classical RC. In QRC there is a register of accessable qubits :math:`\rho_0`, which are subject to
+encoding the classical information and measurements, and hidden qubits :math:`\rho_{\mathrm{hid}}`, which are related to the reservoir and 
+artifically raise the dimension, the reservoir dynamic acts on, by the size of the hidden register. The hidden qubits can either be provided by an additional register
+or interaction with the enviroment.
+
+First the classical input data :math:`x=\lbrace x^{(i)}\rbrace_{i=1}^D`, where :math:`D` denotes the samplesize, gets related to a unitary 
+evolution :math:`U(x)`, called encoding circuit, that evolves the initial state of the accessable qubits :math:`\rho_0` to 
+
+.. math::
+    \rho(x)=U(x)\rho_0U(x)^{\dagger}.
+
+Afterwards the reservoir dynamic :math:`U_R`  gets applied to the composite of the accessable and hidden qubits, i.e
+
+ .. math::
+    \tilde{\rho}(x)=U_R(\rho(x)\otimes \rho_{\mathrm{hid}})U_R^{\dagger}=U_R(U(x)\rho_0U(x)^{\dagger}\otimes \rho_{\mathrm{hid}})U_R^{\dagger}.
+
+Now using a set of (usually randomized) observables :math:`\lbrace O_1, \ldots, O_M \rbrace` the respective expecation-
+values
+
+.. math::
+    \langle O_j \rangle_x = \mathrm{Tr}(O_j \tilde{\rho}(x))
+
+are deteremined by measurements for all :math:`j = 1 ,\ldots,M`. The resulting vector 
+
+.. math::
+    \symbf{v}(x):= \begin{bmatrix}\langle O_1 \rangle_x\\\vdots\\\langle O_M \rangle_x\end{bmatrix}
+
+can be used to perform classical machine learning algorithms like linear regression. So the key advantage over QNN is
+that one does not optimize over the weights of a complex parametrized quantum circuit, but keeps the complex part fix and later 
+optimizes the readout vectors via cheaper algorithms.
+
+.. _figure_qrc 1:
+.. figure:: ../_static/qrc/QRC_user_guide.png
+    :alt: Quantum Reservoir Computing (QRC)
+    :width: 600
+    :align: center
+
+    **Figure 1** An example of a quantum reservoir computing circuit (see Ref. [1]). In the graphic we set the hidden qubits :math:`\rho_{\mathrm{hid}}` as :math:`\ket{000}`.
+    The encoding circuit (orange) and the quantum reservoir (blue) evolve the initial accessable qubit register :math:`\ket{\rho_0}` and
+    the composite of accessable and hidden qubits respectively. After the measurement with respect to the observable :math:`O_k` we can
+    repeat with similar circuits for all the other observables and use the expectation values to do classical machine learning.
+
+
+
+Note that in sQUlearn, there is no hidden qubit register available in the pre-configured encoding circuits. This can be constructed manually if needed, or if run on a 
+quantum computer, it may be due to the (non-controllable) interaction with the surrounding bath.
+
+With the outputs of our QRC circuit we construct the so called readout vector 
+
+.. math::
+    \symbf{v}^*(x)= \symbf{w}^\top \symbf{v}(x) = \sum\limits^M_{j=1} \symrm{w}_j \cdot \langle O_j \rangle_x,
+
+where :math:`\symbf{w}^\top = (\symrm{w}_1, \ldots, \symrm{w}_M)`, and the task of classical maschine learning is to determine the best collection of weights :math:`\symrm{w}_j`. This can 
+be done, for example, using a pseudo inverse method.
+
+High-level methods for QRC
+===========================
+
+As already mentioned the expectation values :math:`\langle O_j \rangle_x` will be used to carry out a classical maschine learning model. Usually one sticks to linear
+regression, since the complexity is transmitted to the reservoir. Nonetheless sQUlearn provides some additional options to choose from. 
+
+With sQUlearn it is possible to use QRC to do regression and classification tasks:
+
+.. autosummary::
+   :nosignatures:
+
+   QRCClassifier
+   QRCRegressor
+
+By passing either of both classes a fitting keyword argument ``mlp`` (multi-layer perceptron model), ``linear`` (linear model or single layer perceptron for classification) or 
+``kernel`` (support vector maschine) one can set the desired maschine learning model. 
+We will now go step by step through the implementation of an example QRC for both methods with sQUlearn. 
+
+Classification
+===============
+
+Setup
+-----
+
+First an foremost the encoding of the classical data onto the accessable qubits and the quantum reservoir preparation
+is done in sQUlearn by the :class:`EncodingCircuit` class. For details we refer to the documentations and examples in the user guidelines.
+
+.. jupyter-execute::
+
+    from squlearn.encoding_circuit import ChebyshevPQC
+
+    pqc = ChebyshevPQC(num_qubits=8, num_features=2, num_layers=2)
+    pqc.draw("mpl")
+
+Here we have chosen the :class:`~squlearn.encoding_circuit.ChebyshevPQC` as our encoding circuit, but sQUlearn provides a list of several alternative choices in :ref:`quantum_encoding_circuits`.
+The parameters are all randomly chosen. Next we also initialize our executor and QRCClassifier:
+
+.. code-block:: python
+
+    from squlearn import Executor
+    from squlearn.qrc.qrc_classifier import QRCClassifier
+
+    exec = Executor()
+    qrc = QRCClassifier(pqc, executor=exec, ml_model="linear", num_operators=200)
+
+The :class:`QRCClassifier` takes our prepared :class:`EncodingCircuit` and a machine learning method of our choice with
+linear regression as the default setting. In the last argument we can set the number of observables :math:`M`, which will be randomly chosen in
+order to measure the circuit and create the output vector :math:`\vec{v}` of size :math:`M`. For closer instructions on the 
+:class:`Executor` class we refer to :ref:`executor_user_guide` in the user guideline.
+
+Training
+--------
+
+Now we train our QRC model using the :class:`fit` method after we specify a certain dataset we like to train on:
+
+.. code-block:: python
+
+    from sklearn.datasets import make_moons
+    from sklearn.model_selection import train_test_split
+    from sklearn.preprocessing import MinMaxScaler
+
+    X, y = make_moons(n_samples=1000, noise=0.2, random_state=42)
+
+    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+    scaler = MinMaxScaler(feature_range=(-0.9, 0.9))
+    X_train = scaler.fit_transform(X_train)
+    X_test = scaler.transform(X_test)
+    
+    qrc.fit(X_train, y_train)
+
+Result
+------
+
+In the end we can plot our results and see how it worked:
+
+.. code-block:: python
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+
+    xx, yy = np.meshgrid(np.linspace(-1, 1, 50), np.linspace(-1, 1, 50))
+    Z = qrc.predict(np.c_[xx.ravel(), yy.ravel()])
+    Z = Z.reshape(xx.shape)
+
+    plt.contourf(xx, yy, Z, alpha=0.8)
+    plt.scatter(
+        X_train[:, 0], X_train[:, 1], c=y_train, edgecolor="k", marker="X", label="Training Data"
+    )
+    plt.scatter(X_test[:, 0], X_test[:, 1], c=y_test, edgecolor="k", marker="o", label="Test Data")
+    plt.xlabel("Feature 1")
+    plt.ylabel("Feature 2")
+    plt.title("QRC Classification Inference")
+    plt.legend()
+    plt.show()
+
+.. _figure_qrc 2:
+.. figure:: ../_static/qrc/qrc_classification_transparent.png
+    :alt: Classification
+    :width: 600
+    :align: center
+
+    **Figure 2** One can see that on this particular case the classification was very successful.
+    
+
+Regression
+==========
+
+Setup
+-----
+
+Just like in the classifier example we start by encoding the classical data and reservoir with the :class:`_encoding_circuit` class.
+This time, we choose the :class:`~squlearn.encoding_circuit.HubregtsenEncodingCircuit` as our encoding circuit, again with randomly picked parameters.
+
+.. jupyter-execute::
+
+    from squlearn.encoding_circuit import HubregtsenEncodingCircuit
+
+    pqc = HubregtsenEncodingCircuit(num_qubits=10, num_features=1, num_layers=2)
+    pqc.draw("mpl")
+
+
+The :class:`QRCRegressor` similar to the classifier example, takes our prepared :class:`EncodingCircuit` and a machine learning method 
+of our choice with linear regression as the default setting. In the last argument we again can determine the number of observables :math:`M`
+to measure the circuit and create the output vector :math:`\vec{v}` of size :math:`M`.
+
+.. code-block:: python
+
+    from squlearn import Executor
+    from squlearn.qrc import QRCRegressor
+
+    exec = Executor()
+    qrc = QRCRegressor(pqc, executor=exec, ml_model="linear", num_operators=200)
+
+
+Training
+--------
+
+.. code-block:: python
+
+    import numpy as np
+
+    X_train = np.arange(0.0, 1.0, 0.1)
+    y_train = np.exp(np.sin(10 * X_train))
+    X_train = X_train.reshape(-1, 1)
+
+    
+    X_test = np.arange(0.01, 1.0, 0.01)
+    y_test = np.exp(np.sin(10 * X_test))
+    X_test = X_test.reshape(-1, 1)
+    
+    qrc.fit(X_train, y_train)
+
+Now we evaluate the model by calculating the inference of the model and the training data set
+
+
+.. code-block:: python
+
+    y_pred = qrc.predict(X_test)
+
+
+Result
+------
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+    from sklearn.metrics import mean_squared_error, r2_score
+
+    print("Mean Squared Error:", mean_squared_error(y_test, y_pred))
+    print("R^2 Score:", r2_score(y_test, y_pred))
+
+    plt.plot(X_test, y_test, "-", color="blue", label="True Values")
+    plt.plot(X_test, y_pred, "-", color="red", label="Predictions")
+    plt.plot(X_train, y_train, "x", color="green", label="Training Set")
+    plt.xlabel("x")
+    plt.ylabel("f(x)")
+    plt.title("QRC Regression Inference")
+    plt.legend()
+    plt.show()
+
+.. _figure_qrc 3:
+.. figure:: ../_static/qrc/qrc_regression_transparent.png
+    :alt: Regression
+    :width: 600
+    :align: center
+
+    **Figure 3** The regression of our discrete data set fits the function locally with high precision.
+
+
+.. rubric:: References
+
+_`[1]` Xiong, Weijie, et al. "On fundamental aspects of quantum extreme learning machines"
+`arXiv:2312.15124 <https://arxiv.org/abs/2312.15124>`_ (2023).
+
+_`[2]` Suzuki, Y., Gao, Q., Pradel, K.C. et al. "Natural quantum reservoir computing for temporal information processing"
+`Sci Rep 12, 1353 <https://doi.org/10.1038/s41598-022-05061-w>`_ (2022).

{squlearn-0.8.0 → squlearn-0.8.1}/docs/user_guide/user_guide_index.rst

@@ -11,3 +11,4 @@ User Guide
    encoding_circuits
    kernel_methods
    quantum_neural_networks
+   quantum_reservoir_computing