# 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.
"""Contains the template for the tensor hypercontraction ``SELECT`` oracle."""
from collections import Counter
from functools import partial
from math import pi
import numpy as np
from pennylane import capture, math
from pennylane.core.operator import Operator2, abstractify
from pennylane.decomposition import add_decomps, register_resources
from pennylane.ops import (
CNOT,
SWAP,
Hadamard,
S,
X,
Z,
adjoint,
change_op_basis,
ctrl,
)
from pennylane.typing import Wire
from pennylane.wires import Wires, WiresLike, validate_no_wire_overlaps
from .arithmetic.semi_adder import SemiAdder
from .multix import MultiX
from .qrom import QROM
def _validate_select_data(chi, t_eigenvectors):
"""Validate the static THC leaf and one-body eigenvector matrices."""
shapes = {}
arrays = {}
for name, matrix in (("chi", chi), ("t_eigenvectors", t_eigenvectors)):
if (
not isinstance(matrix, tuple)
or not matrix
or not all(isinstance(row, tuple) for row in matrix)
):
raise ValueError(
f"{name} must be a tuple of tuples of floats; got {type(matrix).__name__}."
)
num_columns = len(matrix[0])
if num_columns == 0 or any(len(row) != num_columns for row in matrix):
raise ValueError(f"{name} must be a non-empty rectangular matrix.")
arr = np.asarray(matrix)
if (
not np.issubdtype(arr.dtype, np.number)
or not np.isrealobj(arr)
or not np.all(np.isfinite(arr))
):
raise ValueError(f"{name} entries must be finite real numbers.")
shapes[name] = (len(matrix), num_columns)
arrays[name] = arr
M, n_half = shapes["chi"]
if shapes["t_eigenvectors"] != (n_half, n_half):
raise ValueError(
f"t_eigenvectors must have shape ({n_half}, {n_half}); got {shapes['t_eigenvectors']}."
)
if np.any(np.sum(arrays["chi"] ** 2, axis=1) < 1e-30):
raise ValueError("Cannot build a rotation from a zero vector in chi.")
if np.any(np.sum(arrays["t_eigenvectors"] ** 2, axis=0) < 1e-30):
raise ValueError("Cannot build a rotation from a zero vector in t_eigenvectors.")
return M, n_half
def _cascade_angles(leaf):
r"""Givens angles :math:`\theta_p` mapping ``leaf`` onto :math:`\lvert e_0 \rangle`.
Zeroes the vector from its last coordinate inwards, so row ``0`` of the resulting
:math:`U` is the normalized ``leaf`` and :math:`U^\dagger Z_1 U` is the reflection about
it. Only :math:`N/2 - 1` angles are needed rather than a full :math:`\mathcal{O}(N^2)`
Givens network, because that sandwich depends on :math:`U` only through row ``0``.
Args:
leaf (tuple[float]): the vector to rotate, shape ``(N/2,)``. Its norm is irrelevant;
the angles are scale invariant.
Returns:
the ``N/2 - 1`` angles, where entry ``p`` belongs to the pair
``(p, p + 1)``. Empty for a single orbital.
Raises:
ValueError: if ``leaf`` is the zero vector.
"""
vec = math.reshape(math.asarray(leaf, dtype=float), -1)
if math.shape(vec)[0] <= 1:
return math.zeros(0)
if math.norm(vec) < 1e-15:
raise ValueError("Cannot build a rotation from a zero vector.")
# Each step of the cascade replaces vec[p] by the norm of the suffix it has just
# zeroed, so the angles have a closed form. Only the last coordinate keeps its sign,
# which is what puts the final angle in (-pi, 0] when leaf[-1] is negative.
suffix = math.sqrt(math.cumsum(vec[::-1] ** 2)[::-1])
suffix = math.concatenate([suffix[:-1], vec[-1:]])
return math.arctan2(suffix[1:], vec[:-1])
def _angle_batches(n_half, num_batches):
r"""Split the Givens pairs into contiguous batches, in application order.
Args:
n_half (int): the number of spatial orbitals, ``N/2``
num_batches (int): the number of batches to split the ``N/2 - 1`` pairs into
Returns:
tuple[list[list[int]], int]: the pairs of each batch, followed by the width of the
widest batch. Pair ``p`` acts on the spatial orbitals ``(p, p + 1)`` and the ladder
runs from ``N/2 - 2`` down to ``0``. Only the last batch may be short, so the width
sizes the angle register and the number of batches returned can be smaller than
``num_batches``.
"""
pairs = list(reversed(range(max(n_half - 1, 0))))
width = max(-(-len(pairs) // num_batches), 1)
return [pairs[i : i + width] for i in range(0, len(pairs), width)], width
def _build_qrom_givens_data(chi, t_eigenvectors, beth, one_body_table, batches):
r"""Build the incremental ``QROM`` tables of quantized Givens angles.
Each row holds the ``beth``-bit angles that rotate one leaf onto
:math:`\lvert e_0 \rangle`, one field per pair in the batch; addresses not backed by a
leaf are all-zero and load the identity. Since ``QROM(clean=True)`` writes with an
XOR, table :math:`b` is stored as its difference with table :math:`b - 1`, which carries
the angle register from one batch to the next instead of erasing and reloading it. The
first table is absolute, so re-loading it clears the register.
Args:
chi (tuple[tuple[float]]): the THC leaf matrix, shape ``(M, N/2)``, addressed by the index
register.
t_eigenvectors (tuple[tuple[float]]): the one-body eigenvectors as columns, shape
``(N/2, N/2)``. Ignored when ``one_body_table=False``.
beth (int): bits of precision per Givens angle.
one_body_table (bool): if ``True``, the address is extended by the one-body flag and
the eigenvectors are loaded above the ``chi`` rows.
batches (Sequence[Sequence[int]]): the Givens pairs of each batch, in application
order, as returned by ``_angle_batches``.
Returns:
list[list[list[int]]]: one ``QROM`` table per batch, empty when there are no pairs
to rotate.
"""
chi = math.asarray(chi, dtype=float)
M, n_half = chi.shape
if not batches:
return []
block = 1 << math.ceil_log2(max(M, n_half))
addresses = list(range(M))
leaves = list(chi)
if one_body_table:
addresses += [block + ell for ell in range(n_half)]
t_eig = math.asarray(t_eigenvectors, dtype=float)
leaves += list(math.transpose(t_eig))
# The quantized angles are the last point where this is array math: ``QROM`` takes
# classical bitstrings, so the grid indices are pulled out as Python ints here and the
# tables below are built with plain integer arithmetic.
levels = 1 << beth
thetas = math.stack([_cascade_angles(leaf) for leaf in leaves])
grid = math.floor(-math.mod(2.0 * thetas, 4.0 * pi) / (4.0 * pi) * levels)
grid = [[int(value) % levels for value in row] for row in grid]
# Only the last batch can be short, so the first sets the width of the angle register
# and the rest fill a prefix. The table stops at the last address backed by a leaf:
# `QROM`` pads the rest with the identity, so cost falls with the number of rows but
# it also scales with ``2 ** len(control_wires)``, so both are kept as tight as possible.
n_rows = block + n_half if one_body_table else M
width = len(batches[0]) * beth
leaf_of = dict(zip(addresses, range(len(leaves))))
def _row(address, batch):
if address not in leaf_of:
return [0] * width
angles = grid[leaf_of[address]]
bits = [(angles[p] >> (beth - 1 - j)) & 1 for p in batch for j in range(beth)]
return bits + [0] * (width - len(bits))
tables = [[_row(address, batch) for address in range(n_rows)] for batch in batches]
return [tables[0]] + [
[[cur ^ prev for cur, prev in zip(row, previous)] for row, previous in zip(table, before)]
for table, before in zip(tables[1:], tables[:-1])
]
def _apply_loaded_rotation(
psi_down, angle_wires, beth, pairs, gradient_wires, work_wires
): # pylint: disable=too-many-arguments, too-many-positional-arguments
r"""Apply the rotations of one batch, whose angles are held in ``angle_wires``.
This is the phase-gradient compilation of Section III.C of `Lee et al. (2021)
<https://arxiv.org/abs/2011.03494>`_. Applying this to the Givens rotation, we write it as
.. math::
\mathrm{SE}(\theta) = \left(H_0\,\mathrm{CNOT}_{01}\right)^\dagger
\left[R_y(-\theta/2)_0 \otimes R_y(-\theta/2)_1\right]
\left(H_0\,\mathrm{CNOT}_{01}\right) ,
\qquad R_y(\alpha) = S H R_z(\alpha) H S^\dagger ,
both :math:`R_y` carry the same angle, so each becomes one addition of the
same loaded value under a fixed Clifford: two additions per Givens pair, and no
arbitrary-angle rotation anywhere. The control is moved onto the loaded bits by a ``CNOT`` layer,
so no controlled adder is needed.
Args:
psi_down (Sequence[int]): the ``N/2`` spatial orbitals :math:`U` acts on
angle_wires (Sequence[int]): the loaded angle register, ``beth`` bits per pair
beth (int): bits of precision per Givens angle
pairs (Sequence[int]): the Givens pairs of this batch, in application order
gradient_wires (Sequence[int]): the ``beth + 1`` wires of the phase gradient register
work_wires (Sequence[int]): at least ``beth`` zeroed wires. The first ``beth`` are the
scratch of :class:`~.SemiAdder`.
"""
adder_work = work_wires[:beth]
for slot, p in enumerate(pairs):
bits = angle_wires[slot * beth : (slot + 1) * beth]
add = adjoint(SemiAdder)
lower, upper = psi_down[p], psi_down[p + 1]
Hadamard(lower)
CNOT(wires=[lower, upper])
for wire in (lower, upper):
adjoint(S)(wire)
Hadamard(wire)
ctrl(MultiX([1] * len(bits), wires=bits), control=wire)
add(bits, gradient_wires, adder_work)
ctrl(MultiX([1] * len(bits), wires=bits), control=wire)
Z(wire)
Hadamard(wire)
S(wire)
CNOT(wires=[lower, upper])
Hadamard(lower)
[docs]
def select_thc_wires(M, N, beth, num_batches=1):
r"""Return the wire counts required by :class:`~.SelectTHC`.
Args:
M (int): the THC rank.
N (int): the number of spin orbitals.
beth (int): bits of precision per Givens angle. The realised grid is the odd
multiples of :math:`\pi / 2^{\mathrm{beth}}`, so the spacing is
:math:`2\pi / 2^{\mathrm{beth}}`.
num_batches (int): the number of batches the Givens angles are loaded in. The
default of ``1`` loads all of them at once. See the note below.
Returns:
dict: ``{"system_wires": n_system, "index_wires": n_index,
"flag_wires": n_flag, "gradient_wires": n_gradient, "work_wires": n_work}``.
* ``system_wires`` (``N``): the spin orbitals, the ``N/2`` spin-down spatial
orbitals followed by the ``N/2`` spin-up ones.
* ``index_wires`` (``2 * ceil(log2(M + 1))``): :math:`\mu` followed by
:math:`\nu`, as produced by ``PREPARE``. The ``+ 1`` inside the logarithm
leaves room for the one-body sentinel value :math:`\nu = M`.
* ``flag_wires`` (``5``): the success flag, the one-body sentinel flag (:math:`\nu = M`),
the qubit that controls the :math:`\mu \leftrightarrow \nu` swap,
and the two spin flags.
* ``gradient_wires`` (``beth + 1``): the phase gradient register. See the note below.
* ``work_wires`` (``ceil((N/2 - 1) / num_batches) * beth +
max(ceil(log2(M + 1)), beth)``): the minimum clean scratch, returned to
:math:`\lvert 0 \rangle`. Zero when ``N/2 == 1``, where the sandwich is a lone
:math:`Z_1` and no angles are loaded.
Raises:
ValueError: if ``M``, ``N``, ``beth`` or ``num_batches`` is not a positive
integer, if ``N`` is odd, or if the one-body block does not fit the index
register.
.. note::
Only ``work_wires`` is a minimum; the other four are exact and must be matched.
Extra work wires are forwarded to the internal :class:`~.QROM`, which splits them
between the unary iteration of its ``Select`` and the ``SelectSwap`` space-time
trade-off. Which split it picks depends on ``M``, ``N`` and ``beth``, so extra
wires do not necessarily lower the gate count.
.. note::
``gradient_wires`` must be prepared by the caller in the phase gradient state
.. math::
\lvert \phi \rangle = \frac{1}{\sqrt{2^{\mathrm{beth}+1}}}
\sum_{k=0}^{2^{\mathrm{beth}+1} - 1}
e^{-2 \pi i k / 2^{\mathrm{beth}+1}} \lvert k \rangle ,
which can be done with :class:`~.PhaseGradientStatePrep`.
The ``SELECT`` oracle leaves it unchanged, so it is
deliberately not allocated internally: one register is prepared once and shared by
``PREPARE`` and ``SELECT``.
**Example**
>>> import pennylane as qp
>>> qp.select_thc_wires(M=3, N=4, beth=4)
{'system_wires': 4, 'index_wires': 4, 'flag_wires': 5, 'gradient_wires': 5, 'work_wires': 8}
"""
for name, value in (("M", M), ("N", N), ("beth", beth), ("num_batches", num_batches)):
if isinstance(value, bool) or not isinstance(value, int) or value < 1:
raise ValueError(f"{name} must be a positive integer, got {value!r}.")
if N % 2:
raise ValueError(f"N must be an even number of spin orbitals; got {N}.")
n = math.ceil_log2(M + 1)
n_half = N // 2
if n_half > 2**n:
raise ValueError(
f"The one-body rotations do not fit the index register: N // 2 = {n_half} "
f"exceeds 2 ** ceil(log2(M + 1)) = {2**n} for M = {M}."
)
batches, width = _angle_batches(n_half, num_batches)
n_angle = width * beth if batches else 0
return {
"system_wires": N,
"index_wires": 2 * n,
"flag_wires": 5,
"gradient_wires": beth + 1,
"work_wires": n_angle + max(n, beth) if n_angle else 0,
}
def _select_half(
chi,
t_eigenvectors,
beth,
system_wires,
index_wires,
flag_wires,
gradient_wires,
work_wires,
num_batches=1,
one_body_table=False,
skip_one_body=False,
): # pylint: disable=too-many-arguments, too-many-positional-arguments
r"""Apply one :math:`V = U^\dagger Z_1 U` sandwich of the THC ``SELECT`` oracle.
This is the kernel of Fig. 5 of `Lee et al. (2021)
<https://arxiv.org/abs/2011.03494>`_. It is emitted as a single
:func:`~.change_op_basis` so that a control placed on this sandwich falls only on the
:math:`Z_1` reflection.
Args:
chi (tuple[tuple[float]]): the THC leaf matrix, shape ``(M, N/2)``
t_eigenvectors (tuple[tuple[float]]): the one-body eigenvectors as columns, shape
``(N/2, N/2)``. Required when ``one_body_table=True``, ignored otherwise.
beth (int): bits of precision per Givens angle
system_wires (Sequence[int]): the ``N`` spin orbitals
index_wires (Sequence[int]): the ``ceil(log2(M + 1))`` wires of the THC index
addressing the rotation table
flag_wires (Sequence[int]): three wires, the success flag, the one-body
flag and the spin flag
gradient_wires (Sequence[int]): the ``beth + 1`` wires holding the phase gradient state.
This is assumed to be prepared on entry and left unchanged, as it is reused between
``PREPARE`` and ``SELECT`` oracles.
work_wires (Sequence[int]): clean scratch, returned to :math:`\lvert 0 \rangle`
num_batches (int): the number of batches the Givens angles are loaded in. The
default of ``1`` loads all of them at once; larger values shrink
``work_wires`` at the cost of more ``QROM`` loads.
one_body_table (bool): flag to check if the ``QROM`` address is extended by the
one-body flag and the one-body rotations are loaded
skip_one_body (bool): if ``False``, the :math:`Z_1` reflection is controlled on the
success flag alone, as in the first sandwich of Fig. 5. If ``True``, it carries
a second control, the open circle on the :math:`\lvert \nu = M \rangle`
wire of the second sandwich in Fig. 5, so the reflection is switched off on the
one-body block and this half acts as the identity there.
Raises:
ValueError: if a register has the wrong size, or if ``t_eigenvectors`` has the
wrong shape when ``one_body_table=True``.
"""
chi = math.asarray(chi, dtype=float)
M, n_half = chi.shape
n = math.ceil_log2(M + 1)
req = select_thc_wires(M, 2 * n_half, beth, num_batches)
batches, width = _angle_batches(n_half, num_batches)
n_angle = width * beth if batches else 0
if len(system_wires) != 2 * n_half:
raise ValueError(f"system_wires must have {2 * n_half} entries; got {len(system_wires)}.")
if len(index_wires) != n:
raise ValueError(f"index_wires must have {n} entries for M={M}; got {len(index_wires)}.")
if len(flag_wires) != 3:
raise ValueError(f"flag_wires must have 3 entries; got {len(flag_wires)}.")
if len(gradient_wires) != beth + 1:
raise ValueError(
f"gradient_wires must have beth + 1 = {beth + 1} entries; got {len(gradient_wires)}."
)
if len(work_wires) < req["work_wires"]:
raise ValueError(
f"work_wires must have at least {req['work_wires']} entries for M={M}, "
f"N/2={n_half}, beth={beth}; got {len(work_wires)}."
)
if one_body_table and math.shape(t_eigenvectors) != (n_half, n_half):
raise ValueError(
f"t_eigenvectors must have shape ({n_half}, {n_half}); "
f"got {math.shape(t_eigenvectors)}."
)
psi_down, psi_up = list(system_wires[:n_half]), list(system_wires[n_half:])
succ, edge, spin = flag_wires
angle_wires = list(work_wires[:n_angle])
# The QROM restores its work wires before the adder runs, so the two share the pool.
# ``angle_wires`` holds the loaded angles while the sandwich is open, so ``qrom_work`` is
# the only part of the pool that is zeroed for the ops between the two QROM calls.
qrom_work = list(work_wires[n_angle:])
swap_work = list(work_wires)
gradient_wires = list(gradient_wires)
tables = _build_qrom_givens_data(chi, t_eigenvectors, beth, one_body_table, batches)
# The index register is sized by PREPARE, which needs the ``nu = M`` sentinel, but this
# QROM only addresses ``mu < M`` or ``ell < N/2``, so its top wire is always in |0>.
n_mu = math.ceil_log2(max(M, n_half))
qrom = {
"control_wires": ([edge] if one_body_table else []) + list(index_wires)[n - n_mu :],
"target_wires": angle_wires,
"work_wires": qrom_work,
"clean": True,
}
z_control, z_values = ([succ, edge], [1, 0]) if skip_one_body else ([succ], [1])
def _basis():
# Route V onto the spin-up block when the spin flag is set, then apply U,
# one batch of angles at a time.
for down, up in zip(psi_down, psi_up):
ctrl(
SWAP(wires=[down, up]),
control=spin,
work_wires=swap_work,
work_wire_type="zeroed",
)
for b, batch in enumerate(batches):
QROM(tables[b], **qrom)
_apply_loaded_rotation(psi_down, angle_wires, beth, batch, gradient_wires, qrom_work)
def _reflect():
# Reflect on the first orbital, switched off on the one-body block.
ctrl(
Z(psi_down[0]),
control=z_control,
control_values=z_values,
work_wires=qrom_work,
work_wire_type="zeroed",
)
def _unbasis():
adjoint(_basis)()
return change_op_basis(_basis, _reflect, _unbasis)
def _index_swaps(
mu_wires, nu_wires, edge, spin1, spin2, work_wires
): # pylint: disable=too-many-arguments, too-many-positional-arguments
r"""Exchange the two index registers and the two spin flags off the one-body block.
The swaps are conditioned on :math:`\nu \neq M`, so they are emitted as a
:func:`~.change_op_basis` around an ``X`` on ``edge``: a control placed on this block then
falls only on the swaps, not on the two bit flips.
Args:
mu_wires (Sequence[int]): the wires of the first THC index
nu_wires (Sequence[int]): the wires of the second THC index
edge (int): the one-body sentinel flag
spin1 (int): the spin flag of the first sandwich
spin2 (int): the spin flag of the second sandwich
work_wires (Sequence[int]): zeroed scratch for the controlled swaps
"""
def _swaps():
for a, b in zip(mu_wires, nu_wires, strict=True):
ctrl(
SWAP(wires=[a, b]),
control=edge,
work_wires=work_wires,
work_wire_type="zeroed",
)
ctrl(
SWAP(wires=[spin1, spin2]),
control=edge,
work_wires=work_wires,
work_wire_type="zeroed",
)
return change_op_basis(partial(X, wires=edge), _swaps)
[docs]
class SelectTHC(Operator2):
r"""Self-inverse Hamiltonian selection oracle for tensor hypercontraction (THC).
Implements the ``SELECT`` of Fig. 5 of `Lee et al. (2021)
<https://arxiv.org/abs/2011.03494>`_, with the self-inverse fix of its Eqs. (36)-(42)
and Fig. 7. On the subspace flagged by the success wire this applies
.. math::
\lvert \mu \rangle \lvert \nu \rangle \lvert \psi \rangle \;\longmapsto\;
\lvert \nu \rangle \lvert \mu \rangle \,
V_\nu^{\beta} V_\mu^{\alpha} \lvert \psi \rangle ,
\qquad V_\mu = U_\mu^\dagger Z_1 U_\mu = I - 2 c_\mu^\dagger c_\mu ,
reducing to the one-body :math:`V_{T, \ell}^{\sigma}` when the one-body sentinel flag
is set.
The Hermitian operator that the walk operator block-encodes is given by:
.. math::
\langle P \rvert \mathrm{SELECT} \lvert P \rangle = \tfrac{1}{2}
\left( V_\mu^{\alpha} V_\nu^{\beta} + V_\nu^{\alpha} V_\mu^{\beta} \right) ,
up to the sign :math:`(-1)^{s_{\mu\nu}}` of the sampled coefficient, which ``PREPARE``
applies as a controlled phase on its sign qubit.
Use :func:`~.select_thc_wires` for the register sizes.
Args:
chi (tuple[tuple[float]]): the THC leaf matrix of shape ``(M, N/2)``, provided as
a nested tuple. Each row is assumed normalized; only its direction enters the
circuit, so any row norm must already be absorbed into :math:`\zeta_{\mu\nu}`
in ``PREPARE``.
t_eigenvectors (tuple[tuple[float]]): eigenvectors of the modified one-body matrix
:math:`T'` as columns, shape ``(N/2, N/2)``, provided as a nested tuple
beth (int): bits of precision per Givens angle
system_wires (Sequence[int]): the ``N`` spin orbitals
index_wires (Sequence[int]): ``2 * ceil(log2(M + 1))`` wires, :math:`\mu`
followed by :math:`\nu`, as left by ``PREPARE``.
flag_wires (Sequence[int]): this includes five wires, in order the success flag, the
one-body flag (:math:`\nu = M`), the qubit that controls the :math:`\mu \leftrightarrow
\nu` swap, and the two spin flags. All five are assumed to be prepared by
``PREPARE``.
gradient_wires (Sequence[int]): the ``beth + 1`` wires holding the phase gradient state.
This is assumed to be prepared on entry and left unchanged, as it is reused between
``PREPARE`` and ``SELECT`` oracles.
work_wires (Sequence[int]): clean scratch, returned to :math:`\lvert 0 \rangle`
num_batches (int): the number of batches the Givens angles are loaded in. The
default of ``1`` loads all of them at once; larger values shrink
``work_wires`` at the cost of more ``QROM`` loads.
Raises:
ValueError: if two registers share a wire, or if a register has the wrong size
ValueError: if ``chi`` or ``t_eigenvectors`` is not a nested tuple of finite,
real numbers
ValueError: if ``t_eigenvectors`` does not have shape ``(N/2, N/2)``
ValueError: if ``beth`` or ``num_batches`` is not a positive integer
ValueError: if the one-body rotations do not fit the index register, that is if
``N/2 > 2 ** ceil(log2(M + 1))``
ValueError: if a row of ``chi`` or a column of ``t_eigenvectors`` is the zero
vector, which has no rotation onto :math:`\lvert e_0 \rangle`
**Example**
.. code-block:: python
import numpy as np
import pennylane as qp
M, N, beth = 3, 4, 3
rng = np.random.default_rng(0)
chi = tuple(map(tuple, rng.standard_normal((M, N // 2))))
t_eigenvectors = tuple(
map(tuple, np.linalg.qr(rng.standard_normal((N // 2, N // 2)))[0])
)
sizes = qp.select_thc_wires(M, N, beth)
wires = qp.registers(sizes)
n_total = sum(sizes.values())
@qp.qnode(qp.device("default.qubit", wires=n_total))
def circuit():
qp.X(wires["flag_wires"][0]) # success flag
for w in wires["flag_wires"][3:]: # the two spin flags
qp.Hadamard(w)
qp.PhaseGradientStatePrep(wires["gradient_wires"])
qp.SelectTHC(
chi, t_eigenvectors, beth, wires["system_wires"], wires["index_wires"],
wires["flag_wires"], wires["gradient_wires"], wires["work_wires"],
)
return qp.probs(wires=wires["system_wires"])
.. details::
:title: Available decompositions
.. decomposition-table:: qp.SelectTHC
:stacked:
:symbols: :math:`N` spin orbitals, :math:`M` is the THC rank, :math:`h = N/2` spatial orbitals, :math:`P = h - 1` Givens pairs loaded in
:math:`B` batches (:math:`B \leq` ``num_batches``, and :math:`B = 0` if
:math:`P = 0`), and :math:`n = \lceil \log_2(M+1) \rceil` wires per index
:example: :math:`M=1`, :math:`N=4` (:math:`h=2`, :math:`P=1`, :math:`B=1`, :math:`n=1`)
.. decomposition-rule:: _select_thc_decomp
:image: /_static/decomposition_thumbnails/select_thc_double_factorized.svg
:lightbox:
:class:`~.QROM` | :math:`2B` | 2
:class:`Adjoint(QROM) <.QROM>` | :math:`2B` | 2
:class:`~.CSWAP` | :math:`4h + n + 1` | 10
:class:`~.Hadamard` | :math:`24P` | 24
:class:`~.CNOT` | :math:`8P` | 8
:class:`~.S` | :math:`8P` | 8
:class:`Adjoint(S) <.S>` | :math:`8P` | 8
:class:`~.Z` | :math:`8P` | 8
:class:`~.MultiX` with 1 control | :math:`16P` | 16
:class:`~.SemiAdder` | :math:`4P` | 4
:class:`Adjoint(SemiAdder) <.SemiAdder>` | :math:`4P` | 4
:class:`~.CZ` with 1 control | :math:`1` | 1
:class:`~.CZ` with 2 controls | :math:`1` | 1
:class:`~.X` | :math:`3` | 3
"""
wire_argnames = (
"system_wires",
"index_wires",
"flag_wires",
"gradient_wires",
"work_wires",
)
compilable_argnames = ("chi", "t_eigenvectors", "beth", "num_batches")
arg_specs = {
"system_wires": Wire[-1],
"index_wires": Wire[-1],
"flag_wires": Wire[5],
"gradient_wires": Wire[-1],
"work_wires": Wire[-1],
}
def __init__(
self,
chi,
t_eigenvectors,
beth,
system_wires: WiresLike,
index_wires: WiresLike,
flag_wires: WiresLike,
gradient_wires: WiresLike,
work_wires: WiresLike,
num_batches=1,
): # pylint: disable=too-many-arguments,too-many-positional-arguments
M, n_half = _validate_select_data(chi, t_eigenvectors)
requirements = select_thc_wires(M, 2 * n_half, beth, num_batches)
registers = {
"system_wires": Wires(system_wires),
"index_wires": Wires(index_wires),
"flag_wires": Wires(flag_wires),
"gradient_wires": Wires(gradient_wires),
"work_wires": Wires(work_wires),
}
for name in ("system_wires", "index_wires", "flag_wires", "gradient_wires"):
if len(registers[name]) != requirements[name]:
raise ValueError(
f"{name} must have {requirements[name]} entries; got {len(registers[name])}."
)
if len(registers["work_wires"]) < requirements["work_wires"]:
raise ValueError(
f"work_wires must have at least {requirements['work_wires']} entries; "
f"got {len(registers['work_wires'])}."
)
validate_no_wire_overlaps(registers)
super().__init__(
chi,
t_eigenvectors,
beth,
*registers.values(),
num_batches,
)
@property
def wires(self):
"""All wires involved in the operation."""
return (
self.system_wires
+ self.index_wires
+ self.flag_wires
+ self.gradient_wires
+ self.work_wires
)
def _select_thc_resources(
chi,
t_eigenvectors,
beth,
system_wires,
index_wires,
flag_wires,
gradient_wires,
work_wires,
num_batches=1,
): # pylint: disable=too-many-arguments,too-many-positional-arguments
"""Return the top-level resources of the SelectTHC decomposition."""
sizes = [
len(system_wires),
len(index_wires),
len(flag_wires),
len(gradient_wires),
len(work_wires),
]
offsets = np.cumsum([0] + sizes)
concrete_wires = [
range(int(start), int(stop)) for start, stop in zip(offsets[:-1], offsets[1:])
]
system, index, flags, gradient, work = concrete_wires
n = math.ceil_log2(len(chi) + 1)
mu_wires = list(index[:n])
nu_wires = list(index[n:])
succ, edge, _, spin1, spin2 = flags
# `_select_half` returns change_op_basis. Under capture that unrolls eagerly
# (binds inner gates into the jaxpr and returns None), so pause while we
# build the resource keys. compute_resources already stops queuing but does
# not pause capture. See #10162.
with capture.pause():
first_half = _select_half(
chi,
t_eigenvectors,
beth,
system,
mu_wires,
[succ, edge, spin1],
gradient,
work,
num_batches=num_batches,
one_body_table=True,
)
second_half = _select_half(
chi,
t_eigenvectors,
beth,
system,
nu_wires,
[succ, edge, spin2],
gradient,
work,
num_batches=num_batches,
skip_one_body=True,
)
swaps = _index_swaps(mu_wires, nu_wires, edge, spin1, spin2, work)
resources = Counter(abstractify(op) for op in (first_half, second_half, swaps))
resources[X] += 1
return resources
@register_resources(_select_thc_resources)
def _select_thc_decomp(
chi,
t_eigenvectors,
beth,
system_wires,
index_wires,
flag_wires,
gradient_wires,
work_wires,
num_batches=1,
**_,
): # pylint: disable=too-many-arguments,too-many-positional-arguments
M = len(chi)
n = math.ceil_log2(M + 1)
mu_wires = index_wires[:n]
nu_wires = index_wires[n : 2 * n]
succ, edge, swap, spin1, spin2 = flag_wires
# 1. V on mu in the first spin sector, the only sandwich acting on the one-body block.
_select_half(
chi,
t_eigenvectors,
beth,
system_wires,
mu_wires,
[succ, edge, spin1],
gradient_wires,
work_wires,
num_batches=num_batches,
one_body_table=True,
)
# 2. V on nu in the other spin sector, switched off on the one-body block.
_select_half(
chi,
t_eigenvectors,
beth,
system_wires,
nu_wires,
[succ, edge, spin2],
gradient_wires,
work_wires,
num_batches=num_batches,
skip_one_body=True,
)
# 3. Exchange the two indices and the two spin flags, and flip the qubit that
# controls the mu <-> nu swap. This is the "X on the ancilla qubit and swapping the mu and nu
# registers" step between Eqs. (38) and (39) of arXiv:2011.03494, and it is what makes
# SELECT self-inverse.
_index_swaps(mu_wires, nu_wires, edge, spin1, spin2, work_wires)
X(swap)
add_decomps(SelectTHC, _select_thc_decomp)