squlearn 0.8.0__tar.gz → 0.8.2__tar.gz

{squlearn-0.8.0 → squlearn-0.8.2}/.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.2}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: squlearn
-Version: 0.8.0
-Summary: A library for quantum machine learning following the scikit-learnstandard.
+Version: 0.8.2
+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>
@@ -10,19 +10,20 @@ Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
+License-File: LICENSE.txt
 Requires-Dist: bayesian-optimization>=1.4.3,<2
 Requires-Dist: dill>=0.3.4
 Requires-Dist: mapomatic>=0.10.0
 Requires-Dist: networkx>=3.0
 Requires-Dist: numpy>=1.20
 Requires-Dist: pennylane>=0.34.0
-Requires-Dist: qiskit>=0.45.0
+Requires-Dist: qiskit>=0.45.0,<2
 Requires-Dist: qiskit-aer>=0.12.0
 Requires-Dist: qiskit-algorithms>=0.3.0
 Requires-Dist: qiskit-ibm-runtime>=0.18.0
 Requires-Dist: qiskit-machine-learning>=0.7.0
 Requires-Dist: scipy>=1.8.0
-Requires-Dist: scikit-learn>=1.2.0,<1.4.2
+Requires-Dist: scikit-learn>=1.2.0
 Requires-Dist: tqdm>=4.1.0
 Requires-Dist: black ; extra == "dev"
 Requires-Dist: flit ; extra == "dev"
@@ -58,10 +59,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.2}/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.2}/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.2/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.2}/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.2}/docs/modules/classes.rst

@@ -16,9 +16,9 @@ QML Regressors
    :toctree: generated/
    :template: class.rst
 
-   kernel.ml.QSVR
-   kernel.ml.QKRR
-   kernel.ml.QGPR
+   kernel.QSVR
+   kernel.QKRR
+   kernel.QGPR
    qnn.QNNRegressor
    qrc.QRCRegressor
 
@@ -33,8 +33,8 @@ QML Classifiers
    :toctree: generated/
    :template: class.rst
 
-   kernel.ml.QSVC
-   kernel.ml.QGPC
+   kernel.QSVC
+   kernel.QGPC
    qnn.QNNClassifier
    qrc.QRCClassifier
 
@@ -155,7 +155,7 @@ Core
 Quantum Kernel Core
 ------------------------------------
 
-.. automodule:: squlearn.kernel.matrix
+.. automodule:: squlearn.kernel.lowlevel_kernel
     :no-members:
     :no-inherited-members:
 
@@ -166,8 +166,8 @@ Quantum Kernel Core
    :toctree: generated/
    :template: class.rst
 
-   kernel.matrix.FidelityKernel
-   kernel.matrix.ProjectedQuantumKernel
+   kernel.lowlevel_kernel.FidelityKernel
+   kernel.lowlevel_kernel.ProjectedQuantumKernel
 
 .. automodule:: squlearn.kernel.loss
     :no-members:
@@ -198,10 +198,10 @@ QNN Core
    :template: class.rst
 
    qnn.lowlevel_qnn.LowLevelQNN
-   qnn.lowlevel_qnn_qiskit.LowLevelQNNQiskit
-   qnn.lowlevel_qnn_qiskit.Expec
-   qnn.lowlevel_qnn_pennylane.LowLevelQNNPennyLane
-   qnn.lowlevel_qnn_base.LowLevelQNNBase
+   qnn.lowlevel_qnn.lowlevel_qnn_qiskit.LowLevelQNNQiskit
+   qnn.lowlevel_qnn.lowlevel_qnn_qiskit.Expec
+   qnn.lowlevel_qnn.lowlevel_qnn_pennylane.LowLevelQNNPennyLane
+   qnn.lowlevel_qnn.lowlevel_qnn_base.LowLevelQNNBase
    qnn.loss.SquaredLoss
    qnn.loss.VarianceLoss
    qnn.loss.ODELoss
@@ -214,11 +214,11 @@ Tools for training QNNs
    :toctree: generated/
    :template: class.rst
 
-   qnn.get_variance_fac
-   qnn.get_lr_decay
-   qnn.ShotsFromRSTD
-   qnn.training.train
-   qnn.training.train_mini_batch
+   qnn.util.get_variance_fac
+   qnn.util.get_lr_decay
+   qnn.util.ShotsFromRSTD
+   qnn.util.training.train
+   qnn.util.training.train_mini_batch
 
 
 Implemented optimizers
