qp.CGFHamiltonian¶
- class CGFHamiltonian(core_tensors, leaf_tensors, nuc_constant=None)[source]¶
Bases:
NumericHamiltonianA 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.
See also
- Parameters:
core_tensors (TensorLike | AbstractArray) – The core tensors of shape
(L+1, M, M, N, N). Index0along the leading dimension represents the one-body core tensor, while indices1throughLrepresent the two-mode interaction cores. Only the one-body diagonalcore_tensors[0][l, l, p, p]and the strict lower mode trianglecore_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). Index0along the leading dimension represents the one-body leaf tensor, while indices1throughLrepresent the two-mode rotation leaves. Allleaf_tensorsmust be real and orthogonal.nuc_constant (float | AbstractArray | None) – The nuclear constant energy offset. Defaults to
0.0if left asNone.
Here
Mis the number of modes,Nthe number of modals per mode, andLthe number of two-body fragments; all three are derived from the shapes and reported asnum_modes,num_modals, andnum_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)
Implementation Details
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 diagonalcore_tensors[0][l, l, p, p]sets the single-siteRZangles of the one-body layer;core_tensors[nu](\(\nu \geq 1\)): the two-body tensors, whose strict lower mode trianglecore_tensors[nu][l, m](\(l > m\)) sets the two-siteIsingZZangles of the two-body layers;nuc_constant: the constant \(C\), applied together with the one-body identity terms as a singleGlobalPhase(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
IsingZZgates.Attributes
The named dimensions derived from the tensor shapes.
Whether all tensors are abstract specifications rather than concrete data.
The tensors this Hamiltonian carries and the scalar data, in (
tensor_names,scalar_names) order.The fields the Hamiltonian carries that are scalar quantities.
Maps each shape symbol to
(attribute name, offset).The tensor fields this Hamiltonian carries, in pytree leaf order.
Maps each shape-validated tensor field to its symbolic shape template.
The tensors this Hamiltonian carries, in
tensor_namesorder.- 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_namesorder.- Type:
tuple
Methods
Transpose the one-body leaf so both sectors share the scaffolding's row convention.
Force every per-mode leaf to determinant
+1so that noBasisRotationneeds 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
+1so that noBasisRotationneeds a determinant-correcting phase flip.Leaves may come with mixed determinants (e.g. an
eighone-body leaf withdet = -1next toexpmtwo-body leaves withdet = +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.