Skip to content

recurrent_hqnc

eigenkit.torch.estimators.recurrent_hqnc

eigenkit.torch.estimators.recurrent_hqnc.RecurrentHQNC

Bases: ModelAccessMixin, BaseQuantumClassifier

Hybrid classifier: a recurrent encoder, a quantum layer and a linear class head.

The recurrent encoder is a recurrent neural network (RNN). The estimator expects 3-D inputs of shape (n_samples, seq_len, seq_feature_dim). By default, only the last timestep of the RNN output goes to the quantum layer. Set rnn_return_last_timestep=False, together with sequence_length, to use the full RNN output (flattened) instead. The quantum part is the same as in HQNC: MinMaxNorm, the quantum layer and an nn.Linear head.

Parameters:

Name Type Description Default
seq_feature_dim int

The number of features at each time step (the last axis of X).

 required
rnn_type Literal['rnn', 'gru', 'lstm']

The type of recurrent layer: "rnn", "gru" (gated recurrent unit) or "lstm" (long short-term memory).

 'gru'
rnn_hidden_dim int

The hidden size in each direction.

 32
rnn_num_layers int

The number of stacked RNN layers.

 1
rnn_dropout float

The dropout between the RNN layers. It applies only if rnn_num_layers > 1.

 0.0
rnn_bidirectional bool

If True, the RNN is bidirectional, and its output size doubles.

 False
rnn_return_last_timestep bool

If True, only the last output step is kept. Otherwise, the full sequence is flattened, which requires sequence_length.

 True
sequence_length int | None

The number of time steps in each sample. It is required when rnn_return_last_timestep=False, and it must equal X.shape[1] in fit.

 None
in_quantum int | None

The number of inputs of the quantum layer. It defaults to the size of the RNN output that reaches the quantum layer: rnn_hidden_dim, doubled when the RNN is bidirectional, and multiplied by sequence_length when rnn_return_last_timestep=False.

 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 labels passed to fit(). If it is given, it must equal the number of distinct labels in y.

 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 during training.

 True
random_state int | None

The seed for the initialisation of the weights.

 42

Attributes:

Name Type Description
train_losses_

The 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.

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

Fit the estimator on X and y.

Parameters:

Name Type Description Default
X ndarray

The sequences, of shape (n_samples, seq_len, seq_feature_dim).

 required
y ndarray

One label for each sequence, of shape (n_samples,).

 required
X_val ndarray | None

Optional validation sequences, of the same shape as X. Default: None.

 None
y_val ndarray | None

The labels of X_val. Default: None.

 None

Returns:

Type Description
RecurrentHQNC

This estimator, so that calls can be chained.

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 a label for every sample in X.

Parameters:

Name Type Description Default
X ndarray

The sequences, of shape (n_samples, seq_len, seq_feature_dim).

 required

Returns:

Type Description
ndarray

One prediction for each sequence, of shape (n_samples,).

predict_proba(X)

Predict the class probabilities of every sample in X.

Parameters:

Name Type Description Default
X ndarray

The sequences, of shape (n_samples, seq_len, seq_feature_dim).

 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