# 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 qubit IQP circuits.
This module estimates Pauli expectation values for IQP circuits without
simulating the full quantum state.
"""
import math
from collections.abc import Callable
from dataclasses import dataclass
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
_PHASE_BYTES_PER_GATE_SAMPLE = 16
_PHASE_BYTES_PER_GATE_OBSERVABLE = 4
_BYTES_PER_GB = 1024**3
[docs]
@dataclass
class CircuitConfig: # pylint: disable=too-many-instance-attributes
"""Description of a qubit IQP circuit for classical expectation-value estimation.
This dataclass bundles all the information needed to build an expectation-value
estimator via :func:`build_expval_func`: the gate structure, the observables to
measure, sampling parameters, and an optional non-standard initial state.
Args:
gates (dict[int, list[list[int]]]): Circuit structure mapping each
trainable parameter index to a list of gates. Each gate is itself a
list of qubit indices that participate in a Pauli-Z tensor-product
generator. For example, ``{0: [[0, 1]], 1: [[2]]}`` defines two
parameters: parameter 0 drives a ZZ gate on qubits 0 and 1, and
parameter 1 drives a Z gate on qubit 2. Use
:func:`~pennylane.labs.tcdq.create_local_gates` or
:func:`~pennylane.labs.tcdq.create_lattice_gates` to generate
these automatically.
n_samples (int): Number of random bitstrings drawn for the
estimation.
key (ArrayLike): JAX PRNG key for random bitstring generation.
n_qubits (int): Total number of qubits in the circuit.
observables (ArrayLike | None): Integer array of shape
``(n_observables, n_qubits)`` encoding Pauli operators (I=0, X=1,
Y=2, Z=3). Each row is one observable. If ``None``, observables must
be passed at call time to the function returned by
:func:`build_expval_func`.
init_state_elems (ArrayLike | None): Binary array of shape ``(N, n_qubits)``
listing the computational-basis states with non-zero amplitude in a
custom initial state. Use together with ``init_state_amps``. If
``None`` (default), the circuit starts in the uniform superposition
state :math:`H^{\\otimes n}|0\\rangle`.
init_state_amps (ArrayLike | None): Complex array of shape ``(N,)`` with
the amplitudes corresponding to ``init_state_elems``.
phase_fn (Callable | None): Optional custom phase function
``phase_fn(params, bitstring)`` applied as an extra diagonal layer.
Defaults to ``None``.
max_memory (float): Upper bound, in gigabytes (1 GB = 1024**3 bytes), on
the temporary memory used by the phase-difference computation. The gates are
processed in blocks whose size is derived from this budget together with the
number of samples and observables. Defaults to ``1.0``.
**Example**
>>> import jax
>>> from pennylane.labs.tcdq import CircuitConfig, create_local_gates
>>> gates = create_local_gates(n_qubits=4, max_weight=2)
>>> config = CircuitConfig(
... gates=gates,
... n_samples=2000,
... key=jax.random.PRNGKey(42),
... n_qubits=4,
... observables=[[3, 3, 0, 0], [0, 0, 3, 3]], # ZZ on (0,1) and ZZ on (2,3)
... )
.. seealso::
`IQPopt: Fast optimization of instantaneous quantum polynomial circuits in JAX <https://arxiv.org/abs/2501.04776>`_
"""
#: Circuit structure mapping parameter indices to lists of gates.
gates: dict[int, list[list[int]]] = None
#: Number of random bitstrings drawn for the estimation.
n_samples: int = None
#: JAX PRNG key for random bitstring generation.
key: ArrayLike = None
#: Total number of qubits in the circuit.
n_qubits: int = None
#: Pauli observables encoded as an integer array, or ``None``.
observables: ArrayLike | None = None
#: Computational-basis states with non-zero amplitude, or ``None``.
init_state_elems: ArrayLike | None = None
#: Amplitudes for the custom initial state, or ``None``.
init_state_amps: ArrayLike | None = None
#: Optional custom phase function applied as an extra diagonal layer.
phase_fn: Callable | None = None
#: Upper bound, in gigabytes, on the temporary memory used by the phase-difference computation.
max_memory: float = 1.0
def _parse_generator_dict(circuit_def: dict[int, list[list[int]]], n_qubits: int):
"""Convert a gate dictionary into a binary generator matrix and parameter map.
Args:
circuit_def (dict[int, list[list[int]]]): Dictionary mapping parameter indices to
lists of qubit indices.
n_qubits (int): Total number of qubits.
Returns:
tuple[jnp.ndarray, jnp.ndarray]: Tuple containing:
- Integer array of shape ``(n_gates, max_weight)`` of qubit indices, padded with ``n_qubits``.
- Integer array mapping each generator to its parameter index.
"""
flat_gates = []
param_indices = []
for param_idx in sorted(circuit_def.keys()):
gates_for_this_param = circuit_def[param_idx]
for gate in gates_for_this_param:
flat_gates.append(gate)
param_indices.append(param_idx)
n_gates = len(flat_gates)
lengths = {len(gate) for gate in flat_gates}
width = max(max(lengths, default=0), 1)
rows = np.full((n_gates, width), n_qubits)
for i, qubits in enumerate(flat_gates):
unique = np.asarray(qubits).reshape(-1)
unique = np.unique(np.where(unique < 0, unique + n_qubits, unique))
if unique.size and (unique.min() < 0 or unique.max() >= n_qubits):
raise IndexError(f"Qubit index out of range for a {n_qubits}-qubit circuit")
rows[i, : unique.size] = unique
gate_indices = jnp.asarray(np.ascontiguousarray(rows), dtype=_INDEX_DTYPE)
return gate_indices, jnp.array(param_indices, dtype=_INDEX_DTYPE)
def _xor_gather_rows(bits: jnp.ndarray, gate_indices: jnp.ndarray) -> jnp.ndarray:
parity = bits[gate_indices[:, 0]]
for slot in range(1, gate_indices.shape[1]):
parity = parity ^ bits[gate_indices[:, slot]]
return parity
def _pad_sentinel_row(bits: jnp.ndarray) -> jnp.ndarray:
return jnp.concatenate(
[bits.astype(jnp.uint8), jnp.zeros((1,) + bits.shape[1:], jnp.uint8)], axis=0
)
def _parity_dot(a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
a = jnp.asarray(a)
b = jnp.asarray(b)
dims = (((a.ndim - 1,), (b.ndim - 1,)), ((), ()))
product = jax.lax.dot_general(a, b, dims)
return product % 2
def _parity_signs(parity: jnp.ndarray) -> jnp.ndarray:
return 1 - 2 * parity.astype(_REAL_DTYPE)
def _memory_budget_bytes(max_memory: float) -> int:
"""Convert a ``max_memory`` budget to an integer number of bytes."""
return int(max_memory * _BYTES_PER_GB)
def _phase_block_size(max_memory_bytes: int, n_samples: int, n_observables: int) -> int:
"""Number of gates per block such that the phase computation stays within ``max_memory_bytes``."""
bytes_per_gate = (
_PHASE_BYTES_PER_GATE_SAMPLE * n_samples + _PHASE_BYTES_PER_GATE_OBSERVABLE * n_observables
)
return max(1, max_memory_bytes // bytes_per_gate)
# pylint: disable=too-many-arguments
def _phase_differences(
gate_params: jnp.ndarray,
samples_t: jnp.ndarray,
bitflips_t: jnp.ndarray,
gate_indices: jnp.ndarray,
param_map: jnp.ndarray,
block_size: int,
) -> jnp.ndarray:
n_gates, max_weight = gate_indices.shape
@jax.checkpoint
def block_contribution(block_indices: jnp.ndarray, block_params: jnp.ndarray) -> jnp.ndarray:
theta = gate_params[block_params][:, jnp.newaxis]
b_bits = _xor_gather_rows(samples_t, block_indices)
q_bits = _xor_gather_rows(bitflips_t, block_indices)
b_scaled = jnp.where(b_bits.astype(bool), -theta, theta)
return jax.lax.dot_general(q_bits, b_scaled, (((0,), (0,)), ((), ())))
if n_gates <= block_size:
return 2 * block_contribution(gate_indices, param_map)
n_blocks = -(-n_gates // block_size)
n_pad = n_blocks * block_size - n_gates
if n_pad:
sentinel = samples_t.shape[0] - 1
gate_indices = jnp.concatenate(
[gate_indices, jnp.full((n_pad, max_weight), sentinel, gate_indices.dtype)]
)
param_map = jnp.concatenate([param_map, jnp.zeros((n_pad,), param_map.dtype)])
def accumulate(total, block):
return total + block_contribution(*block), None
zero = jnp.zeros((bitflips_t.shape[1], samples_t.shape[1]), dtype=gate_params.dtype)
total, _ = jax.lax.scan(
accumulate,
zero,
(
gate_indices.reshape(n_blocks, block_size, max_weight),
param_map.reshape(n_blocks, block_size),
),
)
return 2 * total
def _compute_samples(key: ArrayLike, n_samples: int, n_qubits: int) -> jnp.ndarray:
"""Generate the random bitstrings used by the Monte Carlo estimator."""
n_bytes = (n_qubits + 7) // 8
random_bytes = jax.random.bits(key, shape=(n_samples, n_bytes), dtype=jnp.uint8)
unpacked_bits = jnp.unpackbits(random_bytes, axis=-1)
return unpacked_bits[:, :n_qubits]
def _prep_observables(observables_int: ArrayLike) -> tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]:
"""Precompute masks and phase factors for integer-encoded Pauli observables."""
obs_arr = jnp.asarray(observables_int, dtype=jnp.int32)
is_X = obs_arr == 1
is_Y = obs_arr == 2
is_Z = obs_arr == 3
bitflips = jnp.array(is_Z | is_Y, dtype=jnp.uint8)
mask_XY = jnp.array(is_X | is_Y, dtype=jnp.uint8)
count_Y = is_Y.sum(axis=1, dtype=jnp.int32) & 3
y_real = jnp.where(count_Y == 0, 1.0, jnp.where(count_Y == 2, -1.0, 0.0))
y_imag = jnp.where(count_Y == 1, -1.0, jnp.where(count_Y == 3, 1.0, 0.0))
y_real = y_real.astype(_REAL_DTYPE)[:, jnp.newaxis]
y_imag = y_imag.astype(_REAL_DTYPE)[:, jnp.newaxis]
return bitflips, mask_XY, y_real, y_imag
# pylint: disable=too-many-arguments
def _core_expval_execution(
gates_params: ArrayLike,
phase_fn_params: ArrayLike | None,
samples: jnp.ndarray,
obs_data: tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray],
init_state_elems: ArrayLike | None,
init_state_amps: ArrayLike | None,
gate_indices: jnp.ndarray,
param_map: jnp.ndarray,
vmapped_phase_func: Callable | None,
max_memory: float,
) -> tuple[jnp.ndarray, jnp.ndarray]:
"""Evaluate the Monte Carlo integrand and return expectation values and variances."""
bitflips, mask_XY, y_real, y_imag = obs_data
block_size = _phase_block_size(
_memory_budget_bytes(max_memory), samples.shape[0], bitflips.shape[0]
)
samples_t = _pad_sentinel_row(samples.T)
bitflips_t = _pad_sentinel_row(bitflips.T)
gates_params = jnp.asarray(gates_params)
gates_params = gates_params.astype(_REAL_DTYPE)
E = _phase_differences(gates_params, samples_t, bitflips_t, gate_indices, param_map, block_size)
if vmapped_phase_func is not None:
E = E + vmapped_phase_func(phase_fn_params, samples, bitflips).astype(_REAL_DTYPE)
cos_E = jnp.cos(E)
sin_E = jnp.sin(E)
sign_flip = _parity_signs(_parity_dot(mask_XY, samples))
phase_re = sign_flip * (y_real * cos_E - y_imag * sin_E)
phase_im = sign_flip * (y_real * sin_E + y_imag * cos_E)
if init_state_elems is None or init_state_amps is None:
integrand = phase_re
else:
state_elems = jnp.asarray(init_state_elems).astype(jnp.uint8)
amps = jnp.asarray(init_state_amps).astype(_COMPLEX_DTYPE)
g_signs = _parity_signs(_parity_dot(state_elems, samples))
w_signs = _parity_signs(_parity_dot(bitflips, state_elems))
amps_re = jnp.real(amps)
amps_im = jnp.imag(amps)
stacked = jnp.concatenate(
[amps_re[:, jnp.newaxis] * g_signs, amps_im[:, jnp.newaxis] * g_signs], axis=1
)
overlap = jax.lax.dot_general(w_signs, stacked, (((1,), (0,)), ((), ())))
n_samples = samples.shape[0]
overlap_re = overlap[:, :n_samples]
overlap_im = overlap[:, n_samples:]
col_re = amps_re @ g_signs
col_im = amps_im @ g_signs
h_re = overlap_re * col_re + overlap_im * col_im
h_im = overlap_re * col_im - overlap_im * col_re
integrand = phase_re * h_re - phase_im * h_im
expvals = jnp.mean(integrand, axis=1)
variances = jnp.var(integrand, axis=-1, ddof=1) / samples.shape[0]
return expvals, variances
[docs]
def build_expval_func(
config: CircuitConfig,
) -> Callable:
"""Build an estimator for Pauli expectation values of a qubit IQP circuit.
Returns a pure function that estimates the expectation value of each Pauli
observable specified in ``config.observables`` or passed at call time.
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 (CircuitConfig): Full circuit description including gate
structure, observables, and sampling parameters. See
:class:`CircuitConfig` for details on how to construct one.
Returns:
Callable: A function with signature::
expval_fn(
gates_params,
phase_fn_params=None,
observables=None,
key=None,
n_samples=None,
init_state_elems=None,
init_state_amps=None,
) -> (expvals, variances)
where ``expvals`` is a real array of shape ``(n_observables,)`` and
``variances`` contains the estimated variance of each expectation-value
estimator.
**Example**
>>> import jax
>>> import jax.numpy as jnp
>>> from pennylane.labs.tcdq import CircuitConfig, build_expval_func, create_local_gates
>>> n_qubits = 4
>>> gates = create_local_gates(n_qubits, max_weight=2)
>>> config = CircuitConfig(
... gates=gates,
... n_samples=5000,
... key=jax.random.PRNGKey(0),
... n_qubits=n_qubits,
... observables=[[3, 3, 0, 0], [0, 0, 3, 3]], # ZZ on (0,1) and (2,3)
... )
>>> expval_fn = jax.jit(build_expval_func(config))
>>> params = jnp.zeros(len(gates))
>>> expvals, variances = expval_fn(params)
>>> expvals.shape
(2,)
.. seealso::
:class:`~pennylane.labs.tcdq.CircuitConfig`,
`IQPopt: Fast optimization of instantaneous quantum polynomial circuits in JAX <https://arxiv.org/abs/2501.04776>`_
"""
max_memory = config.max_memory
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(
"CircuitConfig.max_memory must be a positive, finite number of gigabytes, "
f"got {max_memory!r}."
)
gate_indices, param_map = _parse_generator_dict(config.gates, config.n_qubits)
vmapped_phase_func = None
if config.phase_fn is not None:
def compute_phase(p_params, sample, b_flips):
return config.phase_fn(p_params, sample) - config.phase_fn(
p_params, (sample + b_flips) % 2
)
vmapped_phase_func = jax.vmap(
jax.vmap(compute_phase, in_axes=(None, 0, None)), in_axes=(None, None, 0)
)
default_samples = _compute_samples(config.key, config.n_samples, config.n_qubits)
default_obs_data = None if config.observables is None else _prep_observables(config.observables)
# pylint: disable=too-many-arguments
def expval_execution(
gates_params: ArrayLike,
phase_fn_params: ArrayLike | None = None,
observables: ArrayLike | None = None,
key: ArrayLike | None = None,
n_samples: int | None = None,
init_state_elems: ArrayLike | None = None,
init_state_amps: ArrayLike | None = None,
) -> tuple[jnp.ndarray, jnp.ndarray]:
"""Execute the estimator with optional runtime overrides.
This closure captures the precomputed matrices and defaults from the
CircuitConfig, while allowing dynamic injection of new parameters,
observables, or sampling configurations at execution time.
Args:
gates_params (ArrayLike): Trainable parameters $\\theta$ for the circuit gates.
phase_fn_params (ArrayLike | None, optional): Trainable parameters for the
custom phase function. Defaults to None.
observables (ArrayLike | None, optional): Runtime override for the Pauli
observables (I=0, X=1, Y=2, Z=3). 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.
init_state_elems (ArrayLike | None, optional): Runtime override for the
discrete elements of the initial state (X). Defaults to None.
init_state_amps (ArrayLike | None, optional): Runtime override for the
continuous amplitudes of the initial state (P). Defaults to None.
Returns:
tuple[jnp.ndarray, jnp.ndarray]: Estimated expectation values and
the estimated variances of those estimators.
"""
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_samples(_key, _n, config.n_qubits)
else:
samples = default_samples
if observables is not None:
obs_data = _prep_observables(observables)
elif default_obs_data is not None:
obs_data = default_obs_data
else:
raise ValueError(
"No observables specified. Provide them in CircuitConfig "
"or pass at call time via the observables argument."
)
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
return _core_expval_execution(
gates_params,
phase_fn_params,
samples,
obs_data,
state_elems,
state_amps,
gate_indices,
param_map,
vmapped_phase_func,
config.max_memory,
)
return expval_execution