qp.CGFHamiltonian

class CGFHamiltonian(core_tensors, leaf_tensors, nuc_constant=None)[source]

Bases: NumericHamiltonian

A Christiansen greedy-fragmentation (CGF) vibrational Hamiltonian.

The form of this Hamiltonian is described in arXiv:2508.11865, Sec. III C. 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 \(L\) fragments, each parameterized by orthogonal rotation matrices (leaf_tensors) and a diagonal interaction core (core_tensors).

Mathematically,

\[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 \(n_{lp}\) is the number operator of modal \(p\) of mode \(l\), \(\tilde{n}^{(\nu)}_{lp} = \mathcal{U}^{(\nu,l)\dagger} n_{lp} \mathcal{U}^{(\nu,l)}\) is its rotation into the diagonal basis of fragment \(\nu\) by the real orthogonal per-mode rotation \(\mathcal{U}^{(\nu,l)}\), two-body fragments couple distinct modes (\(l > m\)), and \(C\) is a scalar constant. See the Implementation Details for more information.

Parameters:
  • 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] (\(l > m\), \(\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 num_modes, num_modals, and 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)

Recall the form of the CGF Hamiltonian,

\[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 \(n_{lp} = (I - Z_{lp})/2\), all single-site \(Z\) terms (including those generated by expanding the two-body \(\tilde{n}_{lp} \tilde{n}_{mq}\)) are collected into the one-body fragment, and all constants — including the two-body identity balance \(-\tfrac{1}{4}\sum \lambda\) — into \(C\), so each two-body fragment retains only its two-site \(Z_{lp} Z_{mq}\) couplings. The input tensors therefore map to this regrouped form as:

  • leaf_tensors[nu][l]: the per-mode \(N \times N\) real orthogonal rotation that leaves follow opposite modal conventions that differ by a transpose: the one-body leaf (\(\nu = 0\)) stores its eigenvectors on the columns, so \(\mathcal{U}^{(0,l)} =\) BasisRotation (leaf_tensors[0][l]), while each two-body leaf (\(\nu \geq 1\)) stores the modal index on the rows, so \(\mathcal{U}^{(\nu,l)} =\) 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 RZ angles of the one-body layer;

  • core_tensors[nu] (\(\nu \geq 1\)): the two-body tensors, whose strict lower mode triangle core_tensors[nu][l, m] (\(l > m\)) sets the two-site IsingZZ angles of the two-body layers;

  • nuc_constant: the constant \(C\), applied together with the one-body identity terms as a single GlobalPhase (the energy shift; \(C\) must already carry the two-body identity balance).

Note that “one-body”/”two-body” count number operators (\(n_{lp}\), \(n_{lp} n_{mq}\)), not Pauli weight; the regrouping is what lets each two-body layer use only two-site IsingZZ gates.

dimensions

The named dimensions derived from the tensor shapes.

is_fully_abstract

Whether all tensors are abstract specifications rather than concrete data.

nuc_constant

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

nuc_constant = None
numeric_data

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

Type:

tuple

scalar_names = ('nuc_constant',)

The fields the Hamiltonian carries that are scalar quantities.

symbol_metadata = {'L1': ('num_fragments', 1), 'M': ('num_modes', 0), 'N': ('num_modals', 0)}

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

tensor_names = ('core_tensors', 'leaf_tensors')

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

tensor_shapes = {'core_tensors': ('L1', 'M', 'M', 'N', 'N'), 'leaf_tensors': ('L1', 'M', 'N', 'N')}

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

tensors

The tensors this Hamiltonian carries, in tensor_names order.

Type:

tuple

align_one_body_leaf()

Transpose the one-body leaf so both sectors share the scaffolding's row convention.

normalize_leaf_determinant()

Force every per-mode leaf to determinant +1 so that no BasisRotation needs a determinant-correcting phase flip.

align_one_body_leaf()[source]

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 \(U^{(l)}_{pa}\) convention of arXiv: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.

normalize_leaf_determinant()[source]

Force every per-mode leaf to determinant +1 so that no 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 \(|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.

Contents

Using PennyLane

Release news

Development

API

Internals