Merge pull request #328 from sQUlearn/develop

Release 0.8.2

Author: MoritzWillmann

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
 
 

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)
 

docs/user_guide/kernel_methods.rst

@@ -66,7 +66,7 @@ given by measurements.
     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
 ----------------------------------------------
@@ -132,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`
 #########################################################

docs/user_guide/quantum_neural_networks.rst

@@ -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),
@@ -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),

examples/encoding_circuits/various_encoding_circuit.ipynb

@@ -214,7 +214,7 @@
    "source": [
     "\"\"\"\n",
     "This example shows how to wrap a Qiskit QuantumCircuit object into\n",
-    "a sQUlearn EncodingCircuitBase object. The TwoLocal circuit below can be \n",
+    "a sQUlearn EncodingCircuitBase object. The TwoLocal circuit below can be\n",
     "replaced by any other QuantumCircuit\n",
     "\"\"\"\n",
     "\n",

examples/executor/example_executor_qiskit.ipynb

@@ -61,13 +61,13 @@
     "# from a backend obtained from the Qiskit IBM runtime service (here, the account has to be set-up previously):\n",
     "service = QiskitRuntimeService(channel=\"ibm_quantum\")\n",
     "# Alternative: service = QiskitRuntimeService(channel=\"ibm_quantum\",token=\"YOUR_TOKEN_HERE\")\n",
-    "executor = Executor(service.get_backend(\"ibm_kyoto\"))\n",
+    "executor = Executor(service.backend(\"ibm_kyoto\"))\n",
     "# from a session set-up with the Qiskit IBM runtime service:\n",
-    "session = Session(service, backend=service.get_backend(\"ibm_kyoto\"), max_time=28800)\n",
+    "session = Session(service, backend=service.backend(\"ibm_kyoto\"), max_time=28800)\n",
     "executor = Executor(session)\n",
     "\n",
     "# from the Qiskit IBM runtime Estimator primitive:\n",
-    "session = Session(service, backend=service.get_backend(\"ibm_kyoto\"), max_time=28800)\n",
+    "session = Session(service, backend=service.backend(\"ibm_kyoto\"), max_time=28800)\n",
     "estimator = RuntimeEstimator(session=session)\n",
     "executor = Executor(estimator)"
    ]

examples/kernel/example_projected_kernel.ipynb

@@ -581,16 +581,16 @@
        "}\n",
        "</style><div id=\"sk-container-id-1\" class=\"sk-top-container\"><div class=\"sk-text-repr-fallback\"><pre>QSVC(C=1.0, break_ties=False, cache_size=200, class_weight=None,\n",
        "     decision_function_shape=&#x27;ovr&#x27;, max_iter=-1, probability=False,\n",
-       "     quantum_kernel=&lt;squlearn.kernel.matrix.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40&gt;,\n",
+       "     quantum_kernel=&lt;squlearn.kernel.lowlevel_kernel.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40&gt;,\n",
        "     random_state=None, shrinking=True, tol=0.001, verbose=False)</pre><b>In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook. <br />On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.</b></div><div class=\"sk-container\" hidden><div class=\"sk-item\"><div class=\"sk-estimator fitted sk-toggleable\"><input class=\"sk-toggleable__control sk-hidden--visually\" id=\"sk-estimator-id-1\" type=\"checkbox\" checked><label for=\"sk-estimator-id-1\" class=\"sk-toggleable__label fitted sk-toggleable__label-arrow fitted\">&nbsp;QSVC<span class=\"sk-estimator-doc-link fitted\">i<span>Fitted</span></span></label><div class=\"sk-toggleable__content fitted\"><pre>QSVC(C=1.0, break_ties=False, cache_size=200, class_weight=None,\n",
        "     decision_function_shape=&#x27;ovr&#x27;, max_iter=-1, probability=False,\n",
-       "     quantum_kernel=&lt;squlearn.kernel.matrix.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40&gt;,\n",
+       "     quantum_kernel=&lt;squlearn.kernel.lowlevel_kernel.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40&gt;,\n",
        "     random_state=None, shrinking=True, tol=0.001, verbose=False)</pre></div> </div></div></div></div>"
       ],
       "text/plain": [
        "QSVC(C=1.0, break_ties=False, cache_size=200, class_weight=None,\n",
        "     decision_function_shape='ovr', max_iter=-1, probability=False,\n",
-       "     quantum_kernel=<squlearn.kernel.matrix.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40>,\n",
+       "     quantum_kernel=<squlearn.kernel.lowlevel_kernel.projected_quantum_kernel.ProjectedQuantumKernel object at 0x0000017603089B40>,\n",
        "     random_state=None, shrinking=True, tol=0.001, verbose=False)"
       ]
      },

examples/kernel/example_regularization_mitigation.ipynb

@@ -160,7 +160,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "WARNING: Advanced option. Do not use it within an squlearn.kernel.ml workflow\n"
+      "WARNING: Advanced option. Do not use it within an squlearn.kernel workflow\n"
      ]
     },
     {

examples/kernel/qgpc_workflow.ipynb

@@ -463,16 +463,16 @@
        "}\n",
        "</style><div id=\"sk-container-id-1\" class=\"sk-top-container\"><div class=\"sk-text-repr-fallback\"><pre>QGPC(copy_X_train=True, max_iter_predict=100, multi_class=&#x27;one_vs_rest&#x27;,\n",
        "     n_jobs=None, n_restarts_optimizer=0, optimizer=&#x27;fmin_l_bfgs_b&#x27;,\n",
-       "     quantum_kernel=&lt;squlearn.kernel.matrix.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40&gt;,\n",
+       "     quantum_kernel=&lt;squlearn.kernel.lowlevel_kernel.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40&gt;,\n",
        "     random_state=None)</pre><b>In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook. <br />On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.</b></div><div class=\"sk-container\" hidden><div class=\"sk-item\"><div class=\"sk-estimator fitted sk-toggleable\"><input class=\"sk-toggleable__control sk-hidden--visually\" id=\"sk-estimator-id-1\" type=\"checkbox\" checked><label for=\"sk-estimator-id-1\" class=\"sk-toggleable__label fitted sk-toggleable__label-arrow fitted\">&nbsp;QGPC<span class=\"sk-estimator-doc-link fitted\">i<span>Fitted</span></span></label><div class=\"sk-toggleable__content fitted\"><pre>QGPC(copy_X_train=True, max_iter_predict=100, multi_class=&#x27;one_vs_rest&#x27;,\n",
        "     n_jobs=None, n_restarts_optimizer=0, optimizer=&#x27;fmin_l_bfgs_b&#x27;,\n",
-       "     quantum_kernel=&lt;squlearn.kernel.matrix.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40&gt;,\n",
+       "     quantum_kernel=&lt;squlearn.kernel.lowlevel_kernel.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40&gt;,\n",
        "     random_state=None)</pre></div> </div></div></div></div>"
       ],
       "text/plain": [
        "QGPC(copy_X_train=True, max_iter_predict=100, multi_class='one_vs_rest',\n",
        "     n_jobs=None, n_restarts_optimizer=0, optimizer='fmin_l_bfgs_b',\n",
-       "     quantum_kernel=<squlearn.kernel.matrix.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40>,\n",
+       "     quantum_kernel=<squlearn.kernel.lowlevel_kernel.fidelity_kernel.FidelityKernel object at 0x000001B61DF09B40>,\n",
        "     random_state=None)"
       ]
      },

examples/qnn/example_adam.ipynb

@@ -23,7 +23,8 @@
     "from squlearn import Executor\n",
     "from squlearn.encoding_circuit import ChebyshevPQC\n",
     "from squlearn.observables import SummedPaulis\n",
-    "from squlearn.qnn import QNNRegressor, SquaredLoss, get_variance_fac, ShotsFromRSTD\n",
+    "from squlearn.qnn import QNNRegressor, SquaredLoss\n",
+    "from squlearn.qnn.util import get_variance_fac, ShotsFromRSTD\n",
     "from squlearn.optimizers import Adam"
    ]
   },
@@ -276,11 +277,8 @@
   }
  ],
  "metadata": {
-  "interpreter": {
-   "hash": "26de051ba29f2982a8de78e945f0abaf191376122a1563185a90213a26c5da77"
-  },
   "kernelspec": {
-   "display_name": "Python 3.10.2 64-bit",
+   "display_name": "venv",
    "language": "python",
    "name": "python3"
   },
@@ -294,7 +292,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.10"
+   "version": "3.12.7"
   },
   "orig_nbformat": 4
  },