squlearn.encoding_circuit.LayeredEncodingCircuit

class squlearn.encoding_circuit.LayeredEncodingCircuit(num_qubits: int, num_features: int = None, feature_str: str = 'x', parameter_str: str = 'p', **kwargs)

A class for a simple creation of layered encoding circuits.

Gates are added to all qubits by calling the associated function similar to Qiskit’s circuits. Single qubit gates are added to all qubits, while two qubits gates can be added with different entanglement patterns. The implemented one and two qubit gates are listed below.

Some gates have a input variable, as for example rotation gates, that can be set by supplying the string "x" for feature or "p" for parameter. Non-linear mapping can be added by setting the map variable map=. Two qubit gates can be placed either in a nearest-neighbor NN or a all to all entangling pattern AA.

Simple Layered Encoding Circuit

from squlearn.encoding_circuit import LayeredEncodingCircuit
encoding_circuit = LayeredEncodingCircuit(num_qubits=4)
encoding_circuit.H()
encoding_circuit.Rz("x")
encoding_circuit.Ry("p")
encoding_circuit.cx_entangling("NN")
encoding_circuit.draw("mpl", num_features=2)

Create a layered encoding circuit with non-linear input encoding

It is also possible to define a non-linear function for encoding variables in gates by supplying a function for the encoding as the second argument

import numpy as np
from squlearn.encoding_circuit import LayeredEncodingCircuit

def func(a,b):
    return a*np.arccos(b)

encoding_circuit = LayeredEncodingCircuit(num_qubits=4)
encoding_circuit.H()
encoding_circuit.Rz("p","x",encoding=func)
encoding_circuit.cx_entangling("NN")
encoding_circuit.draw("mpl", num_features=2)

Create a layered encoding circuit with layers

Furthermore, it is possible to define layers and repeat them.

from squlearn.encoding_circuit import LayeredEncodingCircuit
from squlearn.encoding_circuit.layered_encoding_circuit import Layer
encoding_circuit = LayeredEncodingCircuit(num_qubits=4)
encoding_circuit.H()
layer = Layer(encoding_circuit)
layer.Rz("x")
layer.Ry("p")
layer.cx_entangling("NN")
encoding_circuit.add_layer(layer,num_layers=3)
encoding_circuit.draw("mpl", num_features=2)

Create a layered encoding circuit from string

Another very useful feature is the creation from encoding circuits from strings. This can be achieved by the function LayeredEncodingCircuit.from_string().

Gates are separated by -, layers can be specified by N[...] where N is the number of repetitions. The entangling strategy can be set by adding NN or AA. Adding a encoding function is possible by adding a = and the function definition as a string. The variables used in the function are given within curly brackets, e.g. crz(p;=a*np.arccos(b),{y,x};NN).

The following strings are used for the gates:

Single qubit gates and their string representation

String	Function	String	Function	String	Function
"H"	H()	"I"	I()	"P"	P()
"Rx"	Rx()	"Ry"	Ry()	"Rz"	Rz()
"S"	S()	"Sc"	S_conjugate()	"T"	T()
"Tc"	T_conjugate()	"U"	U()	"X"	X()
"Y"	Y()	"Z"	Z()

Two qubit gates and their string representation

String	Function	String	Function	String	Function
"ch"	ch_entangling()	"cx"	cx_entangling()	"cy"	cy_entangling()
"cz"	cz_entangling()	"s"	swap()	"cp"	cp_entangling()
"crx"	crx_entangling()	"cry"	cry_entangling()	"crz"	crz_entangling()
"rxx"	rxx_entangling()	"ryy"	ryy_entangling()	"rzz"	rzz_entangling()
"rzx"	rzx_entangling()	"cu"	cu_entangling()

from squlearn.encoding_circuit import LayeredEncodingCircuit
encoding_circuit = LayeredEncodingCircuit.from_string(
    "Ry(p)-3[Rx(p,x;=y*np.arccos(x),{y,x})-crz(p)]-Ry(p)", num_qubits=4)
