# 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.
r"""Lightweight containers for Hamiltonians expressed as a bundle of per-fragment tensors.
These classes wrap pre-computed numeric data in a named type so that it can be passed
around, validated, and used as operator input data consistently, whether the data is
concrete or only known abstractly at compile time.
:class:`NumericHamiltonian` holds the machinery every representation shares. A
representation is defined by naming its tensors and giving each one a symbolic shape
template:
.. code-block:: python
class VibronicHamiltonian(NumericHamiltonian):
tensor_names = ("constant", "kinetic")
tensor_shapes = {"constant": ("F", "N", "N"), "kinetic": ("N", "N", "M", "M")}
symbol_metadata = {"F": ("num_fragments", 0), "N": ("num_states", 0), "M": ("num_modes", 0)}
"""
from __future__ import annotations
from dataclasses import dataclass, replace
from numbers import Number
from typing import Any, ClassVar
import numpy as np
from pennylane import math
from pennylane.pytrees import register_pytree
from pennylane.typing import AbstractArray
__all__ = [
"NumericHamiltonian",
"CDFHamiltonian",
"CGFHamiltonian",
"VibronicHamiltonian",
]
def _shape_of(tensor):
"""Return the shape of a concrete tensor or of an :class:`~.AbstractArray` spec."""
if isinstance(tensor, AbstractArray):
return tensor.shape
return tuple(math.shape(tensor))
def _dtype_of(tensor):
"""Return a ``numpy`` dtype for a concrete tensor or an ``AbstractArray`` spec."""
if isinstance(tensor, AbstractArray):
return tensor.dtype
if isinstance(tensor, Number):
return np.dtype(type(tensor))
return np.dtype(math.get_dtype_name(tensor))
class NumericHamiltonian:
r"""Base class for Hamiltonians expressed as a bundle of named numeric tensors.
Subclasses name their tensors in ``tensor_names`` (the pytree leaf order) and describe
the shape of each one symbolically in ``tensor_shapes``. Each entry of a template is a
symbol, and a symbol repeated within or across templates must take the same size — this
is what lets a single validator enforce shape consistency for every representation, for
concrete and abstract data alike. A field carrying no shape template (e.g. a scalar
validated separately) is named in ``scalar_names`` instead. It still participates in
the pytree, hashing and equality (see ``numeric_data``) but is not shape-validated.
``symbol_metadata`` maps each symbol to the attribute that reports it, together with
the offset between the two. An axis holding ``L + 1`` entries for ``L`` fragments (index
``0`` being a distinguished fragment) therefore has offset ``1``, while an axis that is
itself the reported dimension has offset ``0``.
Subclasses are registered as pytrees whose leaves are the tensors, so the data flows
through program capture and lowering with no per-representation special-casing.
"""
tensor_names: ClassVar[tuple[str, ...]]
"""The tensor fields this Hamiltonian carries, in pytree leaf order."""
scalar_names: ClassVar[tuple[str, ...]]
"""The fields the Hamiltonian carries that are scalar quantities."""
tensor_shapes: ClassVar[dict[str, tuple[str, ...]]]
"""Maps each shape-validated tensor field to its symbolic shape template."""
symbol_metadata: ClassVar[dict[str, tuple[str, int]]]
"""Maps each shape symbol to ``(attribute name, offset)``."""
def __init_subclass__(cls, **kwargs):
if not hasattr(cls, "scalar_names"):
cls.scalar_names = ()
super().__init_subclass__(**kwargs)
# It's required for Catalyst to treat the Hamiltonian as a pytree, so that it can be
# passed as an argument to a decomposition rule and reconstructed from abstract avals
register_pytree(cls, cls._flatten, cls._unflatten)
def _unify_shapes(self):
"""Check every templated tensor against its template and unify the shared symbols."""
sizes: dict[str, int] = {}
for name, template in self.tensor_shapes.items():
shape = _shape_of(getattr(self, name))
if shape is Ellipsis or len(shape) != len(template):
raise ValueError(
f"'{name}' must have {len(template)} dimensions with shape {template}, "
f"got shape {shape}."
)
for size, symbol in zip(shape, template, strict=True):
# ``-1`` marks an axis whose size is unknown. It is permissive and does
# not pin the symbol.
if size == -1:
sizes.setdefault(symbol, -1)
continue
if symbol in sizes and sizes[symbol] not in (size, -1):
meta_name, _ = self.symbol_metadata[symbol]
raise ValueError(
f"inconsistent '{meta_name}' ({symbol}): {sizes[symbol]} vs {size}."
)
sizes[symbol] = size
for symbol, size in sizes.items():
meta_name, offset = self.symbol_metadata[symbol]
if size != -1 and size - offset < 1:
raise ValueError(f"'{meta_name}' must be at least 1, got {size - offset}.")
return sizes
def __post_init__(self):
for name in self.tensor_names:
tensor_data = getattr(self, name)
if isinstance(tensor_data, (list, tuple)):
object.__setattr__(self, name, np.asarray(tensor_data))
for name in self.scalar_names:
scalar_data = getattr(self, name)
scalar_data_shape = _shape_of(scalar_data)
if scalar_data_shape != ():
raise ValueError(
f"Input argument {name} must be a scalar, got shape {scalar_data_shape}."
)
if isinstance(scalar_data, Number):
# Stored as an array so the pytree leaf has a stable shape and dtype,
# Note it's important when a Hamiltonian is used as a control-flow carry.
object.__setattr__(self, name, np.asarray(scalar_data))
sizes = self._unify_shapes()
for symbol, (name, offset) in self.symbol_metadata.items():
size = sizes[symbol]
object.__setattr__(self, name, size - offset if size >= 0 else None)
@property
def is_fully_abstract(self) -> bool:
"""bool: Whether all tensors are abstract specifications rather than concrete data."""
if not hasattr(self, "_is_fully_abstract"):
_is_fully_abstract = True
for name in self.tensor_names + self.scalar_names:
if not isinstance(getattr(self, name), AbstractArray):
_is_fully_abstract = False
break
object.__setattr__(self, "_is_fully_abstract", _is_fully_abstract)
return self._is_fully_abstract # pylint: disable=no-member
@property
def numeric_data(self) -> tuple:
"""tuple: The tensors this Hamiltonian carries and the scalar data, in (``tensor_names``, ``scalar_names``) order."""
return tuple(getattr(self, name) for name in self.tensor_names + self.scalar_names)
@property
def tensors(self) -> tuple:
"""tuple: The tensors this Hamiltonian carries, in ``tensor_names`` order."""
return tuple(getattr(self, name) for name in self.tensor_names)
@property
def dimensions(self) -> dict[str, int | None]:
"""dict: The named dimensions derived from the tensor shapes."""
return {name: getattr(self, name) for name, _ in self.symbol_metadata.values()}
def _flatten(self):
"""Split into tensor leaves and hashable metadata.
The derived dimensions travel in the metadata so that ``_unflatten`` does not
have to re-derive them.
"""
return self.numeric_data, tuple(self.dimensions.values())
@classmethod
def _unflatten(cls, data, metadata):
"""Rebuild from leaves and metadata, bypassing validation."""
obj = cls.__new__(cls)
for name, value in zip(cls.tensor_names + cls.scalar_names, data, strict=True):
object.__setattr__(obj, name, value)
for value, (name, _) in zip(metadata, cls.symbol_metadata.values(), strict=True):
object.__setattr__(obj, name, value)
return obj
def _hash_key(self):
return tuple((_shape_of(t), _dtype_of(t)) for t in self.numeric_data)
def __hash__(self):
# Deliberately keyed on shapes rather than values: this is the information that
# matters for compilation and resource analysis, and it makes an abstract
# Hamiltonian hash equal to the concrete one it was derived from.
return hash((type(self).__name__, self._hash_key()))
def __eq__(self, other):
if type(other) is not type(self):
return NotImplemented
if self._hash_key() != other._hash_key():
return False
for data, other_data in zip(self.numeric_data, other.numeric_data, strict=True):
self_abstract = isinstance(data, AbstractArray)
other_abstract = isinstance(other_data, AbstractArray)
# One is abstract, other is concrete
if self_abstract ^ other_abstract:
return False
# Both concrete
if not self_abstract and not math.allclose(data, other_data):
return False
# We only need to compare our data with the other data if both are concrete
# because comparing the `_hash_key` implicitly compares the shape and
# dtype, thus making comparisons redundant if the data is abstract
return True
def __repr__(self):
def render(tensor):
# Abstract specs and scalars are small enough to show outright; a full
# tensor is not, so it is summarized by its shape.
if isinstance(tensor, AbstractArray) or _shape_of(tensor) == ():
return repr(tensor)
return f"tensor(shape={_shape_of(tensor)})"
body = ", ".join(
f"{n}={render(getattr(self, n))}" for n in self.tensor_names + self.scalar_names
)
return f"{type(self).__name__}({body})"
[docs]
@dataclass(frozen=True, eq=False, repr=False)
class CDFHamiltonian(NumericHamiltonian):
r"""A compressed double-factorized (CDF) electronic Hamiltonian.
The form of this Hamiltonian is described in
`arXiv:2506.15784, Sec. III A <https://arxiv.org/abs/2506.15784>`__.
Briefly, this Hamiltonian form makes approximations to the two-body term in an electronic
Hamiltonian in the molecular orbital basis via a sum of :math:`L` fragments, each parameterized
by orthogonal rotation matrices (`leaf_tensors`) and a diagonal interaction core
(`core_tensors`).
Mathematically,
.. math::
H = C + \sum_{p} \epsilon_{p}\, \tilde{n}^{(0)}_{p}
+ \frac{1}{2}\sum_{l=1}^{L} \sum_{p,q} \lambda^{(l)}_{pq}\,
\tilde{n}^{(l)}_{p} \tilde{n}^{(l)}_{q} ,
where :math:`\tilde{n}_p = n_{p\alpha} + n_{p\beta}` is the spin-summed number operator of
orbital :math:`p`, :math:`\tilde{n}^{(l)}_{p} = \mathcal{U}^{(l)\dagger} \tilde{n}_{p}
\mathcal{U}^{(l)}` is its rotation into the diagonal basis of fragment :math:`l`, and :math:`C`
is a scalar constant. The same orbital rotation :math:`\mathcal{U}^{(l)}` acts on the
:math:`\alpha` and :math:`\beta` spin sectors, and the two-body sum runs over all ordered pairs
:math:`(p, q)` (hence the :math:`\tfrac{1}{2}`). See the Implementation Details for more
information.
.. seealso:: :class:`pennylane.TrotterCDF`
Args:
core_tensors (TensorLike | AbstractArray): the core tensors, of shape
``(L+1, N, N)``. The leading dimension's ``0`` index is the one-body core tensor, while
the rest represent the two-body cores. Only the diagonal of ``core_tensors[0]`` is used
(one-body), while ``core_tensors[l]`` for :math:`l \geq 1` are the symmetric two-body
coupling tensors.
leaf_tensors (TensorLike | AbstractArray): the leaf tensors, of shape
``(L+1, N, N)``. The leading dimension's ``0`` index represents the one-body leaf
tensor, while the rest represents the two-body leaves. ``leaf_tensors`` must be real and
orthogonal.
nuc_constant (float | AbstractArray | None): the nuclear constant energy offset. Defaults to
``0.0`` if left as ``None``.
Here ``N`` is the number of spatial orbitals and ``L`` the number of two-body fragments; both
are derived from the shapes and reported as :attr:`num_orbitals` and :attr:`num_fragments`.
Raises:
ValueError: if the tensor ranks or shared dimensions are inconsistent.
**Example**
>>> import numpy as np
>>> L, N = 2, 3
>>> ham = qp.CDFHamiltonian(
... core_tensors=np.random.rand(L + 1, N, N),
... leaf_tensors=np.random.rand(L + 1, N, N),
... nuc_constant=0.5,
... )
>>> ham.num_orbitals, ham.num_fragments
(3, 2)
The numeric data is directly accessible as follows:
>>> ham.core_tensors.shape
(3, 3, 3)
>>> ham.nuc_constant
array(0.5)
The same Hamiltonian can be described with abstract data for the purposes of fast, low-fidelity
resource-estimation workflows where only shape information is available:
>>> from pennylane.typing import Float
>>> qp.CDFHamiltonian(Float[L + 1, N, N], Float[L + 1, N, N]).core_tensors
AbstractArray((3, 3, 3), float64, weak_type=True)
.. details ::
:title: Implementation Details
Recall the form of the CDF Hamiltonian,
.. math::
H = C + \sum_{p} \epsilon_{p}\, \tilde{n}^{(0)}_{p}
+ \frac{1}{2}\sum_{l=1}^{L} \sum_{p,q} \lambda^{(l)}_{pq}\,
\tilde{n}^{(l)}_{p} \tilde{n}^{(l)}_{q} .
The inputs below encode a *regrouped* form of this Hamiltonian: after substituting
:math:`n = (I - Z)/2`, the single-site :math:`Z` terms generated by expanding the two-body
:math:`\tilde{n}_p \tilde{n}_q` are folded into the one-body tensor, so each two-body
fragment retains only its two-site :math:`Z_p Z_q` couplings. The input tensors map to this
form as:
* ``leaf_tensors[l]``: the :math:`N \times N` orbital rotation :math:`\mathcal{U}^{(l)} =`
:class:`~.BasisRotation` ``(leaf_tensors[l])`` of fragment :math:`l`, which rotates from the
bare basis into the fragment's diagonal basis and is applied to both spin sectors (it must be
real orthogonal);
* ``core_tensors[0]``: the (regrouped) one-body tensor, whose diagonal
:math:`\epsilon_p =` ``core_tensors[0][p, p]`` sets the *single-site* :class:`~.RZ` angles of
the one-body layer;
* ``core_tensors[l]`` (:math:`l \geq 1`): the symmetric two-body coupling tensors
:math:`\lambda^{(l)}_{pq}`, whose entries set the *two-site* :class:`~.IsingZZ` angles of the
two-body layers;
* ``nuc_constant``: the scalar constant :math:`C`. Together with the identity terms produced by
the :math:`n = (I - Z)/2` substitution, it is applied as a single :class:`~.GlobalPhase`
(the energy shift; see the Implementation Details).
Note that "one-body"/"two-body" count number operators (:math:`\tilde{n}_p`,
:math:`\tilde{n}_p \tilde{n}_q`), not Pauli weight; the regrouping is what lets each two-body
layer use only two-site :class:`~.IsingZZ` gates.
"""
tensor_names: ClassVar[tuple[str, ...]] = ("core_tensors", "leaf_tensors")
scalar_names: ClassVar[tuple[str, ...]] = ("nuc_constant",)
tensor_shapes: ClassVar[dict[str, tuple[str, ...]]] = {
"core_tensors": ("L1", "N", "N"),
"leaf_tensors": ("L1", "N", "N"),
}
symbol_metadata: ClassVar[dict[str, tuple[str, int]]] = {
"L1": ("num_fragments", 1),
"N": ("num_orbitals", 0),
}
core_tensors: Any
leaf_tensors: Any
nuc_constant: Any = None
def __post_init__(self):
if self.nuc_constant is None:
zero = AbstractArray((), float) if self.is_fully_abstract else np.asarray(0.0)
object.__setattr__(self, "nuc_constant", zero)
super().__post_init__()
[docs]
def normalize_leaf_determinant(self) -> CDFHamiltonian:
r"""Force every leaf to determinant ``+1`` so that no :class:`~.BasisRotation` needs a
determinant-correcting phase flip.
:func:`~pennylane.qchem.factorize` produces leaves with *mixed* determinants for many
molecules, e.g. an ``eigh`` one-body leaf with ``det = -1`` next to ``expm`` two-body leaves
with ``det = +1``. Here :math:`v` is a single column of the leaf, i.e. one of
the fragment's diagonalizing orbitals; the fragment only depends on it through the projector
:math:`|v\rangle\langle v|` (the number operator built from that orbital), and negating the
column leaves this projector unchanged since :math:`|-v\rangle\langle -v| = |v\rangle\langle v|`.
So flipping one column's sign is a physical no-op on the fragment -- it only flips the leaf's
determinant.
"""
leaves = self.leaf_tensors
signs = math.sign(math.linalg.det(leaves)) # (num_fragments,)
col_scale = math.concatenate(
[signs[..., None], math.ones_like(leaves[..., 0, 1:])], axis=-1
) # (num_fragments, N): +/-1 in the first column slot, 1 elsewhere
return replace(self, leaf_tensors=leaves * col_scale[..., None, :])
[docs]
@dataclass(frozen=True, eq=False, repr=False)
class CGFHamiltonian(NumericHamiltonian):
r"""A Christiansen greedy-fragmentation (CGF) vibrational Hamiltonian.
The form of this Hamiltonian is described in
`arXiv:2508.11865, Sec. III C <https://arxiv.org/abs/2508.11865>`__. Briefly, this Hamiltonian
form makes approximations to the two-mode terms of a vibrational Hamiltonian in the vibrational
self-consistent field (VSCF)-rotated modal basis via a sum of :math:`L` fragments, each
parameterized by orthogonal rotation matrices (`leaf_tensors`) and a diagonal interaction core
(`core_tensors`).
Mathematically,
.. math::
H = C + \sum_{l,p} \epsilon_{lp}\, \tilde{n}^{(0)}_{lp}
+ \sum_{\nu=1}^{L} \sum_{l>m} \sum_{p,q} \lambda^{(\nu)}_{lmpq}\,
\tilde{n}^{(\nu)}_{lp} \tilde{n}^{(\nu)}_{mq} ,
where :math:`n_{lp}` is the number operator of modal :math:`p` of mode :math:`l`,
:math:`\tilde{n}^{(\nu)}_{lp} = \mathcal{U}^{(\nu,l)\dagger} n_{lp} \mathcal{U}^{(\nu,l)}` is
its rotation into the diagonal basis of fragment :math:`\nu` by the real orthogonal per-mode
rotation :math:`\mathcal{U}^{(\nu,l)}`, two-body fragments couple distinct modes
(:math:`l > m`), and :math:`C` is a scalar constant. See the Implementation Details for more
information.
.. seealso:: :class:`pennylane.TrotterCGF`
Args:
core_tensors (TensorLike | AbstractArray): The core tensors of shape
``(L+1, M, M, N, N)``. Index ``0`` along the leading dimension represents the one-body
core tensor, while indices ``1`` through ``L`` represent the two-mode interaction cores.
Only the one-body diagonal ``core_tensors[0][l, l, p, p]`` and the strict lower mode
triangle ``core_tensors[nu][l, m]`` (:math:`l > m`, :math:`\nu \geq 1`) are read.
leaf_tensors (TensorLike | AbstractArray): The leaf tensors of shape ``(L+1, M, N, N)``.
Index ``0`` along the leading dimension represents the one-body leaf tensor, while
indices ``1`` through ``L`` represent the two-mode rotation leaves. All ``leaf_tensors``
must be real and orthogonal.
nuc_constant (float | AbstractArray | None): The nuclear constant energy offset. Defaults to
``0.0`` if left as ``None``.
Here ``M`` is the number of modes, ``N`` the number of modals per mode, and ``L`` the number of
two-body fragments; all three are derived from the shapes and reported as :attr:`num_modes`,
:attr:`num_modals`, and :attr:`num_fragments`.
Raises:
ValueError: if the tensor ranks or shared dimensions are inconsistent.
**Example**
>>> import numpy as np
>>> L, M, N = 2, 2, 3
>>> ham = qp.CGFHamiltonian(
... core_tensors=np.random.rand(L + 1, M, M, N, N),
... leaf_tensors=np.random.rand(L + 1, M, N, N),
... nuc_constant=0.5,
... )
>>> ham.num_modes, ham.num_modals, ham.num_fragments
(2, 3, 2)
The numeric data is directly accessible as follows:
>>> ham.core_tensors.shape
(3, 2, 2, 3, 3)
>>> ham.leaf_tensors.shape
(3, 2, 3, 3)
The same Hamiltonian can be described with abstract data for the purposes of fast, low-fidelity
resource-estimation workflows where only shape information is available:
>>> from pennylane.typing import Float
>>> qp.CGFHamiltonian(
... core_tensors=Float[L + 1, M, M, N, N],
... leaf_tensors=Float[L + 1, M, N, N],
... ).core_tensors
AbstractArray((3, 2, 2, 3, 3), float64, weak_type=True)
.. details ::
:title: Implementation Details
Recall the form of the CGF Hamiltonian,
.. math::
H = C + \sum_{l,p} \epsilon_{lp}\, \tilde{n}^{(0)}_{lp}
+ \sum_{\nu=1}^{L} \sum_{l>m} \sum_{p,q} \lambda^{(\nu)}_{lmpq}\,
\tilde{n}^{(\nu)}_{lp} \tilde{n}^{(\nu)}_{mq} .
The inputs below encode the *regrouped* single-boson form of this Hamiltonian; after
substituting :math:`n_{lp} = (I - Z_{lp})/2`, all single-site :math:`Z` terms (including
those generated by expanding the two-body :math:`\tilde{n}_{lp} \tilde{n}_{mq}`) are
collected into the one-body fragment, and all constants — including the two-body identity
balance :math:`-\tfrac{1}{4}\sum \lambda` — into :math:`C`, so each two-body fragment
retains only its two-site :math:`Z_{lp} Z_{mq}` couplings. The input tensors therefore map
to this regrouped form as:
* ``leaf_tensors[nu][l]``: the per-mode :math:`N \times N` real orthogonal rotation that
leaves follow *opposite* modal conventions that differ by a transpose: the one-body leaf
(:math:`\nu = 0`) stores its eigenvectors on the *columns*, so
:math:`\mathcal{U}^{(0,l)} =` :class:`~.BasisRotation` ``(leaf_tensors[0][l])``, while
each two-body leaf (:math:`\nu \geq 1`) stores the modal index on the *rows*, so
:math:`\mathcal{U}^{(\nu,l)} =` :class:`~.BasisRotation` ``(leaf_tensors[nu][l].T)``.
* ``core_tensors[0]``: the (regrouped) one-body tensor, whose diagonal
``core_tensors[0][l, l, p, p]`` sets the *single-site* :class:`~.RZ` angles of the
one-body layer;
* ``core_tensors[nu]`` (:math:`\nu \geq 1`): the two-body tensors, whose strict lower mode
triangle ``core_tensors[nu][l, m]`` (:math:`l > m`) sets the *two-site* :class:`~.IsingZZ`
angles of the two-body layers;
* ``nuc_constant``: the constant :math:`C`, applied together with the one-body identity
terms as a single :class:`~.GlobalPhase` (the energy shift; :math:`C` must already carry
the two-body identity balance).
Note that "one-body"/"two-body" count number operators
(:math:`n_{lp}`, :math:`n_{lp} n_{mq}`), not Pauli weight; the regrouping is what lets each
two-body layer use only two-site :class:`~.IsingZZ` gates.
"""
tensor_names: ClassVar[tuple[str, ...]] = ("core_tensors", "leaf_tensors")
scalar_names: ClassVar[tuple[str, ...]] = ("nuc_constant",)
tensor_shapes: ClassVar[dict[str, tuple[str, ...]]] = {
"core_tensors": ("L1", "M", "M", "N", "N"),
"leaf_tensors": ("L1", "M", "N", "N"),
}
symbol_metadata: ClassVar[dict[str, tuple[str, int]]] = {
"L1": ("num_fragments", 1),
"M": ("num_modes", 0),
"N": ("num_modals", 0),
}
core_tensors: Any
leaf_tensors: Any
nuc_constant: Any = None
def __post_init__(self):
if (
self.nuc_constant is None
): # replace value with Float if core & leaf tensors are abstract, otherwise 0.0
zero = (
AbstractArray((), float)
if (
isinstance(self.leaf_tensors, AbstractArray)
and isinstance(self.core_tensors, AbstractArray)
)
else np.asarray(0.0)
)
object.__setattr__(self, "nuc_constant", zero)
super().__post_init__()
[docs]
def normalize_leaf_determinant(self) -> CGFHamiltonian:
r"""Force every per-mode leaf to determinant ``+1`` so that no :class:`~.BasisRotation` needs a
determinant-correcting phase flip.
Leaves may come with *mixed* determinants (e.g. an ``eigh`` one-body leaf with ``det = -1``
next to ``expm`` two-body leaves with ``det = +1``). Negating one orbital line leaves the
projector :math:`|v\rangle\langle v|`, and hence the fragment, unchanged, so this is a physical
no-op. The orbital is stored on the *columns* of the one-body leaf and on the *rows* of the
two-body leaves, so the two sectors negate a column and a row respectively.
"""
leaves = self.leaf_tensors
signs = math.sign(math.linalg.det(leaves)) # (L+1, M)
line = math.concatenate(
[signs[..., None], math.ones_like(leaves[..., 0, 1:])], axis=-1
) # (L+1, M, N): +/-1 in the first slot, 1 elsewhere
one_body = leaves[:1] * line[:1][..., None, :] # eigenvectors on columns -> scale column 0
two_body = leaves[1:] * line[1:][..., :, None] # modal index on rows -> scale row 0
return replace(self, leaf_tensors=math.concatenate([one_body, two_body], axis=0))
[docs]
def align_one_body_leaf(self) -> CGFHamiltonian:
"""Transpose the one-body leaf so both sectors share the scaffolding's row convention.
The scaffolding assumes each ``leaf_tensors[nu][l]`` stores its per-mode diagonalizing
rotation with the modal index on the *rows* (the two-body :math:`U^{(l)}_{pa}` convention
of `arXiv:2508.11865 <https://arxiv.org/abs/2508.11865>`__). The one-body leaf, however,
is the eigenvector matrix of the effective one-body integrals and stores its eigenvectors
as *columns*, so it is transposed here to match. Leaves are (special) orthogonal, so this
is the inverse rotation.
"""
leaves = self.leaf_tensors
return replace(
self,
leaf_tensors=math.concatenate([math.swapaxes(leaves[:1], -2, -1), leaves[1:]], axis=0),
)
[docs]
@dataclass(frozen=True, eq=False, repr=False)
class VibronicHamiltonian(NumericHamiltonian):
r"""A real-space vibronic Hamiltonian, given as dense Taylor coefficients per fragment.
The form of this Hamiltonian is described in `Motlagh et al, arXiv:2411.13669
<https://arxiv.org/abs/2411.13669>`__. It acts on ``N`` electronic states and ``M``
vibrational modes, and is partitioned into ``F`` position fragments — each diagonal in a
fragment-specific electronic basis and polynomial in the mode positions up to second order —
plus a single kinetic fragment that is quadratic in the mode momenta,
.. math::
H = \sum_{i=0}^{F-1} H_i + H_{\text{kin}},
\qquad
H_{\text{kin}} = \sum_{r,s} t_{rs}\, P_r P_s ,
where each position fragment carries the electronic matrix elements
.. math::
(H_i)_{ab} = c^{(i)}_{ab} + \sum_r l^{(i)}_{ab,r} Q_r
+ \sum_{r,s} q^{(i)}_{ab,rs} Q_r Q_s .
.. seealso:: :class:`pennylane.TrotterVibronic`
Args:
constant (TensorLike | AbstractArray): the constant (mode-independent) coefficients
:math:`c^{(i)}_{ab}` of the ``F`` position fragments, of shape ``(F, N, N)``.
linear (TensorLike | AbstractArray): the linear-in-position coefficients
:math:`l^{(i)}_{ab,r}`, of shape ``(F, N, N, M)``.
quadratic (TensorLike | AbstractArray): the quadratic-in-position coefficients
:math:`q^{(i)}_{ab,rs}`, of shape ``(F, N, N, M, M)`` (see the Implementation Details
section for the diagonal/off-diagonal convention).
kinetic (TensorLike | AbstractArray): the quadratic-in-momentum coefficients
:math:`t_{rs}` of the single kinetic fragment, of shape ``(N, N, M, M)``.
Here ``F`` is the number of position fragments, ``N`` the number of electronic states and
``M`` the number of vibrational modes; all three are derived from the shapes and reported as
:attr:`num_fragments`, :attr:`num_states` and :attr:`num_modes`.
Raises:
ValueError: if the tensor ranks or shared dimensions are inconsistent.
**Example**
>>> import numpy as np
>>> F, N, M = 2, 2, 3
>>> ham = qp.VibronicHamiltonian(
... constant=np.random.rand(F, N, N),
... linear=np.random.rand(F, N, N, M),
... quadratic=np.random.rand(F, N, N, M, M),
... kinetic=np.random.rand(N, N, M, M),
... )
>>> ham.num_fragments, ham.num_states, ham.num_modes
(2, 2, 3)
The numeric data is directly accessible as follows:
>>> ham.constant.shape
(2, 2, 2)
>>> ham.quadratic.shape
(2, 2, 2, 3, 3)
The same Hamiltonian can be described with abstract data for the purposes of fast, low-fidelity
resource-estimation workflows where only shape information is available:
>>> from pennylane.typing import Float
>>> qp.VibronicHamiltonian(
... Float[F, N, N], Float[F, N, N, M], Float[F, N, N, M, M], Float[N, N, M, M]
... ).constant
AbstractArray((2, 2, 2), float64, weak_type=True)
.. details ::
:title: Implementation Details
Recall the form of the vibronic Hamiltonian,
.. math::
H = \sum_{i=0}^{F-1} H_i + H_{\text{kin}},
\qquad
H_{\text{kin}} = \sum_{r,s} t_{rs}\, P_r P_s ,
where each position fragment carries the electronic matrix elements
.. math::
(H_i)_{ab} = c^{(i)}_{ab} + \sum_r l^{(i)}_{ab,r} Q_r
+ \sum_{r,s} q^{(i)}_{ab,rs} Q_r Q_s .
The arguments of `VibronicHamiltonian` map onto this expression as:
* ``constant[i][a, b]``: the mode-independent coefficient of position fragment :math:`i`;
* ``linear[i][a, b, r]``: the coefficient of :math:`Q_r`;
* ``quadratic[i][a, b, r, s]``: the coefficient of :math:`Q_r Q_s`. The diagonal
``[..., r, r]`` holds the :math:`Q_r^2` coefficient, while an off-diagonal
:math:`Q_r Q_s` coefficient is read *once*, from the entry with :math:`r < s`; the
mirror entry :math:`(s, r)` is ignored, so put the full weight on :math:`r < s`
rather than splitting it evenly between the two;
* ``kinetic[a, b, r, s]``: the coefficient of :math:`P_r P_s`. :class:`~.TrotterVibronic`
reads only the mode-diagonal part of the :math:`(0, 0)` electronic block,
:math:`t_r =` ``kinetic[0, 0, r, r]``.
Note that the :class:`~.TrotterVibronic` operator imposes further structure to the above;
it requires the "XOR" fragmentation scheme of
`arXiv:2411.13669 <https://arxiv.org/abs/2411.13669>`__ and a number of electronic states,
``N``, that is a power of 2.
"""
tensor_names: ClassVar[tuple[str, ...]] = ("constant", "linear", "quadratic", "kinetic")
tensor_shapes: ClassVar[dict[str, tuple[str, ...]]] = {
"constant": ("F", "N", "N"),
"linear": ("F", "N", "N", "M"),
"quadratic": ("F", "N", "N", "M", "M"),
"kinetic": ("N", "N", "M", "M"),
}
symbol_metadata: ClassVar[dict[str, tuple[str, int]]] = {
"F": ("num_fragments", 0),
"N": ("num_states", 0),
"M": ("num_modes", 0),
}
constant: Any
linear: Any
quadratic: Any
kinetic: Any