ffsim.linalg.double_factorized_t2

ffsim.linalg.double_factorized_t2(t2_amplitudes, *, tol=1e-08, max_terms=None, optimize=False, diag_coulomb_indices=None, regularization=0, multi_stage_start=None, multi_stage_step=None, return_optimize_result=False, **optimize_kwargs)[source]

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

Overloads:

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

Warning

The optimize, diag_coulomb_indices, regularization, multi_stage_start, multi_stage_step, return_optimize_result, and optimize_kwargs arguments are deprecated. Instead, call double_factorized_t2_compressed() on the output of this function.

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.

  • optimize (bool) – Deprecated. Whether to optimize the tensors returned by the decomposition to minimize the error in the factorization.

  • diag_coulomb_indices (list[tuple[int, int]] | None) – Deprecated. See double_factorized_t2_compressed().

  • regularization (float) – Deprecated. See double_factorized_t2_compressed().

  • multi_stage_start (int | None) – Deprecated. See double_factorized_t2_compressed().

  • multi_stage_step (int | None) – Deprecated. See double_factorized_t2_compressed().

  • return_optimize_result (bool) – Deprecated. Whether to also return the OptimizeResult returned by scipy.optimize.minimize(). If no optimization is performed, None is returned in its place.

  • optimize_kwargs – Deprecated. Keyword arguments to pass to scipy.optimize.minimize() when optimize is set to True.

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. If return_optimize_result is set to True, the OptimizeResult returned by scipy.optimize.minimize() is also returned, or None if no optimization was performed. No optimization is performed if optimize is set to False.

Raises:

  • ValueError – The t2 amplitudes are complex-valued.

  • ValueError – max_terms is less than 1.

  • ValueError – optimize is True and multi_stage_start or multi_stage_step is less than 1.

  • ValueError – optimize is True and the exact factorization has no terms.

  • ValueError – optimize is True and diag_coulomb_indices contains lower triangular indices.