Source code for pennylane.labs.tcdq.qudit_expval_functions

# 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.
"""Expectation-value estimator for qudit IQP circuits.

This module extends :mod:`~pennylane.labs.tcdq.expval_functions` from qubits
to qudits. It estimates Heisenberg-Weyl moments without building the full
quantum state.

The estimator samples random dit-strings, evaluates an observable-dependent
phase, evaluates a circuit-dependent phase difference, and averages the
resulting complex integrand.

For further information, see
`Section 2, Classically Estimating Expectation Values <https://github.com/PennyLaneAI/pennylane/blob/port_tcdq_docs_pr/pennylane/labs/tcdq/notes.md#2-classically-estimating-expectation-values>`_,
`Section 3, General Input States <https://github.com/PennyLaneAI/pennylane/blob/port_tcdq_docs_pr/pennylane/labs/tcdq/notes.md#3-general-input-states>`_,
and `Section 4, Monte Carlo Statistics <https://github.com/PennyLaneAI/pennylane/blob/port_tcdq_docs_pr/pennylane/labs/tcdq/notes.md#4-monte-carlo-statistics>`_
of the technical notes.
"""

import itertools
import math
from collections.abc import Callable, Sequence
from dataclasses import dataclass
from functools import partial
from typing import NamedTuple

import jax
import jax.numpy as jnp
import numpy as np
from jax.typing import ArrayLike

_REAL_DTYPE = jnp.float32
_COMPLEX_DTYPE = jnp.complex64
_INDEX_DTYPE = jnp.int32


