ffsim.linalg.double_factorized_t2

ffsim.linalg.double_factorized_t2(t2_amplitudes, *, tol=1e-08, max_terms=None)[source]

Double-factorized decomposition of \(t_2\) amplitudes.

The double-factorized decomposition of a \(t_2\) amplitudes tensor \(t_{ijab}\) is

\[t_{ijab} = i \sum_{k=0}^{L - 1} \sum_{pq} Z^{(k)}_{pq} U^{(k)}_{ap} U^{(k)*}_{ip} U^{(k)}_{bq} U^{(k)*}_{jq},\]

where each \(Z^{(k)}\) is a real symmetric matrix representing a diagonal Coulomb operator, each \(U^{(k)}\) is a unitary matrix representing an orbital rotation, \(i\) and \(j\) run over occupied orbitals, and \(a\) and \(b\) run over virtual orbitals.

The number of terms \(L\) in the decomposition depends on the allowed error threshold. A larger error threshold may yield a smaller number of terms. Furthermore, the max_terms parameter specifies an optional upper bound on \(L\). The max_terms parameter is always respected, so if it is too small, then the error of the decomposition may exceed the specified error threshold.

This routine performs a straightforward “exact” factorization of the \(t_2\) amplitudes tensor based on a nested eigenvalue decomposition, and then truncates the terms based on the values of tol and max_terms. To further optimize the resulting tensors to reduce the error in the factorization, pass the untruncated factorization to double_factorized_t2_compressed().

The original \(t_2\) amplitudes tensor can be reconstructed, up to the error tolerance, using the following function:

def reconstruct_t2(
    diag_coulomb_mats: np.ndarray, orbital_rotations: np.ndarray, nocc: int
) -> np.ndarray:
    return (
        1j
        * np.einsum(
            "kpq,kap,kip,kbq,kjq->ijab",
            diag_coulomb_mats,
            orbital_rotations,
            orbital_rotations.conj(),
            orbital_rotations,
            orbital_rotations.conj(),
        )[:nocc, :nocc, nocc:, nocc:]
    )

Note: Currently, only real-valued \(t_2\) amplitudes are supported.

Parameters:

  • t2_amplitudes (ndarray) – The doubles amplitudes tensor of shape (nocc, nocc, nvrt, nvrt), where nocc is the number of occupied orbitals and nvrt is the number of virtual orbitals.

  • tol (float) – Tolerance for error in the decomposition. The error is defined as the maximum absolute difference between an element of the original tensor and the corresponding element of the reconstructed tensor.

  • max_terms (int | None) – An optional limit on the number of terms to keep in the decomposition of the \(t_2\) amplitudes tensor. This argument overrides tol.

Return type:

tuple[ndarray, ndarray]

Returns:

The diagonal Coulomb matrices and the orbital rotations. Each list of matrices is collected into a Numpy array, so this method returns a tuple of two Numpy arrays, the first containing the diagonal Coulomb matrices and the second containing the orbital rotations. Each Numpy array will have shape (L, n, n) where L is the number of terms in the decomposition and n is the number of orbitals.

Raises: