qp.VibronicHamiltonian

class VibronicHamiltonian(constant, linear, quadratic, kinetic)[source]

Bases: NumericHamiltonian

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. 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,

\[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

\[(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 .\]
Parameters:
  • constant (TensorLike | AbstractArray) – the constant (mode-independent) coefficients \(c^{(i)}_{ab}\) of the F position fragments, of shape (F, N, N).

  • linear (TensorLike | AbstractArray) – the linear-in-position coefficients \(l^{(i)}_{ab,r}\), of shape (F, N, N, M).

  • quadratic (TensorLike | AbstractArray) – the quadratic-in-position coefficients \(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 \(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 num_fragments, num_states and 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)

Recall the form of the vibronic Hamiltonian,

\[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

\[(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 \(i\);

  • linear[i][a, b, r]: the coefficient of \(Q_r\);

  • quadratic[i][a, b, r, s]: the coefficient of \(Q_r Q_s\). The diagonal [..., r, r] holds the \(Q_r^2\) coefficient, while an off-diagonal \(Q_r Q_s\) coefficient is read once, from the entry with \(r < s\); the mirror entry \((s, r)\) is ignored, so put the full weight on \(r < s\) rather than splitting it evenly between the two;

  • kinetic[a, b, r, s]: the coefficient of \(P_r P_s\). TrotterVibronic reads only the mode-diagonal part of the \((0, 0)\) electronic block, \(t_r =\) kinetic[0, 0, r, r].

Note that the TrotterVibronic operator imposes further structure to the above; it requires the “XOR” fragmentation scheme of arXiv:2411.13669 and a number of electronic states, N, that is a power of 2.

dimensions

The named dimensions derived from the tensor shapes.

is_fully_abstract

Whether all tensors are abstract specifications rather than concrete data.

numeric_data

The tensors this Hamiltonian carries and the scalar data, in (tensor_names, scalar_names) order.

scalar_names

The fields the Hamiltonian carries that are scalar quantities.

symbol_metadata

Maps each shape symbol to (attribute name, offset).

tensor_names

The tensor fields this Hamiltonian carries, in pytree leaf order.

tensor_shapes

Maps each shape-validated tensor field to its symbolic shape template.

tensors

The tensors this Hamiltonian carries, in tensor_names order.

dimensions

The named dimensions derived from the tensor shapes.

Type:

dict

is_fully_abstract

Whether all tensors are abstract specifications rather than concrete data.

Type:

bool

numeric_data

The tensors this Hamiltonian carries and the scalar data, in (tensor_names, scalar_names) order.

Type:

tuple

scalar_names = ()

The fields the Hamiltonian carries that are scalar quantities.

symbol_metadata = {'F': ('num_fragments', 0), 'M': ('num_modes', 0), 'N': ('num_states', 0)}

Maps each shape symbol to (attribute name, offset).

tensor_names = ('constant', 'linear', 'quadratic', 'kinetic')

The tensor fields this Hamiltonian carries, in pytree leaf order.

tensor_shapes = {'constant': ('F', 'N', 'N'), 'kinetic': ('N', 'N', 'M', 'M'), 'linear': ('F', 'N', 'N', 'M'), 'quadratic': ('F', 'N', 'N', 'M', 'M')}

Maps each shape-validated tensor field to its symbolic shape template.

tensors

The tensors this Hamiltonian carries, in tensor_names order.

Type:

tuple

Contents

Using PennyLane

Release news

Development

API

Internals