# Copyright 2026 Xanadu Quantum Technologies Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Maximum Mean Discrepancy (MMD) loss for Heisenberg-Weyl expectation value functions.
This module extends :mod:`~pennylane.labs.tcdq.build_mmd_loss_pauli` from qubits to
qudits. It compares the circuit output to a dataset by sampling observables,
estimating their moments, and combining those estimates into an unbiased MMD
loss.
The kernel is defined from a graph on one qudit level set. The available
choices are the cycle graph :math:`C_d` and the complete graph :math:`K_d`.
For the mathematical construction, see
`Section IV B of Spectral Born machines: classically trainable quantum generative models for discrete data <https://arxiv.org/abs/2607.06675>`_.
"""
from collections.abc import Callable, Sequence
from dataclasses import dataclass
from functools import partial
import jax
import jax.numpy as jnp
from jax.typing import ArrayLike
from .qudit_expval_functions import _dims_to_numpy
_REAL_DTYPE = jnp.float32
_COMPLEX_DTYPE = jnp.complex64
_INDEX_DTYPE = jnp.int32
[docs]
@dataclass(frozen=True)
class QuditMMDConfig:
r"""Hyperparameters for the qudit graph-kernel MMD loss.
The MMD measures how well the model output matches a target dataset of
dit-strings. In the qudit setting, the kernel comes from heat diffusion on
a graph over the local levels of one qudit, applied independently to each
visible wire.
Args:
bandwidth (float | Sequence[float]): The bandwidth :math:`\sigma^2` of the kernel. If a sequence is provided,
the loss is evaluated for each value and then averaged, unless
``return_per_bandwidth=True``.
n_ops (int): Number of sampled observables per bandwidth. Larger
values reduce estimator variance.
graph_type (str): Graph whose spectrum defines the kernel.
``"cycle"`` is usually the better default when neighbouring qudit
levels have a natural notion of closeness. ``"complete"`` treats
all distinct levels symmetrically. Defaults to ``"cycle"``.
wires (Sequence[int] | None): Subset of qudit indices to include in
the loss. If ``None`` (default), all qudits are used.
sqrt_loss (bool): If ``True``, return ``sqrt(|MMD²|)`` instead of
``MMD²``. Defaults to ``False``.
return_per_bandwidth (bool): If ``True``, return a list of
per-bandwidth loss values instead of their scalar average.
Defaults to ``False``.
**Example**
>>> from pennylane.labs.tcdq import QuditMMDConfig
>>> config = QuditMMDConfig(bandwidth=[0.3, 1.0], n_ops=64, graph_type="cycle")
"""
#: Width of the graph heat kernel (scalar or sequence for multi-bandwidth).
bandwidth: float | Sequence[float] = None
#: Number of sampled observables per bandwidth.
n_ops: int = None
#: Graph whose spectrum defines the kernel (``"cycle"`` or ``"complete"``).
graph_type: str = "cycle"
#: Subset of qudit indices to include, or ``None`` for all qudits.
wires: Sequence[int] | None = None
#: If ``True``, return ``sqrt(|MMD²|)`` instead of ``MMD²``.
sqrt_loss: bool = False
#: If ``True``, return per-bandwidth losses instead of their average.
return_per_bandwidth: bool = False
def _cycle_marginal_probs(d: int, t: float) -> jnp.ndarray:
"""Return the per-site sampling distribution for the cycle-graph heat kernel.
The probability of sampling index :math:`k` on a single qudit is
proportional to :math:`\\exp(-4t \\sin^2(\\pi k / d))`, which are the
eigenvalues of the heat kernel on the cycle graph :math:`C_d`.
For the derivation, see
`Section IV B of Spectral Born machines: classically trainable quantum generative models for discrete data <https://arxiv.org/abs/2607.06675>`_.
"""
k = jnp.arange(d, dtype=_REAL_DTYPE)
log_p = -4.0 * t * jnp.sin(jnp.pi * k / d) ** 2
p = jnp.exp(log_p)
return p / jnp.sum(p)
def _complete_marginal_probs(d: int, t: float) -> jnp.ndarray:
"""Return the per-site sampling distribution for the complete-graph heat kernel.
The complete graph :math:`K_d` has only two distinct eigenvalues,
yielding a binary distribution: index 0 has elevated probability and all
other indices share the remaining mass equally.
For the derivation, see
`Section IV B of Spectral Born machines: classically trainable quantum generative models for discrete data <https://arxiv.org/abs/2607.06675>`_.
"""
log_unnorm = jnp.zeros(d, dtype=_REAL_DTYPE).at[1:].set(-t * d)
p = jnp.exp(log_unnorm)
return p / jnp.sum(p)
def _marginal_probs(d: int, bandwidth: float, graph_type: str) -> jnp.ndarray:
"""Dispatch to the per-site heat-kernel marginal for a single qudit of dimension ``d``."""
if graph_type == "cycle":
return _cycle_marginal_probs(d, bandwidth)
if graph_type == "complete":
return _complete_marginal_probs(d, bandwidth)
raise ValueError(f"Unknown graph_type {graph_type!r}; use 'cycle' or 'complete'.")
def _sample_fourier_indices( # pylint: disable=too-many-arguments
key: ArrayLike,
n_ops: int,
n_qudits: int,
dims: tuple[int, ...],
bandwidth: float,
graph_type: str,
wire_tuple: tuple[int, ...],
) -> jnp.ndarray:
"""Sample Fourier index vectors from the graph-kernel spectral distribution.
Draws ``n_ops`` vectors from the product distribution
:math:`P(\\mathbf{l}) = \\prod_i P_1(l_i)` where :math:`P_1` is the per-site
heat kernel on a graph over that qudit's :math:`d_i` levels. Positions outside
``wire_tuple`` are zero.
Args:
dims (tuple[int, ...]): Per-qudit dimensions, length ``n_qudits``.
Returns:
Integer array of shape ``(n_ops, n_qudits)``; column ``i`` has entries
in :math:`\\{0, \\ldots, d_i-1\\}`.
"""
wires_by_dim: dict[int, list[int]] = {}
for wire in wire_tuple:
wires_by_dim.setdefault(int(dims[wire]), []).append(int(wire))
all_obs = jnp.zeros((n_ops, n_qudits), dtype=_INDEX_DTYPE)
keys = jax.random.split(key, len(wires_by_dim)) if wires_by_dim else []
for group_key, (d_i, wires) in zip(keys, sorted(wires_by_dim.items())):
marginal = _marginal_probs(d_i, bandwidth, graph_type)
cols = jax.random.choice(group_key, d_i, shape=(n_ops, len(wires)), p=marginal)
all_obs = all_obs.at[:, jnp.asarray(wires, dtype=_INDEX_DTYPE)].set(
cols.astype(_INDEX_DTYPE)
)
return all_obs
def _empirical_fourier_moments(
l_visible: jnp.ndarray,
X_data: jnp.ndarray,
dims_visible: jnp.ndarray,
) -> jnp.ndarray:
"""Compute the empirical Fourier moment for each sampled observable from the dataset.
For each Fourier index vector :math:`\\mathbf{l}`, computes
:math:`\\hat{\\mu}_p(\\mathbf{l}) = \\frac{1}{m} \\sum_i \\exp(2\\pi i \\sum_k l_k x_{ik} / d_k)`,
i.e. the per-qudit root of unity :math:`\\omega_k = e^{2\\pi i / d_k}`. The
per-visible-wire dimension is folded in by column-scaling ``l_visible`` with
``1 / dims_visible``.
Args:
l_visible: Integer array of shape ``(n_obs, n_visible)`` — the Fourier
index vectors restricted to the visible wires.
X_data: Integer array of shape ``(m, n_visible)`` — target dataset
samples on the visible wires.
dims_visible: Integer array of shape ``(n_visible,)`` — dimension of
each visible qudit.
Returns:
Complex array of shape ``(n_obs,)``.
"""
inv_d = 1.0 / jnp.asarray(dims_visible, dtype=_REAL_DTYPE)
l_scaled = l_visible.astype(_REAL_DTYPE) * inv_d[jnp.newaxis, :]
inner = l_scaled @ X_data.astype(_REAL_DTYPE).T
return jnp.mean(jnp.exp(2j * jnp.pi * inner).astype(_COMPLEX_DTYPE), axis=1)
def _pp_term(mu_p_hat: jnp.ndarray, m: int) -> jnp.ndarray:
"""Compute the unbiased data–data U-statistic contribution to the MMD.
Removes the diagonal self-pairs from :math:`|\\hat{\\mu}_p|^2`:
:math:`PP(l) = (m |\\hat{\\mu}_p(l)|^2 - 1) / (m - 1)`.
Args:
mu_p_hat: Complex array of shape ``(n_obs,)`` — empirical data moments.
m: Number of samples in the dataset.
Returns:
Real array of shape ``(n_obs,)``.
"""
return (m * jnp.abs(mu_p_hat) ** 2 - 1.0) / (m - 1)
def _qq_term(
mu_q_hat: jnp.ndarray,
cov: jnp.ndarray | None,
) -> jnp.ndarray:
"""Compute the unbiased model–model U-statistic contribution to the MMD.
Removes the estimated variance of the complex sample mean from
:math:`|\\hat{\\mu}_q|^2`. When ``cov`` is ``None`` the model moments are
treated as exact and no variance correction is applied.
Args:
mu_q_hat: Complex array of shape ``(n_obs,)`` — model-side moment
estimates.
cov: Real array of shape ``(n_obs, 2, 2)`` — covariance matrices of
the real and imaginary parts of the estimated moments, or ``None``
for an exact model.
Returns:
Real array of shape ``(n_obs,)``.
"""
if cov is None:
return jnp.abs(mu_q_hat) ** 2
variances = jnp.trace(cov, axis1=-2, axis2=-1)
return jnp.abs(mu_q_hat) ** 2 - variances
def _pq_cross_term(
mu_p_hat: jnp.ndarray,
mu_q_hat: jnp.ndarray,
) -> jnp.ndarray:
"""Compute the data–model cross term of the MMD.
:math:`PQ(l) = 2 \\operatorname{Re}(\\hat{\\mu}_p(l)^* \\hat{\\mu}_q(l))`.
No diagonal correction is needed because the data and model samples are
independent.
Args:
mu_p_hat: Complex array of shape ``(n_obs,)`` — data-side moments.
mu_q_hat: Complex array of shape ``(n_obs,)`` — model-side moments.
Returns:
Real array of shape ``(n_obs,)``.
"""
return 2.0 * jnp.real(jnp.conj(mu_p_hat) * mu_q_hat)
@partial(jax.jit, static_argnames=["dims_visible", "sqrt_loss"])
def _unbiased_mmd_squared( # pylint: disable=too-many-arguments
mu_q_hat: jnp.ndarray,
cov: jnp.ndarray | None,
X_data: jnp.ndarray,
l_visible: jnp.ndarray,
dims_visible: tuple[int, ...],
sqrt_loss: bool,
) -> jnp.ndarray:
"""Combine PP, PQ, and QQ terms into the unbiased MMD² estimator.
``cov`` may be ``None`` for an exact model.
"""
m = X_data.shape[0]
mu_p_hat = _empirical_fourier_moments(l_visible, X_data, jnp.asarray(dims_visible))
pp_term = _pp_term(mu_p_hat, m)
pq_term = _pq_cross_term(mu_p_hat, mu_q_hat)
qq_term = _qq_term(mu_q_hat, cov)
mmd_sq = jnp.mean(qq_term - pq_term + pp_term)
return jnp.sqrt(jnp.abs(mmd_sq)) if sqrt_loss else mmd_sq
@partial(
jax.jit,
static_argnames=[
"n_ops",
"n_qudits",
"dims",
"wire_tuple",
"sqrt_loss",
"expval_fn",
"graph_type",
],
)
def _compute_qudit_loss_for_bandwidth( # pylint: disable=too-many-arguments
bandwidth: float,
obs_key: jnp.ndarray,
eval_key: jnp.ndarray,
params: jnp.ndarray,
target_data: jnp.ndarray,
n_ops: int,
n_qudits: int,
dims: tuple[int, ...],
wire_tuple: tuple[int, ...],
sqrt_loss: bool,
expval_fn: Callable,
graph_type: str,
expval_kwargs: dict,
) -> jnp.ndarray:
"""Estimate one unbiased MMD loss value for a single bandwidth setting."""
l_obs = _sample_fourier_indices(
obs_key, n_ops, n_qudits, dims, bandwidth, graph_type, wire_tuple
)
m_obs = jnp.zeros_like(l_obs)
model_output = expval_fn(
params,
observables=(l_obs, m_obs),
key=eval_key,
**expval_kwargs,
)
mu_q_hat, cov = model_output if isinstance(model_output, tuple) else (model_output, None)
mu_q_hat = jnp.asarray(mu_q_hat).astype(_COMPLEX_DTYPE)
if cov is not None:
cov = jnp.asarray(cov).astype(_REAL_DTYPE)
if mu_q_hat.shape != (n_ops,):
raise ValueError(
f"expval_fn returned moments of shape {mu_q_hat.shape}, expected ({n_ops},)"
)
if cov is not None and cov.shape != (n_ops, 2, 2):
raise ValueError(
f"expval_fn returned covariances of shape {cov.shape}, expected ({n_ops}, 2, 2)"
)
l_visible = l_obs[:, list(wire_tuple)]
dims_visible = tuple(int(dims[w]) for w in wire_tuple)
return _unbiased_mmd_squared(mu_q_hat, cov, target_data, l_visible, dims_visible, sqrt_loss)
[docs]
def build_mmd_loss_hw(
expval_fn: Callable,
dims: int | Sequence[int],
n_qudits: int,
mmd_config: QuditMMDConfig,
) -> Callable:
r"""Build a reusable loss function that computes the qudit graph-kernel MMD.
The returned callable measures the distance between a qudit model's output
distribution and an empirical target dataset of dit-strings using the
Maximum Mean Discrepancy (MMD) with a graph-based kernel. The model is
called as::
expval_fn(params, observables=(l_vecs, m_vecs), key=..., **expval_kwargs)
where ``(l_vecs, m_vecs)`` are integer arrays of shape ``(n_ops, n_qudits)``
identifying the Heisenberg-Weyl operators :math:`O(\mathbf{l}, \mathbf{m})`
to measure. Only :math:`\mathbf{m} = \mathbf{0}` is generated, so the
requested moments are the graph-Fourier moments of the output distribution.
It must return ``moments`` of shape ``(n_ops,)``, or ``(moments, cov)``
where ``cov[i]`` is the ``(2, 2)`` real/imaginary covariance matrix of the
estimator ``moments[i]``; returning ``moments`` alone declares the model
exact.
Args:
expval_fn (Callable): Heisenberg-Weyl expectation value function, as
above. Must be hashable and JAX-traceable.
dims (int | Sequence[int]): Local qudit dimension(s). Either a single
``int`` broadcast to every qudit, or a sequence of length
``n_qudits`` giving a distinct dimension :math:`d_j` per qudit.
n_qudits (int): Number of qudits the model acts on, i.e. the width of
the observable arrays passed to ``expval_fn``.
mmd_config (QuditMMDConfig): MMD hyperparameters including the
bandwidth, number of observables, and graph type. See
:class:`QuditMMDConfig`.
Returns:
Callable: A function with signature
``loss_fn(params, target_data, key=None, **expval_kwargs)`` that returns
either a scalar MMD² estimate (averaged across bandwidths) or a list of
per-bandwidth values when ``mmd_config.return_per_bandwidth=True``.
Raises:
ValueError: If ``mmd_config`` leaves ``bandwidth`` or ``n_ops`` unset,
if ``mmd_config.bandwidth`` is empty, if ``mmd_config.n_ops < 1``,
or if ``mmd_config.wires`` contains duplicates or indices outside
``[0, n_qudits)``.
**Example**
>>> import jax
>>> import jax.numpy as jnp
>>> from pennylane.labs.tcdq import (
... QuditCircuitConfig, QuditMMDConfig, build_qudit_expval_func, build_mmd_loss_hw,
... )
>>> circuit_config = QuditCircuitConfig(
... dims=3,
... n_qudits=2,
... gates={0: [{0: 1}], 1: [{1: 1}]},
... n_samples=512,
... key=jax.random.PRNGKey(0),
... )
>>> mmd_config = QuditMMDConfig(bandwidth=[0.3, 1.0], n_ops=32)
>>> loss_fn = build_mmd_loss_hw(
... build_qudit_expval_func(circuit_config), 3, 2, mmd_config
... )
>>> params = jnp.array([0.2, -0.1])
>>> target_data = jnp.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=jnp.int32)
>>> loss = loss_fn(params, target_data, key=jax.random.PRNGKey(123))
>>> loss.shape
()
.. seealso::
:func:`~pennylane.labs.tcdq.build_qudit_expval_func`,
`Section IV B of Spectral Born machines: classically trainable quantum generative models for discrete data <https://arxiv.org/abs/2607.06675>`_.
"""
if mmd_config.bandwidth is None or mmd_config.n_ops is None:
raise ValueError("mmd_config must specify both bandwidth and n_ops")
if mmd_config.n_ops < 1:
raise ValueError("n_ops must be at least 1")
dims_tuple = tuple(int(x) for x in _dims_to_numpy(dims, n_qudits))
wire_tuple = tuple(range(n_qudits)) if mmd_config.wires is None else tuple(mmd_config.wires)
for w in wire_tuple:
if w < 0 or w >= n_qudits:
raise ValueError(f"Wire index {w} out of range for {n_qudits} qudits")
if len(set(wire_tuple)) != len(wire_tuple):
raise ValueError("wires must not contain duplicates")
bandwidth_list = (
[mmd_config.bandwidth]
if isinstance(mmd_config.bandwidth, (int, float))
else list(mmd_config.bandwidth)
)
if len(bandwidth_list) == 0:
raise ValueError("bandwidth must not be empty")
def loss_fn(
params: ArrayLike,
target_data: ArrayLike,
key: ArrayLike | None = None,
**expval_kwargs,
) -> jnp.ndarray | list[jnp.ndarray]:
"""Estimate the empirical qudit MMD loss for one parameter setting.
The input ``target_data`` is interpreted as samples from the empirical
data distribution on the visible wires. For each requested bandwidth,
this function samples a fresh batch of Heisenberg-Weyl observables,
estimates their moments with ``expval_fn``, computes the matching
empirical moments from ``target_data``, and returns the resulting
unbiased MMD estimate.
If multiple bandwidths are configured, each bandwidth gets its own
independent observable batch and model-evaluation randomness.
Args:
params: Trainable model parameters, passed to ``expval_fn`` as its
first argument.
target_data: Integer array of shape ``(m, n_visible)`` whose rows
are empirical samples on the visible wires.
key: Optional JAX PRNG key seeding this call. It is split once per
bandwidth into one key for observable sampling and one that is
forwarded to ``expval_fn``. If ``None``, uses
``jax.random.PRNGKey(0)``.
**expval_kwargs: Extra keyword arguments forwarded to ``expval_fn``.
Returns:
Either a scalar mean across bandwidths or a list of per-bandwidth
loss values when ``return_per_bandwidth`` is enabled.
Raises:
ValueError: If ``target_data`` is not 2-D, has fewer than two rows
or an unexpected number of columns, if ``expval_kwargs``
contains ``"observables"``, or if ``expval_fn`` returns arrays
of the wrong shape.
"""
if "observables" in expval_kwargs:
raise ValueError(
"expval_kwargs must not contain 'observables': the loss samples the observables "
"and passes them to expval_fn itself"
)
active_key = jax.random.PRNGKey(0) if key is None else key
X_data = jnp.asarray(target_data).astype(_INDEX_DTYPE)
if X_data.ndim != 2:
raise ValueError(f"target_data must be 2-D, got shape {X_data.shape}")
n_visible = len(wire_tuple)
if X_data.shape[1] != n_visible:
raise ValueError(
f"target_data has {X_data.shape[1]} columns but expected "
f"{n_visible} (number of visible wires)"
)
if X_data.shape[0] < 2:
raise ValueError(f"target_data must have at least 2 samples, got {X_data.shape[0]}")
losses: list[jnp.ndarray] = []
for bandwidth in bandwidth_list:
active_key, obs_key, eval_key = jax.random.split(active_key, 3)
loss_val = _compute_qudit_loss_for_bandwidth(
bandwidth=bandwidth,
obs_key=obs_key,
eval_key=eval_key,
params=params,
target_data=X_data,
n_ops=mmd_config.n_ops,
n_qudits=n_qudits,
dims=dims_tuple,
wire_tuple=wire_tuple,
sqrt_loss=mmd_config.sqrt_loss,
expval_fn=expval_fn,
graph_type=mmd_config.graph_type,
expval_kwargs=expval_kwargs,
)
losses.append(loss_val)
if mmd_config.return_per_bandwidth:
return losses
return jnp.mean(jnp.stack(losses))
return loss_fn