Skip to content

hqnc

eigenkit.torch.estimators.hqnc

eigenkit.torch.estimators.hqnc.HQNC

Bases: ModelAccessMixin, BaseQuantumClassifier

Hybrid quantum neural network classifier (HQNC).

The model is MinMaxNorm -> quantum_layer -> nn.Linear(q_out, n_classes). If the number of features of the data differs from the resolved input size of the quantum layer (derived from in_quantum, n_qubits and layer_type), an nn.Linear adapter is added in front automatically.

Parameters:

Name Type Description Default
in_features int

The number of input features.

 required
in_quantum int | None

The number of inputs that the quantum layer expects. It defaults to in_features.

 None
n_qubits int | None

The number of qubits in each circuit. It defaults to in_quantum.

 None
depth int

The number of repetitions of the variational layer.

 2
n_classes int | None

The number of output classes. If None, it is inferred from the training labels.

 None
layer_type str

The quantum layer. It is one of "Basic", "Reupload" and "Ensemble".

 'Basic'
enc_rotation Literal['RX', 'RY', 'RZ'] | None

The encoding rotation: "RX", "RY", "RZ" or None.

 None
var_rotation Literal['RX', 'RY', 'RZ'] | None

The variational rotation of the "basic" ansatz: "RX", "RY", "RZ" or None.

 None
variational_type Literal['basic', 'strong'] | None

The type of variational block: "basic", "strong" or None.

 None
basis Literal['X', 'Y', 'Z'] | None

The measurement basis: "X", "Y", "Z" or None. For these four arguments, None means "use the default of the layer named by layer_type", which is where each of these values is decided.

 None
provider ProviderSpec

The backend. It takes the same options as Circuit(provider=...).

 'numpy'
lr float

The learning rate of the optimiser.

 0.01
optimizer str

The name of the optimiser. The supported names are "adam", "adamw", "rmsprop" and "sgd".

 'adam'
optimizer_kwargs dict | None

Extra keyword arguments passed to the optimiser.

 None
epochs int

The number of training epochs.

 50
batch_size int

The size of each mini-batch.

 32
show_progress bool

If True, a tqdm progress bar is shown.

 True
random_state int | None

The seed for the initialisation of the weights.

 42

Attributes:

Name Type Description
train_losses_

The average cross-entropy loss of each epoch, set by fit().
validation_losses_

The validation cross-entropy loss of each epoch, set by fit() when validation data is given.
Example 
import numpy as np
from eigenkit.torch.estimators import HQNC

rng = np.random.default_rng(0)
X_train, X_test = rng.normal(size=(30, 4)), rng.normal(size=(5, 4))
y_train = np.arange(30) % 3

model = HQNC(in_features=4, depth=2, n_classes=3)
model.fit(X_train, y_train)
predictions = model.predict(X_test)

fit(X, y, X_val=None, y_val=None)

Fit the classifier on training data.

Parameters:

Name Type Description Default
X ndarray

The samples, of shape (n_samples, in_features).

 required
y ndarray

The class labels, of shape (n_samples,). They can be of any type that scikit-learn's LabelEncoder accepts.

 required
X_val ndarray | None

Optional validation samples, used to compute the validation loss of each epoch.

 None
y_val ndarray | None

Optional validation labels, used to compute the validation loss of each epoch.

 None

Returns:

Type Description
HQNC

This estimator, so that calls can be chained.

Raises:

Type Description
ValueError

If X does not have in_features columns.

load(path, *, provider=None) classmethod

Load a fitted model from a .eigenkit bundle.

Load only bundles that you trust. A bundle can contain joblib pickles, and unpickling runs code, as with torch.load or joblib.load.

Parameters:

Name Type Description Default
path str | Path

The path of the bundle.

 required
provider ProviderSpec | None

A provider that replaces the saved one.

 None

Returns:

Type Description
'BaseQuantumEstimator'

The loaded estimator.

Raises:

Type Description
TypeError

If the method is called on a subclass and the bundle holds a different class. BaseQuantumEstimator.load() accepts any class.

predict(X)

Predict the class labels of X.

Parameters:

Name Type Description Default
X ndarray

The samples, of shape (n_samples, n_features).

 required

Returns:

Type Description
ndarray

One prediction for each sample.

predict_proba(X)

Predict the probability of each class, with a softmax over the logits.

It returns a float32 array of shape (n_samples, n_classes). Each row sums to 1.

Parameters:

Name Type Description Default
X ndarray

The samples, of shape (n_samples, n_features).

 required

Returns:

Type Description
ndarray

The probabilities, of shape (n_samples, n_classes), with the columns in the order of classes_.

save(path)

Save a fitted model to a .eigenkit bundle.

The bundles of models that hold scikit-learn objects (QSVC, QSVR, the reservoir estimators and the time-series estimators) contain joblib pickles, so loading one can run code. Share them only with people who trust you.

Parameters:

Name Type Description Default
path str | Path

The path of the bundle. The suffix .eigenkit is added when it is missing.

 required