qp.CDFHamiltonian

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

Bases: NumericHamiltonian

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

Parameters:
  • 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 \(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 num_orbitals and 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)

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-site RZ angles 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-site IsingZZ angles 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 single GlobalPhase (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 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), '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_names order.

Type:

tuple

normalize_leaf_determinant()

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

normalize_leaf_determinant()[source]

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

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 \(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.

Contents

Using PennyLane

Release news

Development

API

Internals