@@ -286,11 +286,11 @@ Base Classes
 
     observables.observable_base.ObservableBase
     encoding_circuit.encoding_circuit_base.EncodingCircuitBase
-    kernel.matrix.kernel_matrix_base.KernelMatrixBase
+    kernel.lowlevel_kernel.kernel_matrix_base.KernelMatrixBase
     kernel.loss.kernel_loss_base.KernelLossBase
     optimizers.optimizer_base.OptimizerBase
     qnn.base_qnn.BaseQNN
-    qnn.loss.LossBase
+    qnn.loss.qnn_loss_base.QNNLossBase
     qrc.base_qrc.BaseQRC
 
 

{squlearn-0.8.0 → squlearn-0.8.2}/docs/user_guide/executor.rst

@@ -143,7 +143,7 @@ execution environment:
     executor = Executor(dev, shots = 1234)
 
 
-- A :class:`Backend <qiskit.providers.Backend>` from :class:`QiskitRuntimeService <qiskit_ibm_runtime.QiskitRuntimeService>`'s :meth:`get_backend <qiskit_ibm_runtime.QiskitRuntimeService.get_backend>` method, which utilizes the execution of quantum jobs on IBM Quantum.
+- A :class:`Backend <qiskit.providers.Backend>` from :class:`QiskitRuntimeService <qiskit_ibm_runtime.QiskitRuntimeService>`'s :meth:`backend <qiskit_ibm_runtime.QiskitRuntimeservice.backend>` method, which utilizes the execution of quantum jobs on IBM Quantum.
   Sessions and Primitives are automatically created and managed by the :class:`Executor <squlearn.Executor>` class (remember to close the session at the end of your code when running on IBM Quantum).
 
   .. code-block:: python
@@ -152,7 +152,7 @@ execution environment:
     from qiskit_ibm_runtime import QiskitRuntimeService
 
     service = QiskitRuntimeService(channel="ibm_quantum", token="INSERT_YOUR_TOKEN_HERE")
-    executor = Executor(service.get_backend('ibm_brisbane'))
+    executor = Executor(service.backend('ibm_brisbane'))
     ...
     # Close the session at the end of your code
     executor.close_session()
@@ -179,7 +179,7 @@ execution environment:
     from qiskit_ibm_runtime import QiskitRuntimeService
 
     service = QiskitRuntimeService(channel="ibm_quantum", token="INSERT_YOUR_TOKEN_HERE")
-    session = service.create_session(backend = service.get_backend('ibm_brisbane'))
+    session = service.create_session(backend = service.backend('ibm_brisbane'))
     executor = Executor(session)
     ...
     executor.close_session()
@@ -195,7 +195,7 @@ execution environment:
 
     service = QiskitRuntimeService(channel="ibm_quantum", token="INSERT_YOUR_TOKEN_HERE")
 
-    session = service.create_session(backend = service.get_backend('ibm_brisbane'))
+    session = service.create_session(backend = service.backend('ibm_brisbane'))
     estimator = Estimator(session=session)
     estimator.options.resilience.zne_mitigation = True
     estimator.options.resilience.zne.noise_factors = (1, 3, 5)
