Qiskit-machine-learning

Changelog
New Features
- Added support for using Qiskit Machine Learning with Python 3.12.

Bug Fixes
- Added a max_circuits_per_job parameter to the [FidelityQuantumKernel](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.FidelityQuantumKernel.html#qiskit_machine_learning.kernels.FidelityQuantumKernel) used in the case that if more circuits are submitted than the job limit for the backend, the circuits are split up and run through separate jobs.

- Removed [QuantumKernelTrainer](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer) dependency on copy.deepcopy that was throwing an error with real backends. Now, it modifies the [TrainableKernel](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.TrainableKernel.html#qiskit_machine_learning.kernels.TrainableKernel) in place. If you would like to use the initial kernel, please call [assign_training_parameters()](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.TrainableKernel.html#qiskit_machine_learning.kernels.TrainableKernel.assign_training_parameters) of the [TrainableKernel](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.TrainableKernel.html#qiskit_machine_learning.kernels.TrainableKernel) using the [initial_point](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.initial_point) attribute of [QuantumKernelTrainer](https://qiskit-community.github.io/qiskit-machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer).

- Fixes an issue for the Quantum Neural Networks where the binding order of the inputs and weights might end up being incorrect. Though the params for the inputs and weights are specified to the QNN, the code previously bound the inputs and weights in the order given by the circuit.parameters. This would end up being the right order for the Qiskit circuit library feature maps and ansatzes most often used, as the default parameter names led to the order being as expected. However for custom names etc. this was not always the case and then led to unexpected behavior. The sequences for the input and weights parameters, as supplied, are now always used as the binding order, for the inputs and weights respectively, such that the order of the parameters in the overall circuit no longer matters.

Changelog

This bug fix release fixed the link to the Qiskit medium blog post where it was announced that application modules had been moved to the qiskit-community organization.

Prelude

Qiskit Machine Learning has been migrated to the [qiskit-community Github organization](https://github.com/qiskit-community) to further emphasize that it is a community-driven project. To reflect this change, and because we are onboarding additional code-owners and maintainers, with this version (0.7) we have decided to remove all deprecated code, regardless of the time of its deprecation. This ensures that the new members of the development team do not have a large bulk of legacy code to maintain. This can mean one of two things for you as the end-user:

- Nothing, if you already migrated your code and no longer rely on any deprecated features.
- Otherwise, you should make sure that your workflow doesn’t rely on deprecated classes. If you cannot do that, or want to continue
using some of the features that were removed, you should pin your version of Qiskit Machine Learning to 0.6.

For more context on the changes around Qiskit Machine Learning and the other application projects as well as the Algorithms library in Qiskit, be sure to read this [blog post](https://ibm.biz/BdSyNm).

New Features

- The [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) class can be passed as circuit to the [SamplerQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN) and [EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN). This simplifies the interfaces to build a [Sampler](https://qiskit.org/documentation/stubs/qiskit.primitives.Sampler.html#qiskit.primitives.Sampler) or [Estimator](https://qiskit.org/documentation/stubs/qiskit.primitives.Estimator.html#qiskit.primitives.Estimator) based neural network implementation from a feature map and an ansatz circuit.
Using the [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) comes with the benefit that the feature map and ansatz do not have to be composed explicitly. If a [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) is passed to the [SamplerQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN) or [EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN) the input and weight parameters do not have to be provided, because these two properties are taken from the [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit).
An example of using [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) with the [SamplerQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN) class is as follows:

python
from qiskit_machine_learning.circuit.library import QNNCircuit
from qiskit_machine_learning.neural_networks import SamplerQNN

def parity(x):
return f"{bin(x)}".count("1") % 2

Create a parameterized 2 qubit circuit composed of the default ZZFeatureMap feature map
and RealAmplitudes ansatz.
qnn_qc = QNNCircuit(num_qubits = 2)

qnn = SamplerQNN(
circuit=qnn_qc,
interpret=parity,
output_shape=2
)

qnn.forward(input_data=[1, 2], weights=[1, 2, 3, 4, 5, 6, 7, 8])


The [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) is used with the [EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN) class in the same fashion:

python
from qiskit_machine_learning.circuit.library import QNNCircuit
from qiskit_machine_learning.neural_networks import EstimatorQNN

Create a parameterized 2 qubit circuit composed of the default ZZFeatureMap feature map
and RealAmplitudes ansatz.
qnn_qc = QNNCircuit(num_qubits = 2)

qnn = EstimatorQNN(
circuit=qnn_qc
)

qnn.forward(input_data=[1, 2], weights=[1, 2, 3, 4, 5, 6, 7, 8])


- Added a new [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) class that composes a Quantum Circuit from a feature map and an ansatz.
At least one parameter, i.e. number of qubits, feature map, ansatz, has to be provided.
If only the number of qubits is provided the resulting quantum circuit is a composition of the [ZZFeatureMap](https://qiskit.org/documentation/stubs/qiskit.circuit.library.ZZFeatureMap.html#qiskit.circuit.library.ZZFeatureMap) and the [RealAmplitudes](https://qiskit.org/documentation/stubs/qiskit.circuit.library.RealAmplitudes.html#qiskit.circuit.library.RealAmplitudes) ansatz. If the number of qubits is 1 the [ZFeatureMap](https://qiskit.org/documentation/stubs/qiskit.circuit.library.ZFeatureMap.html#qiskit.circuit.library.ZFeatureMap) is used per default. If only a feature map is provided, the [RealAmplitudes](https://qiskit.org/documentation/stubs/qiskit.circuit.library.RealAmplitudes.html#qiskit.circuit.library.RealAmplitudes) ansatz with the corresponding number of qubits is used. If only an ansatz is provided the [ZZFeatureMap](https://qiskit.org/documentation/stubs/qiskit.circuit.library.ZZFeatureMap.html#qiskit.circuit.library.ZZFeatureMap) with the corresponding number of qubits is used.
In case number of qubits is provided along with either a feature map, an ansatz or both, a potential mismatch between the three inputs with respect to the number of qubits is resolved by constructing the [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) with the given number of qubits. If one of the [QNNCircuit](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.QNNCircuit.html#qiskit_machine_learning.circuit.library.QNNCircuit) properties is set after the class construction, the circuit is is adjusted to incorporate the changes. This is, a new valid configuration that considers the latest property update will be derived. This ensures that the classes properties are consistent at all times.

An example of using this class is as follows:

python
from qiskit_machine_learning.circuit.library import QNNCircuit
qnn_qc = QNNCircuit(2)
print(qnn_qc)
prints:
┌──────────────────────────┐»
q_0: ┤0 ├»
│ ZZFeatureMap(x[0],x[1]) │»
q_1: ┤1 ├»
└──────────────────────────┘»
« ┌──────────────────────────────────────────────────────────┐
«q_0: ┤0 ├
« │ RealAmplitudes(θ[0],θ[1],θ[2],θ[3],θ[4],θ[5],θ[6],θ[7]) │
«q_1: ┤1 ├
« └──────────────────────────────────────────────────────────┘

print(qnn_qc.num_qubits)
prints: 2

print(qnn_qc.input_parameters)
prints: ParameterView([ParameterVectorElement(x[0]), ParameterVectorElement(x[1])])

print(qnn_qc.weight_parameters)
prints: ParameterView([ParameterVectorElement(θ[0]), ParameterVectorElement(θ[1]),
ParameterVectorElement(θ[2]), ParameterVectorElement(θ[3]),
ParameterVectorElement(θ[4]), ParameterVectorElement(θ[5]),
ParameterVectorElement(θ[6]), ParameterVectorElement(θ[7])])


- A new [TrainableFidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel.html#qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel) class has been added that provides a trainable version of [FidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityStatevectorKernel.html#qiskit_machine_learning.kernels.FidelityStatevectorKernel). This relationship mirrors that between the existing FidelityQuantumKernel. Thus, [TrainableFidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel.html#qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel) inherits from both [FidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityStatevectorKernel.html#qiskit_machine_learning.kernels.FidelityStatevectorKernel) and [TrainableKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableKernel.html#qiskit_machine_learning.kernels.TrainableKernel).
This class is used with [QuantumKernelTrainer](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer) in an identical way to [TrainableFidelityQuantumKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel.html#qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel), except for the arguments specific to [TrainableFidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel.html#qiskit_machine_learning.kernels.TrainableFidelityStatevectorKernel).

For an example, see the snippet below:

python
from qiskit.quantum_info import Statevector
from qiskit_machine_learning.kernels import TrainableFidelityStatevectorKernel
from qiskit_machine_learning.kernels.algorithms import QuantumKernelTrainer

Instantiate trainable fidelity statevector kernel.
quantum_kernel = TrainableFidelityStatevectorKernel(
feature_map=<your_feature_map>,
statevector_type=Statevector,
training_parameters=<your_training_parameters>,
cache_size=None,
auto_clear_cache=True,
shots=None,
enforce_psd=True,
)

Instantiate a quantum kernel trainer (QKT).
qkt = QuantumKernelTrainer(quantum_kernel=quantum_kernel)

Train the kernel using QKT directly.
qkt_results = qkt.fit(<your_X_train>, <your_y_train>)
optimized_kernel = qkt_results.quantum_kernel


- The module is migrated to [Qiskit Algorithms](https://qiskit.org/ecosystem/algorithms) from the qiskit.algorithms package that is deprecated now.

Upgrade Notes

- Support for running with Python 3.7 has been removed. To run Qiskit Machine Learning you need a minimum Python version of 3.8.

- Removed support of the deprecated parameter quantum_instance in the constructor of [VQC](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.algorithms.VQC.html#qiskit_machine_learning.algorithms.VQC) and in [VQR](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.algorithms.VQR.html#qiskit_machine_learning.algorithms.VQR). Please use sampler and estimator respectively. Refer to the [migration guide](https://qiskit.org/ecosystem/machine-learning/migration/01_migration_guide_0.5.html) for more information.

- Since [qiskit.opflow](https://qiskit.org/documentation/apidoc/opflow.html#module-qiskit.opflow) and [QuantumInstance](https://qiskit.org/documentation/stubs/qiskit.utils.QuantumInstance.html#qiskit.utils.QuantumInstance) are deprecated in Qiskit, Qiskit Machine Learning classes based on the deprecated Qiskit classes have been removed:

* Class qiskit_machine_learning.neural_networks.SamplingNeuralNetwork is removed and has no direct replacement as this is a base class.
* Class qiskit_machine_learning.neural_networks.CircuitQNN is removed and is superseded by [qiskit_machine_learning.neural_networks.SamplerQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN).
* Class qiskit_machine_learning.neural_networks.OpflowQNN is removed and is superseded by [qiskit_machine_learning.neural_networks.EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN).
* Class qiskit_machine_learning.neural_networks.TwoLayerQNN is removed and has no direct replacement. Please make use of [qiskit_machine_learning.neural_networks.EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN) instead.
* Class qiskit_machine_learning.kernels.QuantumKernel is removed and is superseded by [qiskit_machine_learning.kernels.FidelityQuantumKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityQuantumKernel.html#qiskit_machine_learning.kernels.FidelityQuantumKernel), [qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel.html#qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel), and [qiskit_machine_learning.kernels.FidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityStatevectorKernel.html#qiskit_machine_learning.kernels.FidelityStatevectorKernel).

Please refer to the [migration guide](https://qiskit.org/ecosystem/machine-learning/migration/01_migration_guide_0.5.html) on how to replace the deprecated classes with new ones.

- The previously deprecated qgan and runtime packages have been removed. Please refer to:

* New [QGAN tutorial](https://qiskit.org/documentation/machine-learning/tutorials/04_torch_qgan.html) to train a generative quantum neural network.
* New primitive based quantum neural networks [EstimatorQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN), [SamplerQNN](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN), PyTorch connector [TorchConnector](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.connectors.TorchConnector.html#qiskit_machine_learning.connectors.TorchConnector), and [Qiskit Runtime Service](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/apidocs/runtime_service.html) to get functionality similar to what the removed runtime package provided.

Bug Fixes

- Compatibility fix to support Python 3.11.

- Fixes a bug in [FidelityStatevectorKernel](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityStatevectorKernel.html#qiskit_machine_learning.kernels.FidelityStatevectorKernel) where kernel entries could potentially have nonzero complex components due to truncation and rounding errors when enforcing a PSD matrix.

- Updated [RawFeatureVector](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.circuit.library.RawFeatureVector.html#qiskit_machine_learning.circuit.library.RawFeatureVector) to support [changes](https://github.com/Qiskit/qiskit-terra/pull/10183) in the parameter assignment introduced in Qiskit.

- Fixed incorrect type conversions in [TorchConnector](https://qiskit.org/ecosystem/machine-learning/stubs/qiskit_machine_learning.connectors.TorchConnector.html#qiskit_machine_learning.connectors.TorchConnector). The bug was causing the connector to convert the output to the same type as the input data. As a result, when an integer tensor was passed, the output would also be converted to an integer tensor, leading to rounding errors.

Changelog

Bug Fixes

- Compatibility fix to support Python 3.11.

- The function `qiskit_machine_learning.datasets.discretize_and_truncate()` is fixed on numpy version 1.24. This function is used by the QGAN implementation.

Changelog

New Features

- Allow callable as an optimizer in NeuralNetworkClassifier, VQC, NeuralNetworkRegressor, VQR, as well as in [QuantumKernelTrainer](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer).

Now, the optimizer can either be one of Qiskit’s optimizers, such as [SPSA](https://qiskit.org/documentation/stubs/qiskit.algorithms.optimizers.SPSA.html#qiskit.algorithms.optimizers.SPSA) or a callable with the following signature:

python
from qiskit.algorithms.optimizers import OptimizerResult

def my_optimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult:
Args:
fun (callable): the function to minimize
x0 (np.ndarray): the initial point for the optimization
jac (callable, optional): the gradient of the objective function
bounds (list, optional): a list of tuples specifying the parameter bounds
result = OptimizerResult()
result.x = optimal parameters
result.fun = optimal function value
return result

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The above signature also allows to directly pass any SciPy minimizer, for instance as

python
from functools import partial
from scipy.optimize import minimize
optimizer = partial(minimize, method="L-BFGS-B")


- Added a new `FidelityStatevectorKernel` class that is optimized to use only statevector-implemented feature maps. Therefore, computational complexity is reduced from $O(N^2)$ to $O(N)$.

Computed statevector arrays are also cached to further increase efficiency. This cache is cleared when the `evaluate` method is called, unless `auto_clear_cache` is `False`. The cache is unbounded by default, but its size can be set by the user, i.e., limited to the number of samples in the worst case.

By default the Terra reference `Statevector` is used, however, the type can be specified via the `statevector_type` argument.

Shot noise emulation can also be added. If `shots` is `None`, the exact fidelity is used. Otherwise, the mean is taken of samples drawn from a binomial distribution with probability equal to the exact fidelity.

With the addition of shot noise, the kernel matrix may no longer be positive semi-definite (PSD). With `enforce_psd` set to `True` this condition is enforced.

An example of using this class is as follows:

python
from sklearn.datasets import make_blobs
from sklearn.svm import SVC

from qiskit.circuit.library import ZZFeatureMap
from qiskit.quantum_info import Statevector

from qiskit_machine_learning.kernels import FidelityStatevectorKernel

generate a simple dataset
features, labels = make_blobs(
n_samples=20, centers=2, center_box=(-1, 1), cluster_std=0.1
)

feature_map = ZZFeatureMap(feature_dimension=2, reps=2)
statevector_type = Statevector

kernel = FidelityStatevectorKernel(
feature_map=feature_map,
statevector_type=Statevector,
cache_size=len(labels),
auto_clear_cache=True,
shots=1000,
enforce_psd=True,
)
svc = SVC(kernel=kernel.evaluate)
svc.fit(features, labels)


- The PyTorch connector `TorchConnector` now fully supports sparse output in both forward and backward passes. To enable sparse support, first of all, the underlying quantum neural network must be sparse. In this case, if the sparse property of the connector itself is not set, then the connector inherits sparsity from the networks. If the connector is set to be sparse, but the network is not, an exception will be raised. Also you may set the connector to be dense if the network is sparse.

This snippet illustrates how to create a sparse instance of the connector.

python
import torch
from qiskit import QuantumCircuit
from qiskit.circuit.library import ZFeatureMap, RealAmplitudes

from qiskit_machine_learning.connectors import TorchConnector
from qiskit_machine_learning.neural_networks import SamplerQNN

num_qubits = 2
fmap = ZFeatureMap(num_qubits, reps=1)
ansatz = RealAmplitudes(num_qubits, reps=1)
qc = QuantumCircuit(num_qubits)
qc.compose(fmap, inplace=True)
qc.compose(ansatz, inplace=True)

qnn = SamplerQNN(
circuit=qc,
input_params=fmap.parameters,
weight_params=ansatz.parameters,
sparse=True,
)

connector = TorchConnector(qnn)

output = connector(torch.tensor([[1., 2.]]))
print(output)

loss = torch.sparse.sum(output)
loss.backward()

grad = connector.weight.grad
print(grad)


&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;In hybrid setup, where a PyTorch-based neural network has classical and quantum layers, sparse operations should not be mixed with dense ones, otherwise exceptions may be thrown by PyTorch.

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Sparse support works on python 3.8+.

Upgrade Notes

- The previously deprecated `CrossEntropySigmoidLoss` loss function has been removed.
- The previously deprecated datasets have been removed: `breast_cancer`, `digits`, `gaussian`, `iris`, `wine`.
- Positional arguments in [`QSVC`](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QSVC.html#qiskit_machine_learning.algorithms.QSVC) and [`QSVR`](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QSVR.html#qiskit_machine_learning.algorithms.QSVR) were deprecated as of version 0.3. Support of the positional arguments was completely removed in this version, please replace them with corresponding keyword arguments.

Bug Fixes
- [`SamplerQNN`](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN) can now correctly handle quantum circuits without both input parameters and weights. If such a circuit is passed to the QNN then this circuit executed once in the forward pass and backward returns `None` for both gradients.

Changelog

New Features

- Added support for categorical and ordinal labels to [VQC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.VQC.html#qiskit_machine_learning.algorithms.VQC). Now labels can be passed in different formats, they can be plain ordinal labels, a one dimensional array that contains integer labels like 0, 1, 2, …, or an array with categorical string labels. One-hot encoded labels are still supported. Internally, labels are transformed to one hot encoding and the classifier is always trained on one hot labels.
- Introduced Estimator Quantum Neural Network ([EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN)) based on (runtime) primitives. This implementation leverages the estimator primitive (see [BaseEstimator](https://qiskit.org/documentation/stubs/qiskit.primitives.BaseEstimator.html#qiskit.primitives.BaseEstimator)) and the estimator gradients (see [BaseEstimatorGradient](https://qiskit.org/documentation/stubs/qiskit.algorithms.gradients.BaseEstimatorGradient.html#qiskit.algorithms.gradients.BaseEstimatorGradient)) to enable runtime access and more efficient computation of forward and backward passes.
The new [EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN) exposes a similar interface to the Opflow QNN, with a few differences. One is the quantum_instance parameter. This parameter does not have a direct replacement, and instead the estimator parameter must be used. The gradient parameter keeps the same name as in the Opflow QNN implementation, but it no longer accepts Opflow gradient classes as inputs; instead, this parameter expects an (optionally custom) primitive gradient.
The existing training algorithms such as [VQR](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.VQR.html#qiskit_machine_learning.algorithms.VQR), that were based on the Opflow QNN, are updated to accept both implementations. The implementation of [NeuralNetworkRegressor](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.NeuralNetworkRegressor.html#qiskit_machine_learning.algorithms.NeuralNetworkRegressor) has not changed.

- Introduced Quantum Kernels based on (runtime) primitives. This implementation leverages the fidelity primitive (see [BaseStateFidelity](https://qiskit.org/documentation/stubs/qiskit.algorithms.state_fidelities.BaseStateFidelity.html#qiskit.algorithms.state_fidelities.BaseStateFidelity)) and provides more flexibility to end users. The fidelity primitive calculates state fidelities/overlaps for pairs of quantum circuits and requires an instance of [Sampler](https://qiskit.org/documentation/stubs/qiskit.primitives.Sampler.html#qiskit.primitives.Sampler). Thus, users may plug in their own implementations of fidelity calculations.
The new kernels expose the same interface and the same parameters except the quantum_instance parameter. This parameter does not have a direct replacement and instead the fidelity parameter must be used.

A new hierarchy is introduced:

- A base and abstract class [BaseKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.BaseKernel.html#qiskit_machine_learning.kernels.BaseKernel) is introduced. All concrete implementation must inherit this class.

- A fidelity based quantum kernel [FidelityQuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityQuantumKernel.html#qiskit_machine_learning.kernels.FidelityQuantumKernel) is added. This is a direct replacement of [QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel). The difference is that the new class takes either a sampler or a fidelity instance to estimate overlaps and construct kernel matrix.

- A new abstract class [TrainableKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableKernel.html#qiskit_machine_learning.kernels.TrainableKernel) is introduced to generalize ability to train quantum kernels.

- A fidelity-based trainable quantum kernel [TrainableFidelityQuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel.html#qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel) is introduced. This is a replacement of the existing [QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel) if a trainable kernel is required. The trainer [QuantumKernelTrainer](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer.html#qiskit_machine_learning.kernels.algorithms.QuantumKernelTrainer) now accepts both quantum kernel implementations, the new one and the existing one.

The existing algorithms such as [QSVC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QSVC.html#qiskit_machine_learning.algorithms.QSVC), [QSVR](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QSVR.html#qiskit_machine_learning.algorithms.QSVR) and other kernel-based algorithms are updated to accept both implementations.

- Introduced Sampler Quantum Neural Network ([SamplerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN)) based on (runtime) primitives. This implementation leverages the sampler primitive (see [BaseSampler](https://qiskit.org/documentation/stubs/qiskit.primitives.BaseSampler.html#qiskit.primitives.BaseSampler)) and the sampler gradients (see [BaseSamplerGradient](https://qiskit.org/documentation/stubs/qiskit.algorithms.gradients.BaseSamplerGradient.html#qiskit.algorithms.gradients.BaseSamplerGradient)) to enable runtime access and more efficient computation of forward and backward passes more efficiently.
The new [SamplerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN) exposes a similar interface to the [CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN), with a few differences. One is the quantum_instance parameter. This parameter does not have a direct replacement, and instead the sampler parameter must be used. The gradient parameter keeps the same name as in the [CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN) implementation, but it no longer accepts Opflow gradient classes as inputs; instead, this parameter expects an (optionally custom) primitive gradient. The sampling option has been removed for the time being, as this information is not currently exposed by the Sampler, and might correspond to future lower-level primitives.

- The existing training algorithms such as [VQC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.VQC.html#qiskit_machine_learning.algorithms.VQC), that were based on the [CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN), are updated to accept both implementations. The implementation of [NeuralNetworkClassifier](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.NeuralNetworkClassifier.html#qiskit_machine_learning.algorithms.NeuralNetworkClassifier) has not changed.
- Expose the callback attribute as public property on [TrainableModel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.TrainableModel.html#qiskit_machine_learning.algorithms.TrainableModel). This, for instance, allows setting the callback between optimizations and store the history in separate objects.
- Gradient operator/circuit initialization in [OpflowQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.OpflowQNN.html#qiskit_machine_learning.neural_networks.OpflowQNN) and [CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN) respectively is now delayed until the first call of the backward method. Thus, the networks are created faster and gradient framework objects are not created until they are required.
- Introduced a new parameter evaluate_duplicates in [QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel). This parameter defines a strategy how kernel matrix elements are evaluated if duplicate samples are found. Possible values are:

- all means that all kernel matrix elements are evaluated, even the diagonal ones when

training. This may introduce additional noise in the matrix.

- off_diagonal when training the matrix diagonal is set to 1, the rest elements are

fully evaluated, e.g., for two identical samples in the dataset. When inferring, all elements are evaluated. This is the default value.

- none when training the diagonal is set to 1 and if two identical samples are found

in the dataset the corresponding matrix element is set to 1. When inferring, matrix elements for identical samples are set to 1.

- In the previous releases, in the QGAN class, the gradient penalty could not be enabled to train the discriminator with a penalty function. Thus, a gradient penalty parameter was added during the initialization of the QGAN algorithm. This parameter indicates whether or not penalty function is applied to the loss function of the discriminator during training.

- Enable the default construction of the ZFeatureMap in the [TwoLayerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.TwoLayerQNN.html#qiskit_machine_learning.neural_networks.TwoLayerQNN) if the number of qubits is 1. Previously, not providing a feature map for the single qubit case raised an error as default construction assumed 2 or more qubits.

- [VQC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.VQC.html#qiskit_machine_learning.algorithms.VQC) will now raise an error when training from a warm start when encountering targets with a different number of classes to the previous dataset.

- [VQC](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.VQC.html#qiskit_machine_learning.algorithms.VQC) will now raise an error when a user attempts multi-label classification, which is not supported.

- Added two new properties to the [TrainableModel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.TrainableModel.html#qiskit_machine_learning.algorithms.TrainableModel) class:

- fit_result returns a resulting object from the optimization procedure. Please refers to the Terra’s documentation of the OptimizerResult class.
- weights returns an array of trained weights, this is a convenient way to get access to the weights, it is the same as calling model.fit_result.x.

Upgrade Notes

- The method [fit()](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.TrainableModel.fit.html#qiskit_machine_learning.algorithms.TrainableModel.fit) is not abstract any more. Now, it implements basic checks, calls a new abstract method _fit_internal() to be implemented by sub-classes, and keeps track of [fit_result](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.TrainableModel.fit_result.html#qiskit_machine_learning.algorithms.TrainableModel.fit_result) property that is returned by this new abstract method. Thus, any sub-class of [TrainableModel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.TrainableModel.html#qiskit_machine_learning.algorithms.TrainableModel) must implement this new method. Classes [NeuralNetworkClassifier](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.NeuralNetworkClassifier.html#qiskit_machine_learning.algorithms.NeuralNetworkClassifier) and [NeuralNetworkRegressor](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.NeuralNetworkRegressor.html#qiskit_machine_learning.algorithms.NeuralNetworkRegressor) have been updated correspondingly.

- Inheriting from sklearn.svm.SVC in PegasosQSVC resulted in errors when calling some inherited methods such as decision_function due to the overridden fit implementation. For that reason, the inheritance has been replaced by a much lighter inheritance from ClassifierMixin providing the score method and a new method decision_function has been implemented. The class is still sklearn compatible due to duck typing. This means that for the user everything that has been working in the previous release still works, except the inheritance. The only methods that are no longer supported (such as predict_proba) were only raising errors in the previous release in practice.

Deprecation Notes

- The qiskit_machine_learning.algorithms.distribution_learners package is deprecated and will be removed no sooner than 3 months after the release. There’s no direct replacement for the classes from this package. Instead, please refer to the new QGAN tutorial. This tutorial introduces step-by-step how to build a PyTorch-based QGAN using quantum neural networks.

- Classes [qiskit_machine_learning.runtime.TorchRuntimeClient](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.runtime.TorchRuntimeClient.html#qiskit_machine_learning.runtime.TorchRuntimeClient), [qiskit_machine_learning.runtime.TorchRuntimeResult](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.runtime.TorchRuntimeResult.html#qiskit_machine_learning.runtime.TorchRuntimeResult), qiskit_machine_learning.runtime.HookBase and functions qiskit_machine_learning.runtime.str_to_obj(), qiskit_machine_learning.runtime.obj_to_str() are being deprecated. You should use QiskitRuntimeService to leverage primitives and runtimes.

- Class [qiskit_machine_learning.neural_networks.CircuitQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.CircuitQNN.html#qiskit_machine_learning.neural_networks.CircuitQNN) is pending deprecation and is superseded by [qiskit_machine_learning.neural_networks.SamplerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.SamplerQNN.html#qiskit_machine_learning.neural_networks.SamplerQNN).

- Class [qiskit_machine_learning.neural_networks.OpflowQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.OpflowQNN.html#qiskit_machine_learning.neural_networks.OpflowQNN) is pending deprecation and is superseded by [qiskit_machine_learning.neural_networks.EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN).

- Class [qiskit_machine_learning.neural_networks.TwoLayerQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.TwoLayerQNN.html#qiskit_machine_learning.neural_networks.TwoLayerQNN) is pending deprecation and has no direct replacement. Please make use of [qiskit_machine_learning.neural_networks.EstimatorQNN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.neural_networks.EstimatorQNN.html#qiskit_machine_learning.neural_networks.EstimatorQNN) instead.

These classes will be deprecated in a future release and subsequently removed after that.

Class [qiskit_machine_learning.kernels.QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel) is pending deprecation and is superseded by [qiskit_machine_learning.kernels.FidelityQuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.FidelityQuantumKernel.html#qiskit_machine_learning.kernels.FidelityQuantumKernel) and [qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel.html#qiskit_machine_learning.kernels.TrainableFidelityQuantumKernel).

This class will be deprecated in a future release and subsequently removed after that.

- For the class [QuantumKernel](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.kernels.QuantumKernel.html#qiskit_machine_learning.kernels.QuantumKernel), to improve usability and better describe the usage, user_parameters has been renamed to training_parameters; current behavior is retained. For this change the constructor parameter user_parameters is now deprecated and replaced by training_parameters. The related properties and methods are renamed to match. That is to say:

- argument user_parameters -> training_parameters

- property user_parameters -> training_parameters

- property user_param_binds -> training_parameter_binds

- method assign_user_parameters -> assign_training_parameters

- method bind_user_parameters -> bind_training_parameters

- method get_unbound_user_parameters -> get_unbound_training_parameters

Bug Fixes

- Previously in the [QuantumGenerator](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QuantumGenerator.html#qiskit_machine_learning.algorithms.QuantumGenerator) of the [QGAN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QGAN.html#qiskit_machine_learning.algorithms.QGAN) algorithm, if we used a simulator other than the statevector_simulator the result dictionary had not the correct size to compute both the gradient and the loss functions. Now, the values output are stored in a vector of size 2^n and each key is mapped to its value from the result dictionary in the new value array. Also, each key is stored in a vector of size 2^n where each element of the vector keys[i] corresponds to the binary representation of i.

- Previously in the [QuantumGenerator](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QuantumGenerator.html#qiskit_machine_learning.algorithms.QuantumGenerator) of the [QGAN](https://qiskit.org/documentation/machine-learning/stubs/qiskit_machine_learning.algorithms.QGAN.html#qiskit_machine_learning.algorithms.QGAN) algorithm, the gradients were computed using the statevector backend even if we specified another backend. To solve this issue, the gradient object is converted into a CircuitStateFn instead of its adjoint as in the previous version. The gradients are converted into the backend-dependent structure using CircuitSampler. After the evaluation of the object, the gradient_function is stored in a dense array to fix a dimension incompatibility when computing the loss function.

- Fixed quantum kernel evaluation when duplicate samples are found in the dataset. Originally, kernel matrix elements were not evaluated for identical samples in the dataset and such elements were set wrongly to zero. Now we introduced a new parameter evaluate_duplicates that ensures that elements of the kernel matrix are evaluated correctly. See the feature section for more details.

- Previously in the pytorch_discriminator class of the QGAN algorithm, if the gradient penalty parameter was enabled, the latent variable z was not properly initialized : Variable module was used instead of torch.autograd.Variable.

- Calling PegasosQSVC.decision_function() raises an error. Fixed by writing own method instead of inheriting from SVC. The inheritance from SVC in the PegasosQSVC class is removed. To keep the score method, inheritance to the mixin class ClassifierMixin from scikit-learn is added.