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¶
|
Description of a qubit IQP circuit for classical expectation-value estimation. |
|
A class to store qudit IQP circuit configurations. |
|
Hyperparameters for the qubit Maximum Mean Discrepancy (MMD) loss. |
|
Hyperparameters for the qudit graph-kernel MMD loss. |
|
Build an estimator for Pauli expectation values of a qubit IQP circuit. |
|
Build a reusable loss function that computes the qubit Pauli-kernel Maximum Mean Discrepancy (MMD) loss. |
|
Build an estimator for expectation values of a qudit IQP circuit. |
|
Build a reusable loss function that computes the qudit graph-kernel MMD. |
|
Choose a reasonable radial basis function (RBF) kernel bandwidth from a target dataset. |
|
Run a complete optimization loop with automatic convergence detection. |
|
Create an infinite iterator that yields optimization results one batch at a time. |
|
Options controlling the behaviour of |
|
Results returned by |
|
Intermediate result yielded by |
Circuit construction utilities¶
|
Generate gates based on spatial locality on a 2-D qubit lattice. |
|
Generate a gate dictionary containing all qubit subsets up to a given weight. |
|
Generate a gate dictionary with randomly chosen qubit subsets. |
|
Generate Pauli observables as integer-encoded arrays. |