qp.labs.tcdq

This module contains features to enable Train Classical, Deploy Quantum (TCDQ) workflows.

Warning

This module is experimental. Frequent changes will occur, with no guarantees of stability or backwards compatibility.

What is TCDQ?

TCDQ is a framework for training and deploying parameterized quantum circuits (Recio-Armengol et al. (2025)). Unlike traditional approaches to circuit optimization, TCDQ circuits can be trained using classical hardware alone, which enables training of quantum circuits with thousands of qubits and millions of parameters on a laptop or GPU. Although training can be done classically, deploying the trained circuit on quantum hardware for sampling or downstream quantum algorithms can lead to advantages over purely classical algorithms. For example, sampling from Instantaneous Quantum Polynomial (IQP) circuit distributions is known to be hard for classical algorithms in general (up to complexity theoretic assumptions); see Bremner et al. (2016).

This module implements the features needed to classically train TCDQ circuits and uses JAX. Currently, the supported circuits consist of qubit IQP circuits and their generalization to qudits.

Creating an IQP circuit

A qubit IQP circuit can be created by specifying the generators of the diagonal gates. That description is a dictionary mapping a parameter index to a list of gates, where each gate is a list of qubit indices. For instance, {0: [[0, 1]], 1: [[2]]} means parameter 0 drives a \(ZZ\) gate on qubits 0 and 1, and parameter 1 drives a \(Z\) gate on qubit 2. Listing several gates under the same key ties them to a shared parameter. The module contains utilities to create gates: create_local_gates(), create_lattice_gates(), or create_random_gates().

from pennylane.labs.tcdq import create_local_gates

n_qubits = 5

# All one- and two-qubit gates
gates = create_local_gates(n_qubits, max_weight=2)

TCDQ also allows for user-defined diagonal layers beyond those constructed by Pauli-\(Z\) generators. This is achieved by defining a phase function in JAX that maps a bitstring to a real phase defining the entries of the diagonal unitary.

import jax
import jax.numpy as jnp

# A one-hidden-layer network mapping a bitstring to a real phase
def phase_fn(phase_fn_params, z):
    weights, readout = phase_fn_params
    return jnp.dot(readout, jnp.tanh(weights @ z))

We then create a CircuitConfig object to store the circuit structure. This is used to build expectation value estimators below.

from pennylane.labs.tcdq import CircuitConfig

config = CircuitConfig(
    gates=gates,
    n_qubits=n_qubits,
    n_samples=1000,
    key=jax.random.PRNGKey(0),
    phase_fn=phase_fn # None if no phase layer is used
)

The phase layer is applied in addition to the layers defined by the gates. The order is irrelevant, as all gates in the diagonal layer commute. n_samples sets the accuracy of every estimate produced from this configuration: the standard error of each expectation value falls off as \(1/\sqrt{N}\), where \(N\) is n_samples.

Estimating expectation values

Expectation values of Pauli words can be estimated using a Monte Carlo estimator. Pauli words are encoded as integer rows of length n_qubits using I=0, X=1, Y=2, Z=3, so [3, 2, 0, 1] is \(Z \otimes Y \otimes I \otimes X\). A whole batch of observables is estimated at once: stack one row per Pauli word into an array of shape (n_observables, n_qubits), and a single call returns an estimate for every row.

The function build_expval_func() turns a configuration into a pure function that returns the estimated expectation values and their variance as a function of the trainable parameters. Once built, it can be JIT-compiled for faster evaluation. If the configuration defines a phase function, its parameters are passed as the second argument, and gradients flow to them just as they do to the gate parameters.

from pennylane.labs.tcdq import build_expval_func

# A batch of two observables, one row each
observables = jnp.array(
    [
        [3, 3, 0, 0, 0],  # Z on qubits 0 and 1
        [0, 0, 1, 2, 0],  # X on qubit 2, Y on qubit 3
    ]
)

expval_fn = jax.jit(build_expval_func(config))
gates_params = jax.random.uniform(jax.random.PRNGKey(2), shape=(len(gates),))

w_key, r_key = jax.random.split(jax.random.PRNGKey(1))
phase_fn_params = (
    jax.random.normal(w_key, shape=(4, n_qubits)),
    jax.random.normal(r_key, shape=(4,)),
)

expvals, variances = expval_fn(
    gates_params=gates_params,
    phase_fn_params=phase_fn_params,
    observables=observables,
    key=jax.random.PRNGKey(2),
)

Input states