@@ -233,7 +233,7 @@ backend from the :class:`QiskitRuntimeService <qiskit_ibm_runtime.QiskitRuntimeS
                              "zne":{"noise_factors" : (1, 3, 5),"extrapolator":"linear" }}
               }
 
-    executor = Executor(service.get_backend('ibm_brisbane'), # Specify the backend
+    executor = Executor(service.backend('ibm_brisbane'), # Specify the backend
                          cache_dir='cache', # Set cache folder to "cache"
                          caching=True, # Enable caching default for remote executions
                          log_file="executor.log", # Set-up logging file
@@ -296,7 +296,7 @@ They folow the same dictionary datastructure than the original V2 Primtives.
                              "zne":{"noise_factors" : (1, 3, 5),"extrapolator":"linear" }}
               }
 
-    executor = Executor(service.get_backend("ibm_brisbane"),options_estimator=options)
+    executor = Executor(service.backend("ibm_brisbane"),options_estimator=options)
 
 Alternatively, the options can be adjusted by the attributes :meth:`estimator_options` and :meth:`sampler_options` similar
 to the option interface of the V2 Primtives:
@@ -307,7 +307,7 @@ to the option interface of the V2 Primtives:
     from qiskit_ibm_runtime import QiskitRuntimeService
 
     service = QiskitRuntimeService(channel="ibm_quantum", token="INSERT_YOUR_TOKEN_HERE")
-    executor = Executor(service.get_backend("ibm_brisbane"))
+    executor = Executor(service.backend("ibm_brisbane"))
     executor.sampler_options.dynamical_decoupling.enable = True
     executor.sampler_options.dynamical_decoupling.sequence_type = "XpXm"
 
@@ -321,7 +321,7 @@ Options can be adjusted by the :meth:`set_options` method of the Primitives that
 
     service = QiskitRuntimeService(channel="ibm_quantum", token="INSERT_YOUR_TOKEN_HERE")
 
-    executor = Executor(service.get_backend("ibm_brisbane"))
+    executor = Executor(service.backend("ibm_brisbane"))
     estimator = executor.get_estimator()
     estimator.set_options(resilience_level=2)
 

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

@@ -50,8 +50,23 @@ 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
+
+.. currentmodule:: squlearn.kernel
 
 High-Level methods that employ quantum kernels
 ----------------------------------------------
@@ -117,7 +132,7 @@ kernel matrices using either *thresholding* or *tikhonov* approach as described
 Regularization is by default switched of but can be set via the :code:`regularization`
 argument.
 
-.. currentmodule:: squlearn.kernel.matrix
+.. currentmodule:: squlearn.kernel.lowlevel_kernel
 
 Fidelity Quantum Kernel (FQK) via :class:`FidelityKernel`
 #########################################################

{squlearn-0.8.0 → squlearn-0.8.2}/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
@@ -239,13 +239,13 @@ This is possible by providing a :class:`List` or a :class:`Callable` to the lear
 Then a learning rate is chosen from the list or calculated by the callable at the beginning of
 each iteration or epoch.
 A suitable function for generating a callable with an exponential decay of the learning rate is
-provided by :meth:`get_lr_decay`. The following example will generate an Adam optimization
+provided by :meth:`util.get_lr_decay`. The following example will generate an Adam optimization
 with an exponential decay in the learning rate from 0.01 to 0.001 over 100 iterations.
 
 .. jupyter-execute::
 
     from squlearn.optimizers import Adam
-    from squlearn.qnn import get_lr_decay
+    from squlearn.qnn.util import get_lr_decay
     adam = Adam({'lr':get_lr_decay(0.01, 0.001, 100)})
 
 
@@ -263,11 +263,12 @@ The high-level implementations of QNNs, :class:`QNNRegressor` and :class:`QNNCla
 can be initialized with a shot controller that takes care to automatically adjust the number of
 shots. The following example will generate a :class:`QNNRegressor`
 with a RSTD threshold of 0.1 and a minimum and maximum number of shots of 100 and 10000.
-It utilizes the :class:`ShotsFromRSTD <squlearn.qnn.ShotsFromRSTD>` shot controller.
+It utilizes the :class:`ShotsFromRSTD <squlearn.qnn.util.ShotsFromRSTD>` shot controller.
 
 .. code-block:: python
 
-    from squlearn.qnn import QNNRegressor, ShotsFromRSTD
+    from squlearn.qnn import QNNRegressor
+    from squlearn.qnn.util import ShotsFromRSTD
     reg = QNNRegressor(
         ...
         shot_controller = ShotsFromRSTD(rstd_bound=0.1, min_shots=100, max_shots=10000),
@@ -292,13 +293,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 +360,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>`.
@@ -407,12 +408,13 @@ stages (see Ref. [1]). This can be achieved by passing a :class:`List` or a :cla
 to the keyword argument ``variance`` of the :class:`QNNRegressor` (or :class:`QNNClassifier`).
 The following example will generate a :class:`QNNRegressor` with a variance
 regularization factor that is adjusted dynamically during the optimization by utilizing the
-function :meth:`get_variance_fac`. The set-up features a final regularization factor of 0.005,
+function :meth:`util.get_variance_fac`. The set-up features a final regularization factor of 0.005,
 a decay factor of 0.08 and a plateau at :math:`\alpha=1` of 20 iterations at the beginning.
 
 .. code-block:: python
 
-    from squlearn.qnn import QNNRegressor,get_variance_fac
+    from squlearn.qnn import QNNRegressor
+    from squlearn.qnn.util import get_variance_fac
     reg = QNNRegressor(
         ...
         variance = get_variance_fac(0.005,0.08,20),