SamplerQNN¶

class SamplerQNN(*, circuit, sampler=None, input_params=None, weight_params=None, sparse=False, interpret=None, output_shape=None, gradient=None, input_gradients=False, pass_manager=None)[source]¶

Bases: 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 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 QNNCircuit can be passed as circuit to simplify the composition of a feature map and ansatz. If a QNNCircuit is passed as circuit, the input and weight parameters do not have to be provided, because these two properties are taken from the QNNCircuit.

The output can be set up in different formats, and an optional post-processing step can be used to interpret or map the sampler’s raw output in a particular context (e.g. mapping the resulting bitstring to match the number of classes) via an interpret function.

The output_shape parameter defines the shape of the output array after applying the interpret function, and can be set following the guidelines below.

Default behavior: if no interpret function is provided, the default output_shape is 2**num_qubits, which corresponds to the number of possible bit-strings for the given number of qubits.
Custom interpret function: when using a custom interpret function, you must specify output_shape to match the expected output of the interpret function. For instance, if your interpret function maps bit-strings to two classes, you should set output_shape=2.
Number of classical registers: if you want to reshape the output by the number of classical registers, set output_shape=2**circuit.num_clbits. This is useful when the number of classical registers differs from the number of qubits.
Tuple shape: if the interpret function returns a tuple, output_shape should be a tuple that matches the dimensions of the interpreted output.

In this example, the network maps the output of the quantum circuit to two classes via a custom interpret function:

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

# Define a custom interpret function that calculates the parity of the bitstring
def parity(x):
    return f"{bin(x)}".count("1") % 2

# Example 1: Using the QNNCircuit class
# QNNCircuit automatically combines a feature map and an ansatz into a single circuit
qnn_qc = QNNCircuit(num_qubits)

qnn = SamplerQNN(
    circuit=qnn_qc,  # Note that this is a QNNCircuit instance
    interpret=parity,
    output_shape=2  # Reshape by the number of classical registers
)

# Do a forward pass with input data and custom weights
qnn.forward(input_data=[1, 2], weights=[1, 2, 3, 4, 5, 6, 7, 8])

# Example 2: Explicitly specifying the feature map and ansatz
# Create a feature map and an ansatz separately
feature_map = ZZFeatureMap(feature_dimension=num_qubits)
ansatz = RealAmplitudes(num_qubits=num_qubits)

# Compose the feature map and ansatz manually (otherwise done within QNNCircuit)
qc = QuantumCircuit(num_qubits)
qc.compose(feature_map, inplace=True)
qc.compose(ansatz, inplace=True)

qnn = SamplerQNN(
    circuit=qc,  # Note that this is a QuantumCircuit instance
    input_params=feature_map.parameters,
    weight_params=ansatz.parameters,
    interpret=parity,
    output_shape=2  # Reshape by the number of classical registers
)

# Perform a forward pass with input data and weights
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.

sampler¶

The sampler primitive used to compute the neural network’s results. If not provided, a default instance of the reference sampler defined by Sampler will be used.

Type:: BaseSampler

gradient¶

An optional sampler gradient used for the backward pass. If not provided, a default instance of ParamShiftSamplerGradient will be used.

Type:: BaseSamplerGradient

Parameters:

circuit (QuantumCircuit) – The parametrized quantum circuit that generates the samples of this network. If a QNNCircuit is passed, the input_params and weight_params do not have to be provided, because these two properties are taken from the QNNCircuit.
sampler (BaseSampler | None) –
The sampler primitive used to compute the neural network’s results. If None is given, a default instance of the reference sampler defined by Sampler will be used.

Warning

The assignment sampler=None defaults to using Sampler, which points to a deprecated Sampler V1 (as of Qiskit 1.2). SamplerQNN will adopt Sampler V2 as default no later than Qiskit Machine Learning 0.9.
input_params (Sequence[Parameter] | None) – The parameters of the circuit corresponding to the input. If a QNNCircuit is provided the input_params value here is ignored. Instead, the value is taken from the QNNCircuit input_parameters.
weight_params (Sequence[Parameter] | None) – The parameters of the circuit corresponding to the trainable weights. If a QNNCircuit is provided the weight_params value here is ignored. Instead, the value is taken from the QNNCircuit weight_parameters.
sparse (bool) – Returns whether the output is sparse or not.
interpret (Callable[[int], int | tuple[int, ...]] | None) – 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 the interpret function is None, then an identity function will be used by this neural network: lambda x: x (default).
output_shape (int | tuple[int, ...] | None) – The output shape of the custom interpretation. For SamplerV1, it is ignored if no custom interpret method is provided where the shape is taken to be 2^circuit.num_qubits.
gradient (BaseSamplerGradient | None) – An optional sampler gradient to be used for the backward pass. If None is given, a default instance of ParamShiftSamplerGradient will be used.
input_gradients (bool) – 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 TorchConnector.
pass_manager (BasePassManager | None) – The pass manager to transpile the circuits, if necessary. Defaults to None, as some primitives do not need transpiled circuits.

Raises:

QiskitMachineLearningError – Invalid parameter values.

Attributes

circuit¶: Returns the underlying quantum circuit.

input_gradients¶: Returns whether gradients with respect to input data are computed by this neural network in the backward method or not. By default such gradients are not computed.

input_params¶: Returns the list of input parameters.

interpret¶: 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.

num_inputs¶: Returns the number of input features.

num_weights¶: Returns the number of trainable weights.

output_shape¶: Returns the output shape.

sparse¶: Returns whether the output is sparse or not.

weight_params¶: Returns the list of trainable weights parameters.

Methods

backward(input_data, weights)¶

Backward pass of the network.

Parameters:

input_data (float | list[float] | ndarray | None) – input data of the shape (num_inputs). In case of a single scalar input it is directly cast to and interpreted like a one-element array.
weights (float | list[float] | ndarray | None) – trainable weights of the shape (num_weights). In case of a single scalar weight
array. (it is directly cast to and interpreted like a one-element)

Returns:

The result of the neural network of the backward pass, i.e., a tuple with the gradients for input and weights of shape (output_shape, num_input) and (output_shape, num_weights), respectively.

Return type:

tuple[ndarray | SparseArray | None, ndarray | SparseArray | None]

forward(input_data, weights)¶

Forward pass of the network.

Parameters:

input_data (float | list[float] | ndarray | None) – input data of the shape (num_inputs). In case of a single scalar input it is directly cast to and interpreted like a one-element array.
weights (float | list[float] | ndarray | None) – trainable weights of the shape (num_weights). In case of a single scalar weight it is directly cast to and interpreted like a one-element array.

Returns:

The result of the neural network of the shape (output_shape).

Return type:

ndarray | SparseArray

set_interpret(interpret=None, output_shape=None)[source]¶

Change interpret and corresponding output_shape.

Parameters:

interpret (Callable[[int], int | tuple[int, ...]] | None) – A callable that maps the measured integer to another unsigned integer or tuple of unsigned integers. See constructor for more details.
output_shape (int | tuple[int, ...] | None) – 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.