# This code is part of a Qiskit project.
#
# (C) Copyright IBM 2022, 2024.
#
# 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
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.
"""A Neural Network implementation based on the Sampler primitive."""
from __future__ import annotations
import logging
from numbers import Integral
from typing import Callable, cast, Iterable, Sequence
import numpy as np
from qiskit.circuit import Parameter, QuantumCircuit
from qiskit.primitives import BaseSampler, SamplerResult, Sampler
from qiskit_algorithms.gradients import (
BaseSamplerGradient,
ParamShiftSamplerGradient,
SamplerGradientResult,
)
from qiskit_machine_learning.circuit.library import QNNCircuit
from qiskit_machine_learning.exceptions import QiskitMachineLearningError
import qiskit_machine_learning.optionals as _optionals
from .neural_network import NeuralNetwork
if _optionals.HAS_SPARSE:
# pylint: disable=import-error
from sparse import SparseArray
else:
class SparseArray: # type: ignore
"""Empty SparseArray class
Replacement if sparse.SparseArray is not present.
"""
pass
logger = logging.getLogger(__name__)
[documentos]class SamplerQNN(NeuralNetwork):
"""A neural network implementation based on the Sampler primitive.
The ``SamplerQNN`` is a neural network that takes in a parametrized quantum circuit
with designated parameters for input data and/or weights and translates the quasi-probabilities
estimated by the :class:`~qiskit.primitives.Sampler` primitive into predicted classes. Quite
often, a combined quantum circuit is used. Such a circuit is built from two circuits:
a feature map, it provides input parameters for the network, and an ansatz (weight parameters).
In this case a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` can be passed as
circuit to simplify the composition of a feature map and ansatz.
If a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is passed as circuit, the
input and weight parameters do not have to be provided, because these two properties are taken
from the :class:`~qiskit_machine_learning.circuit.library.QNNCircuit`.
The output can be set up in different formats, and an optional post-processing step
can be used to interpret the sampler's output in a particular context (e.g. mapping the
resulting bitstring to match the number of classes).
In this example the network maps the output of the quantum circuit to two classes via a custom
`interpret` function:
.. code-block::
from qiskit import QuantumCircuit
from qiskit.circuit.library import ZZFeatureMap, RealAmplitudes
from qiskit_machine_learning.circuit.library import QNNCircuit
from qiskit_machine_learning.neural_networks import SamplerQNN
num_qubits = 2
def parity(x):
return f"{bin(x)}".count("1") % 2
# Using the QNNCircuit:
# Create a parameterized 2 qubit circuit composed of the default ZZFeatureMap feature map
# and RealAmplitudes ansatz.
qnn_qc = QNNCircuit(num_qubits)
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])
# Explicitly specifying the ansatz and feature map:
feature_map = ZZFeatureMap(feature_dimension=num_qubits)
ansatz = RealAmplitudes(num_qubits=num_qubits)
qc = QuantumCircuit(num_qubits)
qc.compose(feature_map, inplace=True)
qc.compose(ansatz, inplace=True)
qnn = SamplerQNN(
circuit=qc,
input_params=feature_map.parameters,
weight_params=ansatz.parameters,
interpret=parity,
output_shape=2
)
qnn.forward(input_data=[1, 2], weights=[1, 2, 3, 4, 5, 6, 7, 8])
The following attributes can be set via the constructor but can also be read and
updated once the SamplerQNN object has been constructed.
Attributes:
sampler (BaseSampler): The sampler primitive used to compute the neural network's results.
gradient (BaseSamplerGradient): A sampler gradient to be used for the backward pass.
"""
def __init__(
self,
*,
circuit: QuantumCircuit,
sampler: BaseSampler | None = None,
input_params: Sequence[Parameter] | None = None,
weight_params: Sequence[Parameter] | None = None,
sparse: bool = False,
interpret: Callable[[int], int | tuple[int, ...]] | None = None,
output_shape: int | tuple[int, ...] | None = None,
gradient: BaseSamplerGradient | None = None,
input_gradients: bool = False,
):
"""
Args:
sampler: The sampler primitive used to compute the neural network's results.
If ``None`` is given, a default instance of the reference sampler defined
by :class:`~qiskit.primitives.Sampler` will be used.
circuit: The parametrized quantum circuit that generates the samples of this network.
If a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is passed, the
`input_params` and `weight_params` do not have to be provided, because these two
properties are taken from the
:class:`~qiskit_machine_learning.circuit.library.QNNCircuit`.
input_params: The parameters of the circuit corresponding to the input. If a
:class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
`input_params` value here is ignored. Instead the value is taken from the
:class:`~qiskit_machine_learning.circuit.library.QNNCircuit` input_parameters.
weight_params: The parameters of the circuit corresponding to the trainable weights. If
a :class:`~qiskit_machine_learning.circuit.library.QNNCircuit` is provided the
`weight_params` value here is ignored. Instead the value is taken from the
:class:`~qiskit_machine_learning.circuit.library.QNNCircuit` weight_parameters.
sparse: Returns whether the output is sparse or not.
interpret: A callable that maps the measured integer to another unsigned integer or
tuple of unsigned integers. These are used as new indices for the (potentially
sparse) output array. If no interpret function is
passed, then an identity function will be used by this neural network.
output_shape: The output shape of the custom interpretation. It is ignored if no custom
interpret method is provided where the shape is taken to be
``2^circuit.num_qubits``.
gradient: An optional sampler gradient to be used for the backward pass.
If ``None`` is given, a default instance of
:class:`~qiskit_algorithms.gradients.ParamShiftSamplerGradient` will be used.
input_gradients: Determines whether to compute gradients with respect to input data.
Note that this parameter is ``False`` by default, and must be explicitly set to
``True`` for a proper gradient computation when using
:class:`~qiskit_machine_learning.connectors.TorchConnector`.
Raises:
QiskitMachineLearningError: Invalid parameter values.
"""
# set primitive, provide default
if sampler is None:
sampler = Sampler()
self.sampler = sampler
# set gradient
if gradient is None:
gradient = ParamShiftSamplerGradient(self.sampler)
self.gradient = gradient
self._org_circuit = circuit
if isinstance(circuit, QNNCircuit):
self._input_params = list(circuit.input_parameters)
self._weight_params = list(circuit.weight_parameters)
else:
self._input_params = list(input_params) if input_params is not None else []
self._weight_params = list(weight_params) if weight_params is not None else []
if sparse:
_optionals.HAS_SPARSE.require_now("DOK")
self.set_interpret(interpret, output_shape)
self._input_gradients = input_gradients
super().__init__(
num_inputs=len(self._input_params),
num_weights=len(self._weight_params),
sparse=sparse,
output_shape=self._output_shape,
input_gradients=self._input_gradients,
)
if len(circuit.clbits) == 0:
circuit = circuit.copy()
circuit.measure_all()
self._circuit = self._reparameterize_circuit(circuit, input_params, weight_params)
@property
def circuit(self) -> QuantumCircuit:
"""Returns the underlying quantum circuit."""
return self._org_circuit
@property
def input_params(self) -> Sequence[Parameter]:
"""Returns the list of input parameters."""
return self._input_params
@property
def weight_params(self) -> Sequence[Parameter]:
"""Returns the list of trainable weights parameters."""
return self._weight_params
@property
def interpret(self) -> Callable[[int], int | tuple[int, ...]] | None:
"""Returns interpret function to be used by the neural network. If it is not set in
the constructor or can not be implicitly derived, then ``None`` is returned."""
return self._interpret
[documentos] def set_interpret(
self,
interpret: Callable[[int], int | tuple[int, ...]] | None = None,
output_shape: int | tuple[int, ...] | None = None,
) -> None:
"""Change 'interpret' and corresponding 'output_shape'.
Args:
interpret: A callable that maps the measured integer to another unsigned integer or
tuple of unsigned integers. See constructor for more details.
output_shape: The output shape of the custom interpretation. It is ignored if no custom
interpret method is provided where the shape is taken to be
``2^circuit.num_qubits``.
"""
# derive target values to be used in computations
self._output_shape = self._compute_output_shape(interpret, output_shape)
self._interpret = interpret if interpret is not None else lambda x: x
def _compute_output_shape(
self,
interpret: Callable[[int], int | tuple[int, ...]] | None = None,
output_shape: int | tuple[int, ...] | None = None,
) -> tuple[int, ...]:
"""Validate and compute the output shape."""
# this definition is required by mypy
output_shape_: tuple[int, ...] = (-1,)
if interpret is not None:
if output_shape is None:
raise QiskitMachineLearningError(
"No output shape given; it's required when using custom interpret!"
)
if isinstance(output_shape, Integral):
output_shape = int(output_shape)
output_shape_ = (output_shape,)
else:
output_shape_ = output_shape # type: ignore
else:
if output_shape is not None:
# Warn user that output_shape parameter will be ignored
logger.warning(
"No interpret function given, output_shape will be automatically "
"determined as 2^num_qubits."
)
output_shape_ = (2**self.circuit.num_qubits,)
return output_shape_
def _postprocess(self, num_samples: int, result: SamplerResult) -> np.ndarray | SparseArray:
"""
Post-processing during forward pass of the network.
"""
if self._sparse:
# pylint: disable=import-error
from sparse import DOK
prob = DOK((num_samples, *self._output_shape))
else:
prob = np.zeros((num_samples, *self._output_shape))
for i in range(num_samples):
counts = result.quasi_dists[i]
# evaluate probabilities
for b, v in counts.items():
key = self._interpret(b)
if isinstance(key, Integral):
key = (cast(int, key),)
key = (i, *key) # type: ignore
prob[key] += v
if self._sparse:
return prob.to_coo()
else:
return prob
def _postprocess_gradient(
self, num_samples: int, results: SamplerGradientResult
) -> tuple[np.ndarray | SparseArray | None, np.ndarray | SparseArray]:
"""
Post-processing during backward pass of the network.
"""
if self._sparse:
# pylint: disable=import-error
from sparse import DOK
input_grad = (
DOK((num_samples, *self._output_shape, self._num_inputs))
if self._input_gradients
else None
)
weights_grad = DOK((num_samples, *self._output_shape, self._num_weights))
else:
input_grad = (
np.zeros((num_samples, *self._output_shape, self._num_inputs))
if self._input_gradients
else None
)
weights_grad = np.zeros((num_samples, *self._output_shape, self._num_weights))
if self._input_gradients:
num_grad_vars = self._num_inputs + self._num_weights
else:
num_grad_vars = self._num_weights
for sample in range(num_samples):
for i in range(num_grad_vars):
grad = results.gradients[sample][i]
for k, val in grad.items():
# get index for input or weights gradients
if self._input_gradients:
grad_index = i if i < self._num_inputs else i - self._num_inputs
else:
grad_index = i
# interpret integer and construct key
key = self._interpret(k)
if isinstance(key, Integral):
key = (sample, int(key), grad_index)
else:
# if key is an array-type, cast to hashable tuple
key = tuple(cast(Iterable[int], key))
key = (sample, *key, grad_index)
# store value for inputs or weights gradients
if self._input_gradients:
# we compute input gradients first
if i < self._num_inputs:
input_grad[key] += val
else:
weights_grad[key] += val
else:
weights_grad[key] += val
if self._sparse:
if self._input_gradients:
input_grad = input_grad.to_coo() # pylint: disable=no-member
weights_grad = weights_grad.to_coo()
return input_grad, weights_grad
def _forward(
self,
input_data: np.ndarray | None,
weights: np.ndarray | None,
) -> np.ndarray | SparseArray | None:
"""
Forward pass of the network.
"""
parameter_values, num_samples = self._preprocess_forward(input_data, weights)
# sampler allows batching
job = self.sampler.run([self._circuit] * num_samples, parameter_values)
try:
results = job.result()
except Exception as exc:
raise QiskitMachineLearningError("Sampler job failed.") from exc
result = self._postprocess(num_samples, results)
return result
def _backward(
self,
input_data: np.ndarray | None,
weights: np.ndarray | None,
) -> tuple[np.ndarray | SparseArray | None, np.ndarray | SparseArray | None]:
"""Backward pass of the network."""
# prepare parameters in the required format
parameter_values, num_samples = self._preprocess_forward(input_data, weights)
input_grad, weights_grad = None, None
if np.prod(parameter_values.shape) > 0:
circuits = [self._circuit] * num_samples
job = None
if self._input_gradients:
job = self.gradient.run(circuits, parameter_values)
elif len(parameter_values[0]) > self._num_inputs:
params = [self._circuit.parameters[self._num_inputs :]] * num_samples
job = self.gradient.run(circuits, parameter_values, parameters=params)
if job is not None:
try:
results = job.result()
except Exception as exc:
raise QiskitMachineLearningError("Sampler job failed.") from exc
input_grad, weights_grad = self._postprocess_gradient(num_samples, results)
return input_grad, weights_grad