Merge branch 'main' into VFF_PR

Author: edoaltamura

.pylintdict

@@ -112,6 +112,7 @@ deterministically
 diag
 dicts
 diederik
+dill
 dimensionality
 dir
 discretization
@@ -122,6 +123,7 @@ disp
 distro
 dobsicek
 docstring
+docstrings
 doi
 dok
 dp
@@ -519,6 +521,7 @@ seealso
 semidefinite
 sep
 serializable
+serializablemodelmixin
 shalev
 shanno
 shende
@@ -657,3 +660,4 @@ zz
 φ_i
 φ_ij
 Δ
+π

README.md

@@ -3,11 +3,13 @@
 [![License](https://img.shields.io/github/license/qiskit-community/qiskit-machine-learning.svg?)](https://opensource.org/licenses/Apache-2.0) <!--- long-description-skip-begin -->
 [![Current Release](https://img.shields.io/github/release/qiskit-community/qiskit-machine-learning.svg?logo=Qiskit)](https://github.com/qiskit-community/qiskit-machine-learning/releases)
 [![Build Status](https://github.com/qiskit-community/qiskit-machine-learning/actions/workflows/main.yml/badge.svg)](https://github.com/qiskit-community/qiskit-machine-learning/actions?query=workflow%3A"Machine%20Learning%20Unit%20Tests"+branch%3Amain+event%3Apush)
-[![Monthly downloads](https://img.shields.io/pypi/dm/qiskit-machine-learning.svg)](https://pypi.org/project/qiskit-machine-learning/)
 [![Coverage Status](https://coveralls.io/repos/github/qiskit-community/qiskit-machine-learning/badge.svg?branch=main)](https://coveralls.io/github/qiskit-community/qiskit-machine-learning?branch=main)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qiskit-machine-learning)
+[![Monthly downloads](https://img.shields.io/pypi/dm/qiskit-machine-learning.svg)](https://pypi.org/project/qiskit-machine-learning/)
 [![Total downloads](https://static.pepy.tech/badge/qiskit-machine-learning)](https://pepy.tech/project/qiskit-machine-learning)
 [![Slack Organisation](https://img.shields.io/badge/slack-chat-blueviolet.svg?label=Qiskit%20Slack&logo=slack)](https://slack.qiskit.org)
+[![arXiv](https://img.shields.io/badge/arXiv-2505.17756-b31b1b.svg)](https://arxiv.org/abs/2505.17756)
+
 <!--- long-description-skip-end -->
 
 ## What is Qiskit Machine Learning?
@@ -21,8 +23,9 @@ on the Qiskit software development kit. As of version `0.7`, Qiskit Machine Lear
 by IBM and the [Hartree Center](https://www.hartree.stfc.ac.uk/), part of the UK Science and 
 Technologies Facilities Council (STFC).
 
-A description of the library structure, features, and domain-specific applications, can be found 
-in a dedicated [ArXiv paper](https://arxiv.org/abs/2505.17756).
+> [!NOTE]
+> A description of the library structure, features, and domain-specific applications, can be found 
+> in a dedicated [ArXiv paper](https://arxiv.org/abs/2505.17756).
 
 The Qiskit Machine Learning framework aims to be:
 
@@ -117,7 +120,7 @@ Learning module. Let's try an experiment using VQC (Variational Quantum Classifi
 train and test samples from a data set to see how accurately the test set can be classified.
 
 ```python
-from qiskit.circuit.library import TwoLocal, ZZFeatureMap
+from qiskit.circuit.library import n_local, zz_feature_map
 from qiskit_machine_learning.optimizers import COBYLA
 from qiskit_machine_learning.utils import algorithm_globals
 
@@ -138,8 +141,8 @@ training_features, training_labels, test_features, test_labels = ad_hoc_data(
     training_size=training_size, test_size=test_size, n=feature_dim, gap=0.3
 )
 
-feature_map = ZZFeatureMap(feature_dimension=feature_dim, reps=2, entanglement="linear")
-ansatz = TwoLocal(feature_map.num_qubits, ["ry", "rz"], "cz", reps=3)
+feature_map = zz_feature_map(feature_dimension=feature_dim, reps=2, entanglement="linear")
+ansatz = n_local(feature_map.num_qubits, ["ry", "rz"], "cz", reps=3)
 vqc = VQC(
     feature_map=feature_map,
     ansatz=ansatz,

docs/tutorials/09_saving_and_loading_models.ipynb

@@ -535,7 +535,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "original_classifier.save(\"vqc_classifier.model\")"
+    "original_classifier.to_dill(\"vqc_classifier.model\")"
    ]
   },
   {
@@ -555,7 +555,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "loaded_classifier = VQC.load(\"vqc_classifier.model\")"
+    "loaded_classifier = VQC.from_dill(\"vqc_classifier.model\")"
    ]
   },
   {

qiskit_machine_learning/algorithms/classifiers/qsvc.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2021, 2024.
+# (C) Copyright IBM 2021, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -34,13 +34,24 @@ class QSVC(SVC, SerializableModelMixin):
     Read more in the `scikit-learn user guide
     <https://scikit-learn.org/stable/modules/svm.html#svm-classification>`_.
 
-    **Example**
+    Examples:
+        .. code-block::
 
-    .. code-block::
+            from qiskit_machine_learning.kernels import FidelityQuantumKernel
+            from qiskit_machine_learning.algorithms import QSVC
+
+            kernel = FidelityQuantumKernel()
+            qsvc = QSVC(quantum_kernel=kernel)
+            qsvc.fit(X_train, y_train)
+            y_pred = qsvc.predict(X_test)
+
+            # Save the trained model
+            qsvc.to_dill('qsvc_model.dill')
+
+            # Load the model for later use
+            loaded_qsvc = QSVC.from_dill('qsvc_model.dill')
+            score = loaded_qsvc.score(X_test, y_test)
 
-        qsvc = QSVC(quantum_kernel=qkernel)
-        qsvc.fit(sample_train,label_train)
-        qsvc.predict(sample_test)
     """
 
     def __init__(self, *, quantum_kernel: Optional[BaseKernel] = None, **kwargs):

qiskit_machine_learning/algorithms/classifiers/vqc.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2021, 2024.
+# (C) Copyright IBM 2021, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -69,14 +69,14 @@ def __init__(
                 If ``None`` is given, the number of qubits is derived from the
                 feature map or ansatz. If neither of those is given, raises an exception.
                 The number of qubits in the feature map and ansatz are adjusted to this
-                number if required.
+                number if required and possible (such adjustment is deprecated).
             feature_map: The (parametrized) circuit to be used as a feature map for the underlying
-                QNN. If ``None`` is given, the :class:`~qiskit.circuit.library.ZZFeatureMap`
+                QNN. If ``None`` is given, the :meth:`~qiskit.circuit.library.zz_feature_map`
                 is used if the number of qubits is larger than 1. For a single qubit
-                classification problem the :class:`~qiskit.circuit.library.ZFeatureMap`
+                classification problem the :meth:`~qiskit.circuit.library.z_feature_map`
                 is used by default.
             ansatz: The (parametrized) circuit to be used as an ansatz for the underlying QNN.
-                If ``None`` is given then the :class:`~qiskit.circuit.library.RealAmplitudes`
+                If ``None`` is given then the :meth:`~qiskit.circuit.library.real_amplitudes`
                 circuit is used.
             loss: A target loss function to be used in training. Default value is ``cross_entropy``.
             optimizer: An instance of an optimizer or a callable to be used in training.
@@ -108,7 +108,7 @@ def __init__(
         """
 
         num_qubits, feature_map, ansatz = derive_num_qubits_feature_map_ansatz(
-            num_qubits, feature_map, ansatz
+            num_qubits, feature_map, ansatz, use_methods=True
         )
 
         if output_shape is None:

qiskit_machine_learning/algorithms/inference/qbayesian.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2023, 2024.
+# (C) Copyright IBM 2023, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -19,7 +19,7 @@
 from qiskit import QuantumCircuit, ClassicalRegister
 from qiskit.quantum_info import Statevector
 from qiskit.circuit import Qubit
-from qiskit.circuit.library import GroverOperator
+from qiskit.circuit.library import grover_operator
 from qiskit.primitives import BaseSampler, Sampler, BaseSamplerV2, BaseSamplerV1
 from qiskit.transpiler.passmanager import BasePassManager
 from qiskit.result import QuasiDistribution
@@ -129,7 +129,7 @@ def __init__(
         # True if rejection sampling converged after limit
         self._converged = bool()
 
-    def _get_grover_op(self, evidence: Dict[str, int]) -> GroverOperator:
+    def _get_grover_op(self, evidence: Dict[str, int]) -> QuantumCircuit:
         """
         Constructs a Grover operator based on the provided evidence. The evidence is used to
         determine the "good states" that the Grover operator will amplify.
@@ -161,7 +161,7 @@ def _get_grover_op(self, evidence: Dict[str, int]) -> GroverOperator:
         oracle = Statevector(
             [int(format(i, f"0{num_qubits}b") in good_states) for i in range(2**num_qubits)]
         )
-        return GroverOperator(oracle, state_preparation=self._circ)
+        return grover_operator(oracle, state_preparation=self._circ)
 
     def _run_circuit(self, circuit: QuantumCircuit) -> Dict[str, float]:
         """Run the quantum circuit with the sampler."""
@@ -199,7 +199,7 @@ def _run_circuit(self, circuit: QuantumCircuit) -> Dict[str, float]:
         return counts
 
     def __power_grover(
-        self, grover_op: GroverOperator, evidence: Dict[str, int], k: int
+        self, grover_op: QuantumCircuit, evidence: Dict[str, int], k: int
     ) -> Tuple[QuantumCircuit, Set[Tuple[Qubit, int]]]:
         """
         Applies the Grover operator to the quantum circuit 2^k times, measures the evidence qubits,

qiskit_machine_learning/algorithms/regressors/vqr.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2021, 2024.
+# (C) Copyright IBM 2021, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -52,13 +52,13 @@ def __init__(
                 If ``None`` then the number of qubits is derived from the
                 feature map or ansatz, but if neither of these are given an error is raised.
                 The number of qubits in the feature map and ansatz are adjusted to this
-                number if required.
+                number if required and possible (such adjustment is deprecated).
             feature_map: The (parametrized) circuit to be used as a feature map for the underlying
-                QNN. If ``None`` the :class:`~qiskit.circuit.library.ZZFeatureMap`
+                QNN. If ``None`` the :meth:`~qiskit.circuit.library.zz_feature_map`
                 is used if the number of qubits is larger than 1. For a single qubit regression
-                problem the :class:`~qiskit.circuit.library.ZFeatureMap` is used by default.
+                problem the :meth:`~qiskit.circuit.library.z_feature_map` is used by default.
             ansatz: The (parametrized) circuit to be used as an ansatz for the underlying
-                QNN. If ``None`` then the :class:`~qiskit.circuit.library.RealAmplitudes`
+                QNN. If ``None`` then the :meth:`~qiskit.circuit.library.real_amplitudes`
                 circuit is used.
             observable: The observable to be measured in the underlying QNN. If ``None``,
                 use the default :math:`Z^{\otimes num\_qubits}` observable.
@@ -94,7 +94,7 @@ def __init__(
         self._estimator = estimator
 
         num_qubits, feature_map, ansatz = derive_num_qubits_feature_map_ansatz(
-            num_qubits, feature_map, ansatz
+            num_qubits, feature_map, ansatz, use_methods=True
         )
 
         # construct circuit

qiskit_machine_learning/algorithms/serializable_model.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2021, 2023.
+# (C) Copyright IBM 2021, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -15,37 +15,70 @@
 
 import dill
 
+from ..utils.deprecation import issue_deprecation_msg
+
 
 class SerializableModelMixin:
     """
-    Provides convenient methods for saving and loading models.
+    Provides convenient methods for saving and loading models via dill serialization.
+
+    .. warning::
+        The legacy :meth:`save` and :meth:`load` methods are deprecated in v0.9.0
+        and will be removed in a future release. Please use :meth:`to_dill`
+        and :meth:`from_dill` respectively.
+
     """
 
-    def save(self, file_name: str) -> None:
+    def to_dill(self, file_name: str) -> None:
         """
         Saves this model to the specified file. Internally, the model is serialized via ``dill``.
         All parameters are saved, including a primitive instance that is referenced by internal
         objects. That means if a model is loaded from a file and is used, for instance, for
         inference, the same primitive will be used even if a cloud primitive was used.
 
+        .. warning::
+            Replaces the deprecated :meth:`save` method.
+
         Args:
-            file_name: a file name or path where to save the model.
+            file_name: Path where the serialized model will be written.
+
+        Example:
+            .. code-block::
+
+                model.to_dill('model_state.dill')
         """
         with open(file_name, "wb") as handler:
             dill.dump(self, handler)
 
+    def save(self, *args) -> None:
+        """Backwards compatibility with :meth:`to_dill`, deprecated in v0.9.0."""
+        issue_deprecation_msg(
+            msg="SerializableModelMixin.save() is deprecated.",
+            version="0.9.0",
+            remedy="Use the to_dill() method instead.",
+            period="4 months",
+        )
+        self.to_dill(*args)
+
     @classmethod
-    def load(cls, file_name: str) -> Any:
+    def from_dill(cls, file_name: str) -> Any:
         """
-        Loads a model from the file. If the loaded model is not an instance of the class whose
+        Loads a model from a file. If the loaded model is not an instance of the class whose
         method was called, then a warning is raised. Nevertheless, the loaded model may be a valid
         model.
 
+        Replaces the deprecated :meth:`load` method.
+
         Args:
-            file_name: a file name or path to load a model from.
+            file_name: Path to the dill file containing the serialized model.
 
         Returns:
-            A loaded model.
+            An instance of the model loaded from disk.
+
+        Example:
+            .. code-block::
+
+                loaded = MyModel.from_dill('model_state.dill')
 
         Raises:
             TypeError: if a loaded model is not an instance of the expected class.
@@ -55,3 +88,14 @@ def load(cls, file_name: str) -> Any:
         if not isinstance(model, cls):
             raise TypeError(f"Loaded model is of class {type(model)}. Expected class: {cls}.")
         return model
+
+    @classmethod
+    def load(cls, *args) -> Any:
+        """Backwards compatibility with :meth:`from_dill`, deprecated in v0.9.0."""
+        issue_deprecation_msg(
+            msg="SerializableModelMixin.load() is deprecated.",
+            version="0.9.0",
+            remedy="Use the from_dill() classmethod instead.",
+            period="4 months",
+        )
+        return cls.from_dill(*args)

qiskit_machine_learning/circuit/library/__init__.py

@@ -1,6 +1,6 @@
 # This code is part of a Qiskit project.
 #
-# (C) Copyright IBM 2020, 2024.
+# (C) Copyright IBM 2020, 2025.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -28,6 +28,7 @@
    :template: autosummary/class_no_inherited_members.rst
 
    RawFeatureVector
+   raw_feature_vector
 
 Helper circuits
 ---------------
@@ -38,12 +39,10 @@
    :template: autosummary/class_no_inherited_members.rst
 
    QNNCircuit
+   qnn_circuit
 """
 
-from .raw_feature_vector import RawFeatureVector
-from .qnn_circuit import QNNCircuit
+from .raw_feature_vector import RawFeatureVector, raw_feature_vector
+from .qnn_circuit import QNNCircuit, qnn_circuit
 
-__all__ = [
-    "RawFeatureVector",
-    "QNNCircuit",
-]
+__all__ = ["RawFeatureVector", "raw_feature_vector", "QNNCircuit", "qnn_circuit"]