Execution Backends and Parameters

The backend determines the state representation and gate implementation; the device selects CPU or an available GPU. Backends preserve the same quantum semantics, but precision, performance, and supported features may differ.

import numpy as np
from unitarylab import Circuit
 
qc = Circuit(2)
result = qc.execute(
    initial_state=None, backend="torch", device="cpu",
    dtype=np.complex128, shots=1, seed=42, backend_options=None,
)

Parameters

Install the CUDA C++ backend with pip install "unitarylab[cuda]". It requires a compatible NVIDIA driver but not a local CUDA Toolkit. Apple MPS does not support complex128; use np.complex64.

shots must be a positive integer, not a boolean; seed must be a nonnegative integer or None. seed=42 makes circuit measurements reproducible; None uses non-fixed sampling. TensorNet accepts max_bond, cutoff, and routing (auto, swap, or mpo) through backend_options:

result = qc.execute(
    backend="tensornet",
    backend_options={"max_bond": 128, "cutoff": 1e-10, "routing": "auto"},
)

TensorNet is suited to one-dimensional local, weakly entangled circuits. Bond dimensions can grow rapidly for highly entangled circuits, so qubit count alone does not predict performance.

TensorNet initial states

In addition to dense state vectors, backend="tensornet" accepts a TensorNetState or a list/tuple of MPS site tensors, each with shape (left_bond, 2, right_bond). Explicit max_bond and cutoff values override the corresponding settings stored in the input TensorNetState. Reading the dense state may require expanding the entire MPS; for large qubit counts, prefer local queries supported by the backend.

Selection and troubleshooting

• Start with torch + cpu and verify correctness before changing backends.
• Use numpy for a NumPy-only path and cpp for compiled gate kernels.
• Missing GPUs, unsupported dtypes, and absent optional extensions raise errors; execution does not silently switch devices.
• complex64 reduces memory use but increases numerical error. Prefer complex128 for deep circuits or error comparisons when supported.
• Fix the circuit, initial state, dtype, shots, and seed when comparing backends.

Related pages

• Executing Circuits and Reading Results
• Density Matrices and Noise Models
• Quick Start