QML Overview and Backends

unitarylab.library.qml provides quantum machine-learning components whose data interface uses PyTorch tensors. It covers discrete-variable and continuous-variable circuits, model training, quantum kernels, noise, and hybrid neural networks. The QML package is organized into submodules; import from the specific submodule needed by the workflow.

Typical workflow


Dataset and preprocessing
      ↓
Encoding layer → parameterized ansatz → readout layer
      ↓
QML model / PyTorch wrapper
      ↓
Backend execution → loss and gradients → optimizer
      ↓
Metrics, diagnostics, checkpoints, and predictions

Minimal runnable example


from unitarylab.library.qml.backends import available_backends, create_backend
 
print(available_backends())
backend = create_backend("torch")
print(backend.capabilities)

Built-in names include:

Name	Backend	Use
`torch`	`TorchBackend`	PyTorch discrete-variable state simulation and automatic differentiation
`unitarylab` / `unitary_lab`	`UnitaryLabBackend`	Execute UnitaryLab circuits
`cvtorch` / `cv_torch`	`CVTorchBackend`	Continuous-variable QML circuits

Registering a backend


from unitarylab.library.qml.backends import (
    QuantumBackend,
    create_backend,
    get_backend_class,
    register_backend,
)
 
register_backend("my_backend", MyBackend, overwrite=False)
backend = create_backend("my_backend", device="cpu")

Interface	Purpose
`available_backends()`	Return a tuple of registered names
`get_backend_class(name)`	Return a backend class
`create_backend(name, **kwargs)`	Instantiate a backend
`register_backend(name, backend_cls, overwrite=False)`	Register a `QuantumBackend` subclass

Names are resolved in lowercase. Duplicate registration fails by default; set overwrite=True only when replacing an existing implementation is intended.

Unified execution contract


from unitarylab.library.qml.execution import (
    BackendCapabilities,
    BackendResult,
    ExecutionConfig,
    ExecutionRequest,
)

BackendCapabilities describes supported devices, measurements, batching, and differentiation.
ExecutionConfig stores shots, randomness, and execution options.
ExecutionRequest combines a circuit, parameters, observables, and configuration into one request.
BackendResult provides a common container for state, probabilities, samples, or expectation values and preserves metadata.

Before execution, circuits can be validated, decomposed, or lowered with ValidateCapabilities, DecomposeToBasis, and TransformProgram. A backend that cannot fulfill a request should raise an error before execution rather than silently changing measurement semantics.

Selection and limitations

Prefer torch for PyTorch automatic differentiation; use unitarylab to execute an existing unitarylab.Circuit.
Shot-based execution has statistical variation; exact-state and probability execution use memory exponential in qubit count.
Continuous-variable and discrete-variable circuits use different circuit and layer types and cannot be mixed directly.
Keep model data dtype and device consistent after constructing the model to avoid parameters and inputs residing on different devices.