encoding_circuit.draw("mpl", num_features=1)

Parameters:

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

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

• feature_str (str) – Label for identifying the feature variable group (default: "x").

• parameter_str (str) – Label for identifying the parameter variable group (default: "p").

H()

Adds a layer of H gates to the Layered Encoding Circuit

I()

Adds a layer of I gates to the Layered Encoding Circuit

P(*variable_str, encoding: Callable | None = None)

Adds a layer of P gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

Rx(*variable_str: str, encoding: Callable | None = None)

Adds a layer of Rx gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

Ry(*variable_str, encoding: Callable | None = None)

Adds a layer of Ry gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

Rz(*variable_str, encoding: Callable | None = None)

Adds a layer of Rz gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

S()

Adds a layer of S gates to the Layered Encoding Circuit

S_conjugate()

Adds a layer of conjugated S gates to the Layered Encoding Circuit

T()

Adds a layer of T gates to the Layered Encoding Circuit

T_conjugate()

Adds a layer of conjugated T gates to the Layered Encoding Circuit

U(*variable_str)

Adds a layer of U gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

X()

Adds a layer of X gates to the Layered Encoding Circuit

Y()

Adds a layer of Y gates to the Layered Encoding Circuit

Z()

Adds a layer of Z gates to the Layered Encoding Circuit

add_layer(layer, num_layers=1) → None

Add a layer num_layers times.

Parameters:

• layer – Layer structure

• num_layers (int) – Number of times that the layer is repeated

ch_entangling(ent_strategy='NN')

Adds a layer of controlled H gates to the Layered Encoding Circuit

Parameters:

ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

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

cp_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of controlled P gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

crx_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of controlled Rx gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

cry_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of controlled Ry gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

crz_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of controlled Rz gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

cu_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of controlled U gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

cx_entangling(ent_strategy='NN')

Adds a layer of controlled X gates to the Layered Encoding Circuit

Parameters:

ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

cy_entangling(ent_strategy='NN')

Adds a layer of controlled Y gates to the Layered Encoding Circuit

Parameters:

ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

cz_entangling(ent_strategy='NN')

Adds a layer of controlled Z gates to the Layered Encoding Circuit

Parameters:

ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

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

classmethod from_string(encoding_circuit_str: str, num_qubits: int, num_features: int = None, feature_str: str = 'x', parameter_str: str = 'p', num_layers: int = 1)

Constructs a Layered Encoding Circuit through a given string of gates.

Parameters:

• encoding_circuit_str (str) – String that specifies the encoding circuit

• num_qubits (int) – Number of qubits in the encoding circuit

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

• feature_str (str) – String that is used in encoding_circuit_str to label features (default: ‘x’)

• parameter_str (str) – String that is used in encoding_circuit_str to label parameters (default: ‘p’)

• num_layers (int) – Number of layers, i.e., the number of repetitions of the encoding circuit (default: 1)

Returns:

Returns a LayeredEncodingCircuit object that contains the specified encoding circuit.

generate_initial_parameters(num_features, seed=None)

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 Layered 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 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

rxx_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of Rxx gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

ryy_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of Ryy gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

rzx_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of Rzx gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

rzz_entangling(*variable_str, ent_strategy='NN', encoding: Callable | None = None)

Adds a layer of Rzz gates to the Layered Encoding Circuit

Parameters:

• variable_str (str) – Labels of variables that are used in the gate

• ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".

• encoding (Callable) – Encoding function that is applied to the variables, input in the same order as the given labels in variable_str

set_params(**params) → None

Sets value of the encoding circuit hyper-parameters.

Parameters:

params – Hyper-parameters and their values, e.g. num_qubits=2.

swap(ent_strategy='NN')

Adds a layer of swap gates to the Layered Encoding Circuit

Parameters:

ent_strategy (str) – Entanglement strategy that is used to determine the entanglement, either "NN" or "AA".