qp.CDFHamiltonian¶
- class CDFHamiltonian(core_tensors, leaf_tensors, nuc_constant=None)[source]¶
Bases:
NumericHamiltonianA compressed double-factorized (CDF) electronic Hamiltonian.
The form of this Hamiltonian is described in arXiv:2506.15784, Sec. III A. Briefly, this Hamiltonian form makes approximations to the two-body term in an electronic Hamiltonian in the molecular orbital 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_{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 \(\tilde{n}_p = n_{p\alpha} + n_{p\beta}\) is the spin-summed number operator of orbital \(p\), \(\tilde{n}^{(l)}_{p} = \mathcal{U}^{(l)\dagger} \tilde{n}_{p} \mathcal{U}^{(l)}\) is its rotation into the diagonal basis of fragment \(l\), and \(C\) is a scalar constant. The same orbital rotation \(\mathcal{U}^{(l)}\) acts on the \(\alpha\) and \(\beta\) spin sectors, and the two-body sum runs over all ordered pairs \((p, q)\) (hence the \(\tfrac{1}{2}\)). See the Implementation Details for more information.
See also
- Parameters:
core_tensors (TensorLike | AbstractArray) – the core tensors, of shape
(L+1, N, N). The leading dimension’s0index is the one-body core tensor, while the rest represent the two-body cores. Only the diagonal ofcore_tensors[0]is used (one-body), whilecore_tensors[l]for \(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’s0index represents the one-body leaf tensor, while the rest represents the two-body leaves.leaf_tensorsmust be real and orthogonal.nuc_constant (float | AbstractArray | None) – the nuclear constant energy offset. Defaults to
0.0if left asNone.
Here
Nis the number of spatial orbitals andLthe number of two-body fragments; both are derived from the shapes and reported asnum_orbitalsandnum_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)
Implementation Details
Recall the form of the CDF Hamiltonian,
\[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 \(n = (I - Z)/2\), the single-site \(Z\) terms generated by expanding the two-body \(\tilde{n}_p \tilde{n}_q\) are folded into the one-body tensor, so each two-body fragment retains only its two-site \(Z_p Z_q\) couplings. The input tensors map to this form as:
leaf_tensors[l]: the \(N \times N\) orbital rotation \(\mathcal{U}^{(l)} =\)BasisRotation(leaf_tensors[l])of fragment \(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 \(\epsilon_p =\)core_tensors[0][p, p]sets the single-siteRZangles of the one-body layer;core_tensors[l](\(l \geq 1\)): the symmetric two-body coupling tensors \(\lambda^{(l)}_{pq}\), whose entries set the two-siteIsingZZangles of the two-body layers;nuc_constant: the scalar constant \(C\). Together with the identity terms produced by the \(n = (I - Z)/2\) substitution, it is applied as a singleGlobalPhase(the energy shift; see the Implementation Details).
Note that “one-body”/”two-body” count number operators (\(\tilde{n}_p\), \(\tilde{n}_p \tilde{n}_q\)), 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), 'N': ('num_orbitals', 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', 'N', 'N'), 'leaf_tensors': ('L1', '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
Force every leaf to determinant
+1so that noBasisRotationneeds a determinant-correcting phase flip.- normalize_leaf_determinant()[source]¶
Force every leaf to determinant
+1so that noBasisRotationneeds a determinant-correcting phase flip.factorize()produces leaves with mixed determinants for many molecules, e.g. aneighone-body leaf withdet = -1next toexpmtwo-body leaves withdet = +1. Here \(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 \(|v\rangle\langle v|\) (the number operator built from that orbital), and negating the column leaves this projector unchanged since \(|-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.