[docs] @dataclass class QuditCircuitConfig: # pylint: disable=too-many-instance-attributes r"""A class to store qudit IQP circuit configurations. This class stores the description of a qudit IQP circuit to compute its expectation value with respect to a Heisenberg-Weyl (HW) observable. See `arXiv:2607.06675 <https://arxiv.org/abs/2607.06675>`_ for theoretical details. A qudit IQP circuit is in the form :math:`U(\mathbf{\theta}) = \left( F^{\otimes n} \right)^\dagger D(\mathbf{\theta}) F^{\otimes n}` where :math:`F` is the Fourier transform and :math:`D(\mathbf{\theta})` is a diagonal phase unitary on `n` qudits. The diagonal phase unitary is given by a gate set :math:`\mathcal{G}`, .. math:: D(\mathbf{\theta}) = \prod_{\mathbf{g} \in \mathcal{G}} \exp \left( i \theta_\mathbf{g} \mathcal{Q}_\mathbf{g} \right) where :math:`\mathbf{\theta}_\mathbf{g}` is a vector parameterizing the gate :math:`\mathbf{g}` and :math:`\mathcal{Q}_\mathbf{g}` is the Hermitian counterpart to an HW observable. Optionally, one can specify an additional trainable phase layer :math:`D'(\mathbf{\xi})\vert z \rangle = \exp \left( i f_{\mathbf{\xi}}(z) \right) \vert z \rangle` where :math:`f_{\mathbf{\xi}}(z)` is a trainable function parameterized by :math:`\mathbf{\xi}`. After including the phase layer, the final trainable circuit becomes :math:`\left( F^{\otimes n} \right)^\dagger D'(\mathbf{\xi}) D(\mathbf{\theta}) F^{\otimes n}`. This dataclass collects the circuit data needed by :func:`build_qudit_expval_func`. It is the qudit analogue of :class:`~pennylane.labs.tcdq.CircuitConfig`. Args: dims (int | Sequence[int]): Local qudit dimension(s). Either a single ``int`` (e.g., 2 for qubits, 3 for qutrits), which is 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 in the circuit. gates (dict[int, list[dict[int, int]]]): Circuit structure mapping each trainable-parameter index to a list of gates. Each gate is a sparse generator given as a ``dict`` mapping a qudit index to the power of :math:`Z` applied on that qudit; qudits that are not listed are acted on trivially. Powers are reduced modulo the local dimension :math:`d_j`, and entries that reduce to zero are dropped. For example, with ``dims=3`` and ``n_qudits=2``, ``{0: [{0: 1}], 1: [{1: 1}], 2: [{0: 1, 1: 1}]}`` defines three gates: :math:`Z^1` on qudit 0, :math:`Z^1` on qudit 1, and :math:`Z^1 \otimes Z^1` on both. n_samples (int): Number of random dit-strings drawn for the estimation. key (ArrayLike): JAX PRNG key for random dit-string generation. observables (tuple[ArrayLike, ArrayLike] | None): A pair ``(l_vecs, m_vecs)`` specifying the Heisenberg–Weyl displacement operators :math:`O(\mathbf{l}, \mathbf{m})` to measure. Each is an integer array of shape ``(n_obs, n_qudits)`` with entries in :math:`\{0, \ldots, d-1\}`. If ``None``, observables must be supplied at call time (e.g., when used inside :func:`~pennylane.labs.tcdq.build_qudit_mmd_loss`). init_state_elems (ArrayLike | None): Support of a custom initial state. Integer array of shape ``(N, n_qudits)`` with entries in :math:`\{0, \ldots, d-1\}`, where ``N`` is the number of non-zero amplitudes. Defaults to ``None`` (uniform superposition via QFT). init_state_amps (ArrayLike | None): Complex amplitudes of shape ``(N,)`` for the custom initial state. Must be provided together with ``init_state_elems``. phase_fn (Callable | None): Optional phase layer with trainable parameters. The phase layer :math:`D'(\mathbf{\xi})` is given by a ``Callable`` with signature ``(params: ArrayLike, z: ArrayLike) -> scalar`` where ``z`` is a dit-string of shape ``(n_qudits, )`` with entries in :math:`\{0, \dots, d-1\}` and ``params`` has shape matching :math:`\mathbf{\xi}`. max_memory (float | None): Upper bound, in gigabytes (1 GB = 1024**3 bytes), on the temporary memory used by the phase-difference computation. If ``None`` (default), memory is unbounded. **Example** >>> import jax >>> import jax.numpy as jnp >>> from pennylane.labs.tcdq import QuditCircuitConfig >>> config = QuditCircuitConfig( ... dims=3, ... n_qudits=4, ... gates={0: [{0: 1}], 1: [{1: 1}], 2: [{0: 1, 1: 1}]}, ... observables=( ... jnp.array([[1, 0, 0, 0], [0, 1, 0, 0]], dtype=jnp.int32), ... jnp.zeros((2, 4), dtype=jnp.int32), ... ), ... n_samples=5000, ... key=jax.random.PRNGKey(42), ... ) """ #: Local qudit dimension(s): an int (uniform) or list (per-qudit sequence). dims: int | Sequence[int] = None #: Number of qudits in the circuit. n_qudits: int = None #: Circuit structure mapping parameter indices to sparse gates ``{qudit: power}``. gates: dict[int, list[dict[int, int]]] = None #: Number of random dit-strings drawn for the estimation. n_samples: int = None #: JAX PRNG key for random dit-string generation. key: ArrayLike = None #: Heisenberg–Weyl observables ``(l_vecs, m_vecs)``, or ``None``. observables: tuple[ArrayLike, ArrayLike] | None = None #: Support of a custom initial state, or ``None``. init_state_elems: ArrayLike | None = None #: Amplitudes for the custom initial state, or ``None``. init_state_amps: ArrayLike | None = None #: Learnable phase layer phase_fn: Callable | None = None #: Memory budget in GB for the blocked phase-difference computation, or ``None`` for unbounded. max_memory: float | None = None
def _dims_to_numpy(dims: int | Sequence[int], n_qudits: int) -> np.ndarray: """Normalize the ``dims`` field to an integer array of per-qudit dimensions. Accepts either a scalar ``int`` (broadcast to all qudits, the uniform case) or a sequence of length ``n_qudits`` (mixed-dimension case), and always returns a NumPy integer array of shape ``(n_qudits,)``. Raises: ValueError: If ``dims`` is a sequence whose length is not ``n_qudits``. """ if isinstance(dims, int): return np.full((n_qudits,), int(dims), dtype=int) normalized_dims = np.asarray(dims, dtype=int) if normalized_dims.shape != (n_qudits,): raise ValueError( f"d given as a sequence must have length n_qudits={n_qudits}, " f"got shape {normalized_dims.shape}." ) return normalized_dims class SparseGateGroup(NamedTuple): """Gates of equal weight :math:`\\omega` stored in sparse ``(support, power)`` form. Args: omega (int): Number of active qudits shared by every gate in the group. supports (np.ndarray): Active qudit indices, shape ``(n_gates, omega)``, sorted in increasing order along the last axis. powers (np.ndarray): Power of :math:`Z` at each support position, shape ``(n_gates, omega)``, with entries in ``{1, ..., d_j - 1}``. param_indices (jnp.ndarray): Index into ``gates_params`` for each gate, shape ``(n_gates,)``. """ #: Number of active qudits per gate in this group. omega: int #: Active qudit indices, shape ``(n_gates, omega)``. supports: np.ndarray #: Power of :math:`Z` at each support position, shape ``(n_gates, omega)``. powers: np.ndarray #: Parameter index of each gate, shape ``(n_gates,)``. param_indices: jnp.ndarray def _normalize_sparse_gate( gate: dict[int, int], n_qudits: int, dims: np.ndarray ) -> tuple[np.ndarray, np.ndarray]: """Validate one sparse gate and return its sorted ``(support, powers)`` arrays. Raises: TypeError: If ``gate`` is not a ``dict`` (e.g. a dense length-``n_qudits`` vector). IndexError: If a qudit index is outside ``[-n_qudits, n_qudits)``. """ if not isinstance(gate, dict): raise TypeError( "Each qudit gate must be a dict mapping qudit index to Z power, e.g. {0: 1, 2: 2}; " ) support: list[int] = [] powers: list[int] = [] for qudit, power in gate.items(): q = int(qudit) if q >= n_qudits or q < 0: raise IndexError(f"Qudit index {q} out of range for a {n_qudits}-qudit circuit.") # q = q % n_qudits p = int(power) % int(dims[q]) if p == 0: continue support.append(q) powers.append(p) order = np.argsort(support, kind="stable") return np.asarray(support, dtype=int)[order], np.asarray(powers, dtype=int)[order] def _parse_qudit_gate_dict( circuit_def: dict[int, list[dict[int, int]]], n_qudits: int, dims: ArrayLike ) -> list[SparseGateGroup]: """Convert a sparse qudit gate dictionary into weight-grouped support/power arrays. Args: circuit_def (dict[int, list[dict[int, int]]]): Maps parameter indices to lists of sparse gates ``{qudit_index: z_power}``. n_qudits (int): Number of qudits. dims (ArrayLike): Per-qudit dimensions, shape ``(n_qudits,)``. Returns: list[SparseGateGroup]: One group per distinct non-zero weight, sorted by weight. Raises: TypeError: If a gate is not a ``dict``. IndexError: If a qudit index is out of range. """ dims = np.asarray(dims, dtype=int) buckets: dict[int, tuple[list[np.ndarray], list[np.ndarray], list[int]]] = {} for param_idx in sorted(circuit_def.keys()): if not isinstance(param_idx, int): raise TypeError(f"Qudit indices must be type int, got type {type(param_idx)} instead.") if param_idx < 0: raise ValueError( f"Qudit indices must be non-negative integers, got index {param_idx} instead." ) for gate in circuit_def[param_idx]: support, powers = _normalize_sparse_gate(gate, n_qudits, dims) omega = support.size if omega == 0: continue sup_list, pow_list, pidx_list = buckets.setdefault(omega, ([], [], [])) sup_list.append(support) pow_list.append(powers) pidx_list.append(int(param_idx)) return [ SparseGateGroup( omega=omega, supports=np.stack(sup_list), powers=np.stack(pow_list), param_indices=jnp.array(pidx_list, dtype=_INDEX_DTYPE), ) for omega, (sup_list, pow_list, pidx_list) in sorted(buckets.items()) ] def _compute_qudit_samples( key: ArrayLike, num_samples: int, n_qudits: int, dims: ArrayLike ) -> jnp.ndarray: """Generates uniformly random dit-strings from the product Z_{d_1} x ... x Z_{d_n}.""" maxval = jnp.asarray(dims, dtype=_INDEX_DTYPE)[jnp.newaxis, :] # (1, n_qudits) samples = jax.random.randint(key, shape=(num_samples, n_qudits), minval=0, maxval=maxval) return samples.astype(_INDEX_DTYPE) _BYTES_PER_GB = 1024**3 _FLOAT_BYTES = 4 def _memory_budget_bytes(max_memory: float | None) -> int | None: """Convert a ``max_memory`` budget in GB to an integer number of bytes.""" if max_memory is None: return None if ( isinstance(max_memory, bool) or not isinstance(max_memory, (int, float, np.integer, np.floating)) or not math.isfinite(max_memory) or max_memory <= 0 ): raise ValueError( "QuditCircuitConfig.max_memory must be None or a positive, finite number of " f"gigabytes, got {max_memory!r}." ) return int(max_memory * _BYTES_PER_GB) def _qudit_phase_bytes_per_gate(omega: int, n_samples: int, n_obs: int) -> int: """Approximate temporary bytes needed per gate of weight ``omega`` inside one block.""" per_column = _FLOAT_BYTES * (3 * omega + 2**omega) return per_column * (n_samples + n_obs) def _qudit_phase_block_size(max_memory_bytes: int, omega: int, n_samples: int, n_obs: int) -> int: """Number of weight-``omega`` gates per block that fits within ``max_memory_bytes``.""" return max(1, max_memory_bytes // _qudit_phase_bytes_per_gate(omega, n_samples, n_obs)) def _obs_phase_matrix( samples: jnp.ndarray, m_f: jnp.ndarray, l_f: jnp.ndarray, dims: ArrayLike ) -> jnp.ndarray: """Compute the observable phase matrix. :math:`J[i, j] = \\exp(i\\pi \\sum_k m_{ik} (2 z_{jk} - l_{ik}) / d_k)`. """ s_f = samples.astype(_REAL_DTYPE) inv_d = (1.0 / jnp.asarray(dims, dtype=_REAL_DTYPE))[jnp.newaxis, :] # (1, n_qudits) m_scaled = m_f * inv_d # (n_obs, n_qudits) return jnp.exp( 1j * jnp.pi * (2 * m_scaled @ s_f.T - jnp.sum(m_scaled * l_f, axis=1, keepdims=True)) ).astype(_COMPLEX_DTYPE) class _PrecomputedObsData(NamedTuple): """Bundled precomputed observable data from the factory.""" l_vecs: jnp.ndarray n_obs: int l_f: jnp.ndarray m_f: jnp.ndarray obs_phase_matrix: jnp.ndarray # pylint: disable=too-many-arguments def _group_block_contribution( theta_ext: jnp.ndarray, samples_t: jnp.ndarray, l_t: jnp.ndarray, dims_f: jnp.ndarray, supports: jnp.ndarray, powers: jnp.ndarray, param_indices: jnp.ndarray, ) -> jnp.ndarray: """Phase-difference contribution of one block of equal-weight gates. Args: theta_ext (jnp.ndarray): Gate parameters with a trailing zero appended, shape ``(n_params + 1,)``. Padded gates index the trailing zero and contribute nothing. samples_t (jnp.ndarray): Transposed samples, shape ``(n_qudits, n_samples)``, float. l_t (jnp.ndarray): Transposed observable ``l`` vectors, shape ``(n_qudits, n_obs)``, float. dims_f (jnp.ndarray): Per-qudit dimensions, shape ``(n_qudits,)``, float. supports (jnp.ndarray): Active qudit indices of the block, shape ``(block, omega)``. powers (jnp.ndarray): :math:`Z` powers of the block, shape ``(block, omega)``. param_indices (jnp.ndarray): Parameter index of each gate, shape ``(block,)``. Returns: jnp.ndarray: Accumulated phase differences, shape ``(n_obs, n_samples)``. """ omega = supports.shape[1] theta = theta_ext[param_indices] # (block,) g = powers.astype(_REAL_DTYPE)[:, :, jnp.newaxis] # (block, omega, 1) d_s = dims_f[supports][:, :, jnp.newaxis] # (block, omega, 1) z_at_support = jnp.take(samples_t, supports, axis=0) # (block, omega, n_samples) l_at_support = jnp.take(l_t, supports, axis=0) # (block, omega, n_obs) angle_z = 2 * jnp.pi * g * z_at_support / d_s + jnp.pi / 4 angle_l = 2 * jnp.pi * g * l_at_support / d_s state_factors = (jnp.sqrt(2.0) * jnp.cos(angle_z), jnp.sqrt(2.0) * jnp.sin(angle_z)) obs_factors = (jnp.cos(angle_l), jnp.sin(angle_l)) accumulated = None for sigma in itertools.product([0, 1], repeat=omega): B_sigma = state_factors[sigma[0]][:, 0, :] C_sigma = obs_factors[sigma[0]][:, 0, :] for k in range(1, omega): B_sigma = B_sigma * state_factors[sigma[k]][:, k, :] C_sigma = C_sigma * obs_factors[sigma[k]][:, k, :] if accumulated is None: # sigma == (0, ..., 0): B_sigma is the unshifted phi_g(z) accumulated = (theta @ B_sigma)[jnp.newaxis, :] accumulated = accumulated - (C_sigma.T * theta) @ B_sigma return accumulated @partial(jax.jit, static_argnames=("block_size",)) def _group_phase_diffs( theta_ext: jnp.ndarray, samples_t: jnp.ndarray, l_t: jnp.ndarray, dims_f: jnp.ndarray, group: SparseGateGroup, block_size: int, ) -> jnp.ndarray: """Phase differences of one weight group, processed in memory-bounded blocks.""" n_gates, omega = group.supports.shape supports = jnp.asarray(group.supports, dtype=_INDEX_DTYPE) powers = jnp.asarray(group.powers, dtype=_INDEX_DTYPE) param_indices = jnp.asarray(group.param_indices, dtype=_INDEX_DTYPE) block_fn = jax.checkpoint( lambda s, p, i: _group_block_contribution(theta_ext, samples_t, l_t, dims_f, s, p, i) ) if n_gates <= block_size: return block_fn(supports, powers, param_indices) n_blocks = -(-n_gates // block_size) n_pad = n_blocks * block_size - n_gates if n_pad: pad_index = theta_ext.shape[0] - 1 # points at the appended zero parameter supports = jnp.concatenate([supports, jnp.zeros((n_pad, omega), supports.dtype)]) powers = jnp.concatenate([powers, jnp.ones((n_pad, omega), powers.dtype)]) param_indices = jnp.concatenate( [param_indices, jnp.full((n_pad,), pad_index, param_indices.dtype)] ) def accumulate(total, block): return total + block_fn(*block), None zero = jnp.zeros((l_t.shape[1], samples_t.shape[1]), dtype=_REAL_DTYPE) total, _ = jax.lax.scan( accumulate, zero, ( supports.reshape(n_blocks, block_size, omega), powers.reshape(n_blocks, block_size, omega), param_indices.reshape(n_blocks, block_size), ), ) return total # pylint: disable=too-many-arguments def _accumulate_phase_diffs( gates_params: ArrayLike, gate_groups: list[SparseGateGroup], samples: jnp.ndarray, l_vecs: jnp.ndarray, dims: ArrayLike, max_memory_bytes: int | None, vmapped_phase_func: Callable | None, phase_fn_params: ArrayLike | None, ) -> jnp.ndarray: """Assemble the accumulated phase-difference matrix from all weight groups.""" n_samples = samples.shape[0] n_obs = l_vecs.shape[0] theta = jnp.asarray(gates_params).astype(_REAL_DTYPE) theta_ext = jnp.concatenate([theta, jnp.zeros((1,), dtype=_REAL_DTYPE)]) samples_t = samples.astype(_REAL_DTYPE).T # (n_qudits, n_samples) l_t = jnp.asarray(l_vecs).astype(_REAL_DTYPE).T # (n_qudits, n_obs) dims_f = jnp.asarray(dims, dtype=_REAL_DTYPE) accumulated = jnp.zeros((n_obs, n_samples), dtype=_REAL_DTYPE) for group in gate_groups: if max_memory_bytes is None: accumulated = accumulated + _group_block_contribution( theta_ext, samples_t, l_t, dims_f, jnp.asarray(group.supports, dtype=_INDEX_DTYPE), jnp.asarray(group.powers, dtype=_INDEX_DTYPE), jnp.asarray(group.param_indices, dtype=_INDEX_DTYPE), ) else: block_size = _qudit_phase_block_size(max_memory_bytes, group.omega, n_samples, n_obs) accumulated = accumulated + _group_phase_diffs( theta_ext, samples_t, l_t, dims_f, group, block_size ) if vmapped_phase_func is not None: accumulated += vmapped_phase_func(phase_fn_params, samples, l_vecs).astype(_REAL_DTYPE) return accumulated def _compute_initial_state_correction( samples: jnp.ndarray, l_f: jnp.ndarray, state_elems: ArrayLike, state_amps: ArrayLike, dims: ArrayLike, ) -> jnp.ndarray: """Compute the correction factor for a non-standard initial state.""" s_f = samples.astype(_REAL_DTYPE) X_state = jnp.asarray(state_elems).astype(_REAL_DTYPE) # (N, n) Psi = jnp.asarray(state_amps).astype(_COMPLEX_DTYPE) # (N,) inv_d = (1.0 / jnp.asarray(dims, dtype=_REAL_DTYPE))[jnp.newaxis, :] # (1, n) # ω^{Z·X^T} where ω_j = exp(2πi/d_j) — shape (s, N) omega_ZX = jnp.exp(2j * jnp.pi * ((s_f * inv_d) @ X_state.T)).astype(_COMPLEX_DTYPE) # Ψ̃^(2) = ω^{Z·X^T} · Ψ — shape (s,) psi_tilde_2 = omega_ZX @ Psi # F = Ψ* · 1_{1×s} ⊙ ω^{-X·Z^T} — shape (N, s) F_mat = Psi.conj()[:, jnp.newaxis] * omega_ZX.conj().T # Ψ̃^(1) = ω^{L·X^T} · F — shape (l, s) omega_LX = jnp.exp(2j * jnp.pi * ((l_f * inv_d) @ X_state.T)).astype(_COMPLEX_DTYPE) # (l, N) psi_tilde_1 = omega_LX @ F_mat # H = Ψ̃^(1) ⊙ (1_{l×1} · (Ψ̃^(2))^T) — shape (l, s) return psi_tilde_1 * psi_tilde_2[jnp.newaxis, :] def _compute_mc_statistics( integrand: jnp.ndarray, n_samples: int ) -> tuple[jnp.ndarray, jnp.ndarray]: """Compute the Monte Carlo mean and covariance from the integrand. Returns ``(expvals, cov)`` where ``cov`` is the per-observable covariance matrix of the mean estimator, shape ``(n_obs, 2, 2)``. """ expvals = jnp.mean(integrand, axis=1) re = jnp.real(integrand) im = jnp.imag(integrand) re_centered = re - jnp.mean(re, axis=1, keepdims=True) im_centered = im - jnp.mean(im, axis=1, keepdims=True) var_re = jnp.sum(re_centered**2, axis=1) / (n_samples - 1) / n_samples var_im = jnp.sum(im_centered**2, axis=1) / (n_samples - 1) / n_samples cov_re_im = jnp.sum(re_centered * im_centered, axis=1) / (n_samples - 1) / n_samples cov = jnp.stack( [ jnp.stack([var_re, cov_re_im], axis=-1), jnp.stack([cov_re_im, var_im], axis=-1), ], axis=-2, ) # (n_obs, 2, 2) return expvals, cov
[docs] def build_qudit_expval_func( # pylint: disable=too-many-statements config: QuditCircuitConfig, ) -> Callable: """Build an estimator for expectation values of a qudit IQP circuit. Returns a pure function that estimates the complex expectation value :math:`\\langle O(\\mathbf{l}, \\mathbf{m}) \\rangle` for each observable by averaging over randomly sampled dit-strings. The returned function captures precomputed data from ``config`` (generator matrices, default samples, preprocessed observables) so that repeated evaluations with different parameters are fast. Args: config (QuditCircuitConfig): Full circuit description including gate structure, observables, and sampling parameters. See :class:`QuditCircuitConfig` for details on how to construct one. Returns: Callable: A function with signature:: expval_fn( gates_params, phase_fn_params=None, key=None, n_samples=None, observables=None, init_state_elems=None, init_state_amps=None, ) -> (expvals, cov) where ``expvals`` is a complex array of shape ``(n_obs,)`` containing the estimated moments, and ``cov`` has shape ``(n_obs, 2, 2)`` providing the real/imaginary covariance matrix of the mean estimator for each observable. When ``config.phase_fn`` is set, the returned callable requires ``phase_fn_params`` to be passed as the second argument (the trainable parameters of the phase layer). Raises: ValueError: If no observables are provided either in ``config`` or at call time. **Example** >>> import jax >>> import jax.numpy as jnp >>> from pennylane.labs.tcdq import QuditCircuitConfig, build_qudit_expval_func >>> config = QuditCircuitConfig( ... dims=3, ... n_qudits=2, ... gates={0: [{0: 1}], 1: [{1: 1}]}, ... n_samples=512, ... key=jax.random.PRNGKey(0), ... observables=( ... jnp.array([[1, 0], [0, 1]], dtype=jnp.int32), ... jnp.zeros((2, 2), dtype=jnp.int32), ... ), ... ) >>> expval_fn = build_qudit_expval_func(config) >>> params = jnp.array([0.2, -0.1]) >>> expvals, cov = expval_fn(params) >>> expvals.shape, cov.shape ((2,), (2, 2, 2)) .. seealso:: `Spectral Born machines: classically trainable quantum generative models for discrete data <https://arxiv.org/pdf/2607.06675>`_. """ n = config.n_qudits dims = _dims_to_numpy(config.dims, n) gate_groups = _parse_qudit_gate_dict(config.gates, n, dims) max_memory_bytes = _memory_budget_bytes(config.max_memory) default_samples = _compute_qudit_samples(config.key, config.n_samples, n, dims) vmapped_phase_func = None if config.phase_fn is not None: dims_j = jnp.asarray(dims) def compute_phase_diff(p_params, sample, l_vec): return config.phase_fn(p_params, sample) - config.phase_fn( p_params, (sample - l_vec) % dims_j ) vmapped_phase_func = jax.vmap( jax.vmap(compute_phase_diff, in_axes=(None, 0, None)), in_axes=(None, None, 0), ) if config.observables is not None: l_vecs = jnp.array(config.observables[0], dtype=_INDEX_DTYPE) m_vecs = jnp.array(config.observables[1], dtype=_INDEX_DTYPE) l_f = l_vecs.astype(_REAL_DTYPE) m_f = m_vecs.astype(_REAL_DTYPE) n_obs = l_vecs.shape[0] defaults = _PrecomputedObsData( l_vecs=l_vecs, n_obs=n_obs, l_f=l_f, m_f=m_f, obs_phase_matrix=_obs_phase_matrix(default_samples, m_f, l_f, dims), ) else: defaults = None def qudit_expval_batched( gates_params: ArrayLike, phase_fn_params: ArrayLike | None = None, key: ArrayLike | None = None, n_samples: int | None = None, observables: tuple[ArrayLike, ArrayLike] | None = None, init_state_elems: ArrayLike | None = None, init_state_amps: ArrayLike | None = None, ) -> tuple[jnp.ndarray, jnp.ndarray]: # pylint: disable=too-many-arguments """Compute batched expectation values for the configured circuit. Args: gates_params (ArrayLike): 1-D array of gate parameters. phase_fn_params (ArrayLike | None, optional): Trainable parameters for the custom phase function. Defaults to ``None``. key (ArrayLike | None, optional): Runtime override for the JAX PRNG key used for sampling. Defaults to None. n_samples (int | None, optional): Runtime override for the number of samples. Defaults to None. observables (tuple[ArrayLike, ArrayLike] | None, optional): Runtime override for the displacement-operator observables ``(l_vecs, m_vecs)``. Defaults to None. init_state_elems (ArrayLike | None, optional): Runtime override for the support elements of the initial state. Array of shape ``(N, n_qudits)`` with integer entries in ``{0, ..., d-1}``. Defaults to None. init_state_amps (ArrayLike | None, optional): Runtime override for the complex amplitudes of the initial state. Array of shape ``(N,)``. Defaults to None. Returns: tuple[jnp.ndarray, jnp.ndarray]: Returns ``(expvals, cov)`` where ``expvals`` are the estimated complex expectation values, shape ``(n_obs,)``, and ``cov`` stores the real-imaginary covariance matrices of the mean estimator, shape ``(n_obs, 2, 2)``. """ if observables is not None: l_vecs = jnp.array(observables[0], dtype=_INDEX_DTYPE) l_f = l_vecs.astype(_REAL_DTYPE) m_f = jnp.array(observables[1], dtype=_INDEX_DTYPE).astype(_REAL_DTYPE) elif defaults is not None: l_vecs, l_f, m_f = defaults.l_vecs, defaults.l_f, defaults.m_f else: raise ValueError( "No observables specified. Provide them in QuditCircuitConfig " "or pass at call time via the observables argument." ) if key is not None or n_samples is not None: _key = key if key is not None else config.key _n = n_samples if n_samples is not None else config.n_samples samples = _compute_qudit_samples(_key, _n, n, dims) else: _n = config.n_samples samples = default_samples use_cached = ( key is None and n_samples is None and observables is None and defaults is not None ) if use_cached: obs_pm = defaults.obs_phase_matrix else: obs_pm = _obs_phase_matrix(samples, m_f, l_f, dims) accumulated_phase_diffs = _accumulate_phase_diffs( gates_params, gate_groups, samples, l_vecs, dims, max_memory_bytes, vmapped_phase_func, phase_fn_params, ) state_elems = config.init_state_elems if init_state_elems is None else init_state_elems state_amps = config.init_state_amps if init_state_amps is None else init_state_amps integrand = obs_pm * jnp.exp(1j * accumulated_phase_diffs).astype(_COMPLEX_DTYPE) if state_elems is not None and state_amps is not None: H = _compute_initial_state_correction(samples, l_f, state_elems, state_amps, dims) integrand = integrand * H return _compute_mc_statistics(integrand, _n) return qudit_expval_batched