By default the circuit starts from \(|0\rangle^{\otimes n}\). Any state that is sparse in the computational basis can be used instead, by listing its non-zero amplitudes: init_state_elems is an (N, n_qubits) binary array of basis states, and init_state_amps the matching length-N array of (possibly complex) amplitudes.

# alpha |00...0> + beta |11...1>

elems = jnp.array([[0] * n_qubits, [1] * n_qubits])
amps_params = jnp.array([1.0, 2.0])
amps = amps_params / jnp.linalg.norm(amps_params)

expvals, variances = expval_fn(
    gates_params=gates_params,
    phase_fn_params=phase_fn_params,
    observables=observables,
    init_state_elems=elems,
    init_state_amps=amps,
    key=jax.random.PRNGKey(2),
)

Note that the amplitudes are not automatically normalized and should be provided in a normalized form if this is desired.

Training a circuit

Since the estimator is an ordinary differentiable JAX function, a loss is just a Python function of the parameters. Here we minimize the sum of all single-qubit \(Z\) expectation values:

# trainable parameters
params = {
    "gates": gates_params,
    "phase_fn": phase_fn_params,
    "amps": amps_params,
}

observables = 3 * jnp.eye(n_qubits, dtype=int)  # all single-qubit Pauli-Z observables

def loss_fn(params, key):
    amps = params["amps"] / jnp.linalg.norm(params["amps"])
    expvals, _ = expval_fn(
        gates_params=params["gates"],
        phase_fn_params=params["phase_fn"],
        init_state_elems=elems,
        init_state_amps=amps,
        observables=observables,
        key=key,
    )
    return jnp.sum(expvals)

loss_fn = jax.jit(loss_fn)

The loss can be optimized by computing gradients via jax.grad and using any custom optimization routine written in JAX. The module contains a function train() that minimizes the loss function in this way.

from pennylane.labs.tcdq import TrainingOptions, train

result = train(
    optimizer="Adam",
    loss=loss_fn,
    stepsize=0.001,
    n_iters=2000,
    loss_kwargs={"params": params},
    options=TrainingOptions(random_state=1234),
)

print("Final loss:", float(result.losses[-1]))
trained_params = result.final_params

TCDQ contains a dedicated loss function for training quantum generative models. For distributions of bitstrings, build_mmd_loss_pauli() can be used to construct the maximum mean discrepancy loss function that trains the circuit to match a target distribution, as described in Recio-Armengol et al. (2025). The build_mmd_loss_pauli() constructor requires a callable with arguments params, observables and key (where params is any pytree of trainable parameters) which returns estimates of Z-type Pauli observables specified by observables. This design is intentionally modular in order to be compatible with other circuits and estimators beyond those here.

from pennylane.labs.tcdq import MMDConfig, build_mmd_loss_pauli, median_heuristic

key = jax.random.PRNGKey(3)
target_data = jax.random.binomial(key, 1, p=0.5, shape=(500, n_qubits))
mmd_config = MMDConfig(bandwidth=median_heuristic(target_data), n_ops=100)

def expval_fn_train(params, observables, key, init_state_elems):
    amps = params["amps"] / jnp.linalg.norm(params["amps"]) # normalize the amplitudes
    result = expval_fn(
        gates_params=params["gates"],
        phase_fn_params=params["phase_fn"],
        init_state_amps=amps,
        init_state_elems=init_state_elems,
        observables=observables,
        key=key,
    )
    return result

loss_fn = build_mmd_loss_pauli(expval_fn_train, n_qubits, mmd_config)

mmd_result = train(
    optimizer="Adam",
    loss=loss_fn,
    stepsize=0.001,
    n_iters=1000,
    loss_kwargs={"params": params, "target_data": target_data, "init_state_elems": elems},
    options=TrainingOptions(random_state=1234),
)

print("Final MMD loss:", float(mmd_result.losses[-1]))

Qudit circuits

The workflow above extends to qudit circuits, where the gate generators are powers of the generalized Pauli-\(Z\) operator. Here the gate dictionary maps parameters to a list of gates, and each gate is represented by a dictionary mapping qudits to exponents of \(Z\) , with entries in \(\{1, \ldots, d-1\}\). For instance, {1: 3, 2: 1} applies \(Z^3\) on qudit 1 and \(Z\) on qudit 2. Observables are Heisenberg–Weyl operators specified by a pair (l_vecs, m_vecs) of integer vectors. See Huang et al. (2026) for details.

from pennylane.labs.tcdq import QuditCircuitConfig, build_qudit_expval_func

