Data, Circuit Layers, and Models
The QML data layer uses PyTorch tensors. Circuits are composed of an encoding layer, a parameterized ansatz, and a readout layer. High-level models combine these components for classification, regression, or generative tasks.
Data and preprocessing
import torch
from unitarylab.library.qml.data import (
Dataset,
scale_features_to_range,
standardize,
train_test_split,
)
features = torch.tensor([
[-1.0, 0.2], [-0.5, 0.4], [0.6, -0.3], [1.0, -0.8]
], dtype=torch.float64)
targets = torch.tensor([0, 0, 1, 1])
dataset = Dataset(
features=scale_features_to_range(standardize(features)),
targets=targets,
)
train_set, test_set = train_test_split(dataset, test_fraction=0.25, seed=0)| Utility | Purpose |
|---|---|
Dataset | Store features, targets, and optional metadata |
standardize() | Standardize each feature |
scale_features_to_range() | Map features to an angle-encoding interval |
pad_features() | Pad features to the dimension required by an encoder |
TargetStandardizer | Fit, transform, and restore regression targets |
train_test_split(), stratified_train_test_split(), k_fold_split() | Split datasets |
load_csv_dataset() | Construct a dataset from CSV |
bars_and_stripes_patterns() | Generate example data for modeling |
Fit preprocessing statistics on the training set only, then apply them to validation and test data to prevent data leakage.
Encoding, ansatz, and readout
from unitarylab.library.qml.layers import AngleEncoding, HardwareEfficientAnsatz
encoding = AngleEncoding(num_qubits=2)
ansatz = HardwareEfficientAnsatz(num_qubits=2, num_layers=1)| Category | Main components | Input constraints |
|---|---|---|
| Encoding | AngleEncoding, DenseAngleEncoding, AmplitudeEncoding, ZZFeatureEncoding | Angle encoding requires a matching feature count; amplitude encoding requires a normalizable vector compatible with dimension |
| Ansatz | HardwareEfficientAnsatz, DataReuploadingAnsatz, QCNNAnsatz | Parameter-vector length must equal parameter_count |
| Entanglers | FixedEntangler, ParameterizedEntangler | Edges must refer to qubits within the circuit |
| Readouts | ExpectationReadout, PauliReadout, ProbabilityReadout, SampleReadout, StateReadout, DensityMatrixReadout | Return type depends on backend capabilities and shots configuration |
| Continuous-variable | CVDisplacementEncoding, CVNeuralNetworkAnsatz, QuadratureReadout | For continuous-variable backends only |
SequentialCircuitLayer composes multiple layers in order. as_parameter_vector() and split_parameter_vector() organize and split parameter vectors.
High-level models
from unitarylab.library.qml.models import VQCClassifier
from unitarylab.library.qml.nn import TorchQMLLayer
model = VQCClassifier(
num_qubits=4, num_layers=1, num_classes=3,
readout_wires=(0, 1, 2),
)
module = TorchQMLLayer(model, seed=0)| Task | Models |
|---|---|
| Classification | QuantumClassifier, VQCClassifier, DataReuploadingClassifier, QCNNClassifier, CVQuantumClassifier |
| Regression | QuantumRegressor, VQRegressor, DataReuploadingRegressor, QCNNRegressor |
| Generative | QuantumBornMachine, QuantumGenerator |
| Custom variational models | QMLModel, ParameterizedQMLModel, VariationalQuantumModel |
| PyTorch integration | TorchQMLLayer, TorchBornMachine, TorchQuantumGenerator, QuantumGAN, Quanvolution2d |
Class count, readout dimension, and loss function must agree. Batch-aware interfaces use the first dimension as the batch dimension; single-sample and batch output shapes may differ. Run a forward pass and inspect shapes before training.
Resource constraints
Qubit count determines the state-space size, while ansatz depth determines trainable parameter count and circuit depth. Amplitude encoding also requires preparation of a normalized state. Begin with a small qubit count and one ansatz layer, then expand based on validation results.