API reference

tlquantum: Quantum ML

Density Tensors

TensorLy-Quantum provides a convenient class for representing and manipulating density tensors:

DensityTensor(tensor, subsystems)

A quantum state container for state and density matrix operations, including partial traces and quantum information metric calculations.


Also known as MPO, MPS, tensor-train is an efficient way to represent state-vectors and operators in factorized form. In TensorLy-Quantum, we provide out-of-the-box layers and circuits in the TT format.

Gates in TT-form

Unitary(gates, nqubits, ncontraq[, ...])

A unitary for all qubits in a TTCircuit, using tensor ring tensors with PyTorch Autograd support.

IDENTITY([dtype, device])

Identity gate (does not change the state of the qubit on which it acts).

RotY([dtype, device, random])

Qubit rotations about the Y-axis with randomly initiated theta.

RotX([dtype, device, random])

Qubit rotations about the X-axis with randomly initiated theta.

RotZ([dtype, device, random])

Qubit rotations about the Z-axis with randomly initiated theta.

UnaryGatesUnitary(nqubits, ncontraq[, axis, ...])

A Unitary sub-class that generates a layer of unitary, single-qubit rotations.

BinaryGatesUnitary(nqubits, ncontraq, ...[, ...])

A Unitary sub-class that generates a layer of a single two-qubit gates accross all qubits in a TTCircuit.

CZL([dtype, device])

Left (control-qubit) core of a CZ gate.

CZR([dtype, device])

Right (transformed qubit) core of a CZ gate.

CNOTL([dtype, device])

Left (control-qubit) core of a CNOT gate.

CNOTR([dtype, device])

Right (transformed qubit) core of a CNOT gate.

SO4LR(state1, state2, position[, theta, ...])

Left or right core of the two-qubit SO4 rotations gate.

O4LR(position[, phases, dtype, device])

Left and right core of the two-qubit O4 phase gate.

We also provide some convenience functions to facilitate creation of some of the gates:

cz([dtype, device])

Pair of CZ class instances, one left (control) and one right (transformed).

cnot([dtype, device])

Pair of CNOT class instances, one left (control) and one right (transformed).

so4(state1, state2[, dtype, device])

Pair of SO4 two-qubit rotation class instances, with rotations over different states.

Operators in TT-form

unary_hamiltonian(op, nqubits, qubits, weights)

Generates tt-tensor unitary of one single-qubit operator per qubit.

binary_hamiltonian(op, nqubits, qubits1, ...)

Generates tt-tensor classical Ising model Hamiltonian (two-qubit interaction terms in a single basis).

identity([dtype, device])

Single-qubit identity opertor in the tt-tensor format.

pauli_x([dtype, device])

Single-qubit Pauli-X opertor in the tt-tensor format.

pauli_y([dtype, device])

Single-qubit Pauli-Y opertor in the tt-tensor format.

pauli_z([dtype, device])

Single-qubit Pauli-Z opertor in the tt-tensor format.

States in TT-form

spins_to_tt_state(spins[, device, dtype])

Generates tt-tensor state of computational basis product space described by spins.


The norm of a TT-tensor state.

Creating circuits

TTCircuit(unitaries, ncontraq, ncontral[, ...])

A simulator for variational quantum circuits using tensor ring tensors with PyTorch Autograd support.

Adding TT/MPS/MPOs

tt_sum(t1, t2)

Sums two TT tensors in decomposed form

tt_matrix_sum(t1, t2)

Sums two TT matrices in decomposed form

Contracting Tensor Networks

contraction_eq(nqubits, nlayers[, ...])

Generates einsum contraciton equation.


qubits_contract(layer, ncontraq[, contrsets])

Contracts lists (layers) of tt-tensor cores horizontally (merging multiple cores in a single layer) up to some maximum number of qubits.

layers_contract(layer_list, ncontrl)

Contracts sublists of a list of layers vertically (merging cores of multiple layers for a single qubit) up to some maximum contraction depth.

Solving MaxCut

calculate_cut(spins, spins1, spins2, weights)

Calculates the MaxCut value of a given state (set of spins) for a given graph (weights).

brute_force_calculate_maxcut(nqubits, ...)

Brute force calculation of MaxCut for a given set of spins and weights.