n_qudits = 4
dims = 4  # Local dimension of the qudits
qudit_gates = {
    0: [{0: 1}],
    1: [{1: 1}],
    2: [{2: 3}],
    3: [{3: 1}],
    4: [{0: 1, 1: 2}],
    5: [{1: 3, 2: 1}],
    6: [{2: 1, 3: 1}],
}

qudit_config = QuditCircuitConfig(
    dims=dims,
    n_qudits=n_qudits,
    gates=qudit_gates,
    n_samples=1000,
    key=jax.random.PRNGKey(0),
)

l_vecs = jnp.array([[1, 0, 0, 0], [1, 1, 2, 0]])
m_vecs = jnp.array([[0, 2, 0, 0], [1, 3, 0, 2]])

qudit_expval_fn = jax.jit(build_qudit_expval_func(qudit_config))
qudit_params = jnp.ones(len(qudit_gates))

expvals, covariances = qudit_expval_fn(
    gates_params=qudit_params,
    observables=(l_vecs, m_vecs),
    key=jax.random.PRNGKey(2),
)

Phase functions and sparse initial states work as in the qubit case, with bitstrings replaced by dit-strings. Note that the expectation values are complex, so the estimator returns a real–imaginary covariance matrix for each observable.

For distribution matching, build_mmd_loss_hw() accepts a Heisenberg–Weyl expectation value function and uses a heat kernel on either a cycle graph, which preserves adjacency between levels, or a complete graph, which treats distinct levels symmetrically.

from pennylane.labs.tcdq import QuditMMDConfig, build_mmd_loss_hw

qudit_mmd_config = QuditMMDConfig(
    bandwidth=0.5,
    n_ops=100,
    graph_type="cycle",
)
qudit_loss_fn = build_mmd_loss_hw(
    qudit_expval_fn,
    dims=dims,
    n_qudits=n_qudits,
    mmd_config=qudit_mmd_config,
)
target_data = jax.random.randint(
    jax.random.PRNGKey(1), shape=(500, n_qudits), minval=0, maxval=dims
)

qudit_result = train(
    optimizer="Adam",
    loss=qudit_loss_fn,
    stepsize=0.01,
    n_iters=1000,
    loss_kwargs={"params": qudit_params, "target_data": target_data},
    options=TrainingOptions(random_state=1234),
)

Core classes and functions

CircuitConfig([gates, n_samples, key, ...])

Description of a qubit IQP circuit for classical expectation-value estimation.

QuditCircuitConfig([dims, n_qudits, gates, ...])

A class to store qudit IQP circuit configurations.

MMDConfig([bandwidth, n_ops, wires, ...])

Hyperparameters for the qubit Maximum Mean Discrepancy (MMD) loss.

QuditMMDConfig([bandwidth, n_ops, ...])

Hyperparameters for the qudit graph-kernel MMD loss.

build_expval_func(config)

Build an estimator for Pauli expectation values of a qubit IQP circuit.

build_mmd_loss_pauli(expval_fn, n_qubits, ...)

Build a reusable loss function that computes the qubit Pauli-kernel Maximum Mean Discrepancy (MMD) loss.

build_qudit_expval_func(config)

Build an estimator for expectation values of a qudit IQP circuit.

build_mmd_loss_hw(expval_fn, dims, n_qudits, ...)

Build a reusable loss function that computes the qudit graph-kernel MMD.

median_heuristic(samples)

Choose a reasonable radial basis function (RBF) kernel bandwidth from a target dataset.

train(optimizer, loss, stepsize, n_iters, ...)

Run a complete optimization loop with automatic convergence detection.

training_iterator(optimizer, loss, stepsize, ...)

Create an infinite iterator that yields optimization results one batch at a time.

TrainingOptions([unroll_steps, val_kwargs, ...])

Options controlling the behaviour of train() and training_iterator().

TrainingResult(final_params, losses, ...)

Results returned by train() after the optimization loop completes.

BatchResult(params, state, key, key_val, ...)

Intermediate result yielded by training_iterator() after each unrolled batch.

Circuit construction utilities

create_lattice_gates(rows, cols[, distance, ...])

Generate gates based on spatial locality on a 2-D qubit lattice.

create_local_gates(n_qubits[, max_weight])

Generate a gate dictionary containing all qubit subsets up to a given weight.

create_random_gates(n_qubits, n_gates[, ...])

Generate a gate dictionary with randomly chosen qubit subsets.

generate_pauli_observables(n_qubits[, ...])

Generate Pauli observables as integer-encoded arrays.