ffsim.linalg.double_factorized_t2_alpha_beta_compressed

ffsim.linalg.double_factorized_t2_alpha_beta_compressed(t2_amplitudes, *, initial_guess=None, max_terms=None, diag_coulomb_indices=None, regularization=0, multi_stage_start=None, multi_stage_step=None, **optimize_kwargs)[source]

Compress a double-factorized decomposition of alpha-beta \(t_2\) amplitudes.

Optimizes the diagonal Coulomb matrices and orbital rotations of a double-factorized decomposition of alpha-beta \(t_2\) amplitudes (see double_factorized_t2_alpha_beta()) with scipy.optimize.minimize() to reduce the error in the factorization. The optimization starts from the factorization given by initial_guess. If it is not specified, the exact factorization computed by double_factorized_t2_alpha_beta() with the default tolerance is used. To use a different tolerance, call double_factorized_t2_alpha_beta() yourself, without max_terms so that the optimization starts from the full factorization, and pass its output as initial_guess. If max_terms is specified, then the factorization is truncated to its first max_terms terms. The optimization is always performed, even if no terms are truncated.

See double_factorized_t2_compressed() for a description of multi-stage optimization.

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

Parameters:

  • t2_amplitudes (ndarray) – The doubles amplitudes tensor of shape (nocc_a, nocc_b, nvrt_a, nvrt_b), where nocc_a is the number of occupied spin-alpha orbitals, nvrt_a is the number of virtual spin-alpha orbitals, nocc_b is the number of occupied spin-beta orbitals, and nvrt_b is the number of virtual spin-beta orbitals.

  • initial_guess (tuple[ndarray, ndarray] | None) – The initial guess for the optimization, as a tuple of the diagonal Coulomb matrices, as a Numpy array of shape (n_terms, 3, norb, norb), and the orbital rotations, as a Numpy array of shape (n_terms, 2, norb, norb). Typically, this is the untruncated output of double_factorized_t2_alpha_beta(). If not specified, the exact factorization computed by double_factorized_t2_alpha_beta() with the default tolerance is used.

  • max_terms (int | None) – An optional limit on the number of terms to keep in the decomposition. If not specified, all the terms of the initial guess are kept.

  • diag_coulomb_indices (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Allowed indices for nonzero values of the diagonal Coulomb matrices. If specified, should be a tuple of 3 lists, for alpha-alpha, alpha-beta, and beta-beta matrices, in that order. For the alpha-alpha and beta-beta matrices, each index must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

  • regularization (float) – Parameter for regularizing the norm of the diagonal Coulomb matrices. This specifies the coefficient to a term added to the loss function equal to the difference between the sums of the squares of the Frobenius norms of the diagonal Coulomb matrices from the optimized factorization and the initial guess.

  • multi_stage_start (int | None) – The number of terms to start multi-stage optimization.

  • multi_stage_step (int | None) – The number of terms to eliminate in each stage of multi-stage optimization.

  • optimize_kwargs – Keyword arguments to pass to scipy.optimize.minimize(). The default method is "L-BFGS-B".

Return type:

tuple[ndarray, ndarray, OptimizeResult]

Returns:

  • The optimized diagonal Coulomb matrices, as a Numpy array of shape (n_terms, 3, norb, norb).

  • The optimized orbital rotations, as a Numpy array of shape (n_terms, 2, norb, norb).

  • The OptimizeResult returned by scipy.optimize.minimize() in the last stage of the optimization.

Raises:

  • ValueError – The t2 amplitudes are complex-valued.

  • ValueError – max_terms is less than 1.

  • ValueError – multi_stage_start or multi_stage_step is less than 1.

  • ValueError – The alpha-alpha or beta-beta diag_coulomb_indices contain lower triangular indices.

  • ValueError – The initial guess has no terms. This includes the case where initial_guess is not specified and the exact factorization has no terms.

  • ValueError – The shapes of the initial guess tensors are inconsistent.