squlearn.encoding_circuit.QCNNEncodingCircuit

class squlearn.encoding_circuit.QCNNEncodingCircuit(num_qubits: int = 0, num_features: int = None, default: bool = False)

Encoding circuit for quantum convolutional neural networks (QCNN).

The structure is inspired by classical convolutional neural networks. The number of active qubits reduces with each layer. The design idea was initially proposed in reference [1].

Parameters:

  • num_qubits (int) – Number of initial qubits of the QCNN encoding circuit.

  • num_features (int) – Dimension of the feature vector. (default: None)

  • default (bool) – If True, the default circuit is built.

References

[1]: Cong, I., Choi, S. & Lukin, M.D. Quantum convolutional neural networks. Nat. Phys. 15, 1273–1278 (2019).

QCNNObservable(obs: ObservableBase | str = 'Z') → ObservableBase

Build a fitting observable for the current circuit.

This function should be called after beeing finished building the circuit. It maps the supplied observable on the circuit, so that only the left qubits are measured.

Parameters:

  • Union[ObservableBase (obs) – A squlearn observable can be supplied with n-qubit measurements, where n can not exceed the number of left qubits. Alternatively, a string of a pauli gate (X, Y or Z) can be supplied and an observable of single qubit measurements, mapped on the left qubits, is build.

  • str] – A squlearn observable can be supplied with n-qubit measurements, where n can not exceed the number of left qubits. Alternatively, a string of a pauli gate (X, Y or Z) can be supplied and an observable of single qubit measurements, mapped on the left qubits, is build.

Returns:

Returns the fitting observable.

build_circuit(final_num_qubits: int = 1)

Build the circuit “backwards”.

Build the circuit by supplying the number of qubits which should be left after the already supplied gates. This function then generates the necessary number of initial qubits and applies the supplied gates.

Parameters:

final_num_qubits (int) – The number of qubits which should be left after applying the supplied gates.

compose(x, concatenate_features=False, concatenate_parameters=False, num_circuit_features: Tuple[int, int] = (None, None))

Composition of encoding circuits with options for handling features and parameters

Number of qubits and features have to be equal in both encoding circuits! The special function and properties of the both encoding circuits are lost by this composition.

Parameters:

  • self (EncodingCircuitBase) – right / first encoding circuit

  • x (EncodingCircuitBase) – left / second encoding circuit

  • concatenate_features (bool) – If True, the features of both encoding circuits are concatenated (default: False). If False, the features of both encoding circuits are taken

  • concatenate_parameters (bool) – If True, the parameters of both encoding circuits are concatenated (default: False). If False, the parameters of both encoding circuits are taken

  • num_circuit_features (Tuple[int, int]) – Tuple of the number of features for both encoding circuits. This has to be provided if concatenate_features is True otherwise an error is raised.

Returns:

Returns the composed encoding circuit as special class ComposedEncodingCircuit

convolution(quantum_circuit: QuantumCircuit | EncodingCircuitBase | None = None, label: str = 'Conv', alternating: bool = True, share_params: bool = False)

Add a convolution layer to the encoding circuit.

Parameters:

  • Union[EncodingCircuitBase (quantum_circuit) – The quantum circuit, which is applied in this layer.

  • QuantumCircuit – The quantum circuit, which is applied in this layer.

  • None] – The quantum circuit, which is applied in this layer.

  • label (str) – The name of the layer.

  • alternating (bool) – The gate is applied on every qubit modulo qubits of this circuit beginning at 0. If True it applies the gate on every qubit beginning at 1 again.

  • share_params (bool) – If False, different parameters are used for the gates in this layer.

default_circuit()

A default circuit for quickly building a QCNN.

draw(output: str = None, num_features: int = None, feature_label: str = 'x', parameter_label: str = 'p', decompose: bool = False, **kwargs) → None

Draws the encoding circuit using the QuantumCircuit.draw() function.

Parameters:

  • output (str) – Output format of the drawing (default: None).

  • num_features (int) – Number of features to draw the circuit with (default: None).

  • feature_label (str) – Label for the feature vector (default:”x”).

  • parameter_label (str) – Label for the parameter vector (default:”p”).

  • decompose (bool) – If True, the circuit is decomposed before printing (default: False).

  • kwargs – Additional arguments from Qiskit’s QuantumCircuit.draw() function.

Raises:

ValueError – Raised if the number of features is not provided.

Returns:

Returns the circuit in qiskit QuantumCircuit.draw() format

