# 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.
"""Base class for Vibronic Hamiltonian"""
from __future__ import annotations
from collections.abc import Sequence
from itertools import product
import numpy as np
from numpy.typing import ArrayLike
from pennylane.labs.trotter_error.realspace import (
RealspaceCoeffs,
RealspaceMatrix,
RealspaceOperator,
RealspaceSum,
)
from pennylane.labs.trotter_error.realspace.realspace_matrix import _next_pow_2
[docs]
def vibronic_fragments(
states: int,
modes: int,
freqs: ArrayLike,
taylor_coeffs: Sequence[ArrayLike],
scheme: str = "blocks",
) -> list[RealspaceMatrix]:
"""Returns a list of fragments summing to a vibronic Hamiltonian.
Two different fragmentation schemes
are available.
1. The ``blocks`` scheme is taken from Section III of `arXiv:2411.13669 <https://arxiv.org/abs/2411.13669>`_ and
groups the fragments by their electronic-block structure such that all potential terms sharing the same
electronic coupling pattern are grouped together into a single fragment.
2. The ``modes`` scheme constructs fragments based on the vibrational modes and operator types, then
merges the fragments that commute electronically.
Both fragmentation schemes additionally return a fragment containing the kinetic term.
Args:
states (int): the number of electronic states
modes (int): the number of vibrational modes
freqs (ndarray): the harmonic frequencies
taylor_coeffs (Sequence[ndarray]): a sequence containing the tensors of coefficients in the
Taylor expansion. The ith entry in the sequence corresponds to the ith degree Taylor coefficients
and has shape (states, states) + (modes)*i.
scheme (str): the fragmentation scheme to use. Valid options are ``blocks`` and ``modes``, defaults to ``blocks``.
Returns:
list[RealspaceMatrix]: a list of ``RealspaceMatrix`` objects representing the fragments of the vibronic Hamiltonian.
**Example**
>>> from pennylane.labs.trotter_error import vibronic_fragments
>>> import numpy as np
>>> n_modes = 4
>>> n_states = 2
>>> r_state = np.random.RandomState(42)
>>> freqs = r_state.random(4)
>>> taylor_coeffs = [r_state.random(size=(n_states, n_states, )), r_state.random(size=(n_states, n_states, n_modes))]
>>> fragments = vibronic_fragments(n_states, n_modes, freqs, taylor_coeffs)
>>> for fragment in fragments:
... print(fragment)
RealspaceMatrix({(0, 0): RealspaceSum((RealspaceOperator(4, (), 0.15601864044243652), RealspaceOperator(4, ('Q',), phi[1][0, 0][idx0]), RealspaceOperator(4, ('Q', 'Q'), omega[idx0,idx1]))), (1, 1): RealspaceSum((RealspaceOperator(4, (), 0.8661761457749352), RealspaceOperator(4, ('Q',), phi[1][1, 1][idx0]), RealspaceOperator(4, ('Q', 'Q'), omega[idx0,idx1])))})
RealspaceMatrix({(0, 1): RealspaceSum((RealspaceOperator(4, (), 0.15599452033620265), RealspaceOperator(4, ('Q',), phi[1][0, 1][idx0]))), (1, 0): RealspaceSum((RealspaceOperator(4, (), 0.05808361216819946), RealspaceOperator(4, ('Q',), phi[1][1, 0][idx0])))})
RealspaceMatrix({(0, 0): RealspaceSum((RealspaceOperator(4, ('P', 'P'), omega[idx0,idx1]),)), (1, 1): RealspaceSum((RealspaceOperator(4, ('P', 'P'), omega[idx0,idx1]),))})
"""
_validate_input(states, modes, freqs, taylor_coeffs)
match scheme:
case "blocks":
return _og_frags(states, modes, freqs, taylor_coeffs)
case "modes":
return _mode_frags(states, modes, freqs, taylor_coeffs)
case _:
raise ValueError(
f"Fragmentation scheme must be either 'blocks' or 'modes', got {scheme} instead."
)
def _og_frags(
states: int, modes: int, freqs: ArrayLike, taylor_coeffs: Sequence[ArrayLike]
) -> list[RealspaceMatrix]:
frags = [
_position_fragment(i, states, modes, freqs, taylor_coeffs)
for i in range(_next_pow_2(states))
]
frags.append(_momentum_fragment(states, modes, freqs))
return frags
def _position_fragment(
i: int, states: int, modes: int, freqs: ArrayLike, taylor_coeffs: Sequence[ArrayLike]
) -> RealspaceMatrix:
"""Return the ``i``th position fragment"""
blocks = {
(j, i ^ j): _realspace_sum(j, i ^ j, states, modes, freqs, taylor_coeffs)
for j in range(_next_pow_2(states))
}
return RealspaceMatrix(states, modes, blocks)
def _momentum_fragment(states: int, modes: int, freqs: ArrayLike) -> RealspaceMatrix:
"""Return the fragment consisting only of momentum operators."""
term = RealspaceOperator(
modes,
("P", "P"),
RealspaceCoeffs(np.diag(freqs) / 2, label="omega"),
)
word = RealspaceSum(modes, (term,))
blocks = {(i, i): word for i in range(states)}
return RealspaceMatrix(states, modes, blocks)
def _realspace_sum( # pylint: disable=too-many-arguments
i: int, j: int, states: int, modes: int, freqs: ArrayLike, taylor_coeffs: Sequence[ArrayLike]
) -> RealspaceSum:
"""Return a RealspaceSum representation of the ``(i, j)`` block in the RealspaceMatrix"""
if i > states - 1 or j > states - 1:
return RealspaceSum.zero(modes)
realspace_ops = []
for k, phi in enumerate(taylor_coeffs):
op = ("Q",) * k
realspace_op = RealspaceOperator(
modes,
op,
RealspaceCoeffs(phi[i, j], label=f"phi[{k}][{i}, {j}]"),
)
realspace_ops.append(realspace_op)
if i == j:
op = ("Q", "Q")
coeffs = RealspaceCoeffs(np.diag(freqs) / 2, label="omega")
assert coeffs is not None
realspace_ops.append(RealspaceOperator(modes, op, coeffs))
ret_val = RealspaceSum(modes, realspace_ops)
for op in ret_val.ops:
assert op.coeffs is not None
return RealspaceSum(modes, realspace_ops)
def _mode_frags(
states: int, modes: int, freqs: ArrayLike, taylor_coeffs: Sequence[ArrayLike]
) -> list[RealspaceMatrix]:
"""Returns the mode based fragmentation scheme"""
if len(taylor_coeffs) != 3:
raise ValueError(
"Mode-based fragmentation is only compatible with quadratic Taylor coefficients."
)
_, alphas, betas = taylor_coeffs
quadratic_frags = [
_mode_quadratic(states, modes, index, freqs, betas)
for index in product(range(modes), repeat=2)
]
linear_frags = [_mode_linear(states, modes, index, alphas) for index in range(modes)]
frags = _group_commuting(quadratic_frags + linear_frags)
momentum = _momentum_fragment(states, modes, freqs)
potential = _mode_potential_fragment(states, modes, taylor_coeffs)
frags.append(momentum + potential)
return frags
def _mode_quadratic(states, modes, index, freqs, betas) -> tuple[RealspaceMatrix, np.ndarray]:
"""Returns the quadratic terms of the mode based fragmentation scheme"""
m1, m2 = index
frag = RealspaceMatrix.zero(states, modes)
mat = np.zeros((states, states))
for i, j in product(range(states), repeat=2):
h = betas[i, j, m1, m2]
if i == j and m1 == m2:
h += freqs[m1] / 2
if np.isclose(h, 0, atol=1e-10):
continue
coeffs = np.zeros((modes, modes))
coeffs[m1, m2] = h
op = RealspaceOperator(
modes, ("Q", "Q"), RealspaceCoeffs(coeffs, label=f"beta[{m1}, {m2}][{i}, {j}]")
)
frag.set_block(i, j, RealspaceSum(modes, [op]))
mat[i, j] = h
return frag, mat
def _mode_linear(states, modes, index, alphas) -> tuple[RealspaceMatrix, np.ndarray]:
"""Returns the linear terms of the mode based fragmentation scheme"""
frag = RealspaceMatrix.zero(states, modes)
mat = np.zeros((states, states))
for i, j in product(range(states), repeat=2):
h = alphas[i, j, index]
if np.isclose(h, 0):
continue
coeffs = np.zeros(modes)
coeffs[index] = h
op = RealspaceOperator(
modes, ("Q",), RealspaceCoeffs(coeffs, label=f"alpha[{index}][{i}, {j}]")
)
frag.set_block(i, j, RealspaceSum(modes, [op]))
mat[i, j] = h
return frag, mat
def _group_commuting(frags: list[tuple[RealspaceMatrix, np.ndarray]]) -> list[RealspaceMatrix]:
"""Sums the commuting fragments. This operation is order dependent."""
remaining = frags
groups = []
while remaining:
cur_frag, cur_mat = remaining[0]
commuting_frags = [cur_frag]
commuting_mats = [cur_mat]
non_commuting = []
for frag, mat in remaining[1:]:
if all(_commute(mat, m) for m in commuting_mats):
commuting_frags.append(frag)
commuting_mats.append(mat)
else:
non_commuting.append((frag, mat))
groups.append(commuting_frags)
remaining = non_commuting
states = cur_frag.states
modes = cur_frag.modes
summed_groups = [sum(group, RealspaceMatrix.zero(states, modes)) for group in groups]
return summed_groups
def _mode_potential_fragment(
states: int, modes: int, taylor_coeffs: Sequence[ArrayLike]
) -> RealspaceMatrix:
"""Returns the potential fragment in the mode based fragmentation scheme"""
frag = RealspaceMatrix.zero(states, modes)
for i, j in product(range(states), repeat=2):
lambdas = taylor_coeffs[0][i, j]
op = RealspaceOperator(modes, (), RealspaceCoeffs(lambdas, label=f"lambda[{i}, {j}]"))
frag.set_block(i, j, RealspaceSum(modes, [op]))
return frag
def _commute(a: np.ndarray, b: np.ndarray) -> bool:
c = a @ b - b @ a
return np.allclose(c, np.zeros_like(c))
def _validate_input(
states: int, modes: int, freqs: ArrayLike, taylor_coeffs: Sequence[ArrayLike]
) -> None:
"""Validate that the shapes of the harmonic frequencies and the Taylor coefficients are
correct."""
for i, phi in enumerate(taylor_coeffs):
shape = (states, states) + (modes,) * i
if phi.shape != shape:
raise ValueError(
f"{i}th order coefficient tensor must have shape {shape}, got shape {phi.shape}"
)
if freqs.shape != (modes,):
raise TypeError(f"Frequencies must have shape {(modes,)}, got shape {freqs.shape}.")