fully_connected(quantum_circuit: QuantumCircuit | EncodingCircuitBase | None = None, label: str = 'FC')

Add a fully connected layer to the encoding circuit.

The fully connected layer should be placed at the end and operates on all qubits remaining in the circuit.

Parameters:

  • Union[EncodingCircuitBase (quantum_circuit) – The quantum circuit, which is applied in this layer.

  • QuantumCircuit – The quantum circuit, which is applied in this layer.

  • None] – The quantum circuit, which is applied in this layer.

  • label – The name of the layer.

generate_initial_parameters(num_features: int, seed: int | None = None) → ndarray

Generates random parameters for the encoding circuit

Parameters:

  • num_features (int) – Number of features of the input data

  • seed (Union[int,None]) – Seed for the random number generator (default: None)

Returns:

The randomly generated parameters

get_circuit(features: ParameterVector | ndarray, parameters: ParameterVector | ndarray) → QuantumCircuit

Returns the circuit of the QCNN encoding circuit.

Parameters:

  • Union[ParameterVector (param_vec) – Input vector of the features from which the gate inputs are obtained.

  • np.ndarray] – Input vector of the features from which the gate inputs are obtained.

  • Union[ParameterVector – Input vector of the parameters from which the gate inputs are obtained.

  • np.ndarray] – Input vector of the parameters from which the gate inputs are obtained.

Returns:

Returns the circuit in Qiskit’s QuantumCircuit format.

get_feature_bounds(num_features: int) → ndarray

Returns the feature bounds expanded for a given number of features.

Parameters:

num_features (int) – Number of features to expand the bounds for.

Returns:

Feature bounds expanded for the number of features.

Return type:

np.ndarray

get_params(deep: bool = True) → dict

Returns hyper-parameters and their values of the encoding circuit.

Parameters:

deep (bool) – If True, also the parameters for contained objects are returned (default=True).

Returns:

Dictionary with hyper-parameters and values.

inverse()

Returns the inverse of the encoding circuit.

Returns:

The inverse of the encoding circuit

pooling(quantum_circuit: QuantumCircuit | EncodingCircuitBase | None = None, label: str = 'Pool', measurement: bool = False, input_list: list = [], output_list: list = [])

Add a pooling layer to the encoding circuit.

This reduces the number of qubits to operate on from here on in this circuit by at least one for each circuit applied. Default circuit: Entangles qubit i and qubit i+1. Only qubit i stays in the circuit for further operations.

Parameters:

  • Union[EncodingCircuitBase (quantum_circuit) – The quantum circuit, which is applied in this layer. Must be an entangling layer, which entangles qubits.

  • QuantumCircuit – The quantum circuit, which is applied in this layer. Must be an entangling layer, which entangles qubits.

  • None] – The quantum circuit, which is applied in this layer. Must be an entangling layer, which entangles qubits.

  • label (str) – The name of the layer.

  • measurement (bool) – Sets whether the qubits, which are not used anymore after this layer, are measured. If True, quantum_circuit must consist of exactly one classical bit additionally to the quantum bits.

  • input_list (list) – Optionally one can pass the structure of the gates operating. The input list defines the qubits the input circuit acts on. The list should be structured as: [[qubit1,qubit2,..],[qubit3,qubit4,..],..]. Every qubit can only be adressed once and the number of qubits in each list within the list must be equal to the number of qubits of input circuit. THE QUBIT NUMBERS IN THE SUBLISTS REFER TO THE INITIAL QUBIT NUMBERS!

  • output_list (list) – Exactly if an input list is entered, an output list must be entered. The output list defines the qubits which are left in the circuit to operate on. The list should be structured as: [[qubit1,qubit2,..],[qubit3,qubit4,..],..]. It must have the same length as the input list and in each sublist its elements must be in the corresponding input sublist while beeing at least one element less. THE QUBIT NUMBERS IN THE SUBLISTS REFER TO THE INITIAL QUBIT NUMBERS!

repeat_layers(n_times: int = 0)

Repeat the already applied gates to simply build the circuit.

This does not work with a pooling layer with supplied in- and output lists.

Parameters:

  • n_times (int) – The number of times the already applied gates are repeatedly applied.

  • configuration (default) – At least once applied and until less then 4 qubits are left and only once if there is no pooling gate applied.

set_params(**params)

Sets value of the encoding circuit hyper-parameters.

If the number of qubits is reduced and the supplied pooling gates do not fit to this, this will throw a error in the troubling layer.

Parameters:

params – Hyper-parameters (num_qubits or num_features) and their values, e.g. num_qubits=2.