Tensor-decomposition tools

This module contains functions for tensor decomposition methods.

backtransform_svd_vectors!(UaiX::AbstractArray{T,3}, R_occ, R_virt)

Transform SVD vectors $U^{iX}_a$ from a localized back to the canonical orbital basis.

Applies $U_{\mathrm{can}}[a,i,X] = R_v^T[a,a'] R_o^T[i,i'] U_{\mathrm{loc}}[a',i',X]$. If R_occ or R_virt are nothing, UaiX is returned unchanged.

calc_integrals_decomposition(EC::ECInfo)

Decompose $v_{pr}^{qs}$ as $v_p^{qL} v_r^{sL}$ and store as mmL.

Uses the ALPACA algorithm with a matrix-free interface that accesses elements of the $n^2 \times n^2$ integral matrix on demand directly from the mmapped integral array, avoiding materialization of the full dense matrix.

Diagonal elements $⟨pq|pq⟩$ are pre-computed and passed as ALPACADecomposition.PrincipalTriples to avoid scattered I/O via elements!.

calc_integrals_decomposition_ao(EC::ECInfo, cMO::AbstractMatrix)

Fit-free 3-index integrals for the AO-direct route: Cholesky-decompose the exact AO integrals of the ± supermatrix store and transform the Cholesky vectors to the MO basis cMO ($v_p^{qL} = C^{\dagger} v_{\mu}^{\nu L} C$), saved as mmL.

The decomposition reads the ± store DIRECTLY, element-wise (PMIntegralMatrix): no jointly-packed array and no MO integral set is formed at any point. If I/O becomes a bottleneck, one could implement an on-the-fly decomposition of original AO integrals.

get_localization_rotations(EC::ECInfo)

Compute localization rotation matrices if EC.options.cc.localize is true and a molecular system is available.

Returns (R_occ, R_virt) where R_occ (nocc × nocc) and R_virt (nvirt × nvirt) are orthogonal rotation matrices from canonical to localized orbitals, or (nothing, nothing) if localization is not used.

If localization is requested but no molecular system is set up (FCIDUMP-only), prints a warning and returns (nothing, nothing).

prepare_doubles_for_decomposition(EC::ECInfo, T2::AbstractArray{T,4}; permuted=false, R_occ=nothing, R_virt=nothing)

Prepare doubles amplitudes for SVD decomposition.

Transforms $T^{ij}_{ab}$ to a localized orbital basis (if localization is enabled and a molecular system is available), permutes to $T^i_a{}^j_b$ layout, and reshapes to a flat $[ai,bj]$ matrix.

If permuted=false (default), T2 is in $[a,b,i,j]$ (vvoo) layout and will be permuted to $[a,i,b,j]$. If permuted=true, T2 is already in $[a,i,b,j]$ layout.

Pre-computed rotation matrices can be passed via R_occ/R_virt to avoid recomputing them when multiple decompositions share the same localization.

Returns

(T2_flat, R_occ, R_virt) where T2_flat is ready for svd_decompose and R_occ/R_virt are the rotation matrices (or nothing). Pass them to backtransform_svd_vectors! after decomposition.

svd_decompose(Amat, tol=1e-6; method=:llama, pivotol=0.0, pivotol_mode=:maxdim, verbose=true, description="")

SVD-decompose A[ξ,ξ'] as $U^{X}_{ξ} Σ_X δ_{XY} V^{Y}_{ξ'}$. Return $U^{X}_{ξ}$ as U[ξ,X] and $Σ_X$ for $Σ_X$ > tol.

method selects the algorithm: :llama (default) or :dense. pivotol if > 0 overrides LLAMA's pivot tolerance (ignored for :dense). pivotol_mode controls automatic pivot tolerance: :maxdim or :adaptive.

svd_decompose(Amat, nvirt, nocc, tol=1e-6; method=:llama, pivotol=0.0, pivotol_mode=:maxdim, verbose=true, description="")

SVD-decompose A[ai,ξ] as $U^{iX}_a Σ_X δ_{XY} V^{Y}_{ξ}$. Return $U^{iX}_a$ as U[a,i,X] for $Σ_X$ > tol.

method selects the algorithm: :llama (default) or :dense. pivotol if > 0 overrides LLAMA's pivot tolerance (ignored for :dense). pivotol_mode controls automatic pivot tolerance: :maxdim or :adaptive.

svd_decompose(EC::ECInfo, Amat, nvirt, nocc, tol; description="", kwargs...)

SVD-decompose A[ai,ξ] reading decomposition options from EC.options.cc.

Reads method (dense vs llama), pivotol, and pivotol_mode from EC options and forwards to the plain svd_decompose.

For doubles-type quantities, use prepare_doubles_for_decomposition before calling this function and backtransform_svd_vectors! afterwards.

Arguments

• EC::ECInfo: Electronic structure information object
• Amat: Matrix to decompose, shape (nvirt*nocc, ξ)
• nvirt: Number of virtual orbitals
• nocc: Number of occupied orbitals
• tol: SVD threshold

Keyword Arguments

• description="": Description for output
• Additional kwargs are forwarded to the underlying svd_decompose

Returns

• Array{T,3}: U[a,i,X] decomposition vectors

svd_decompose_dense(Amat, tol=1e-6; verbose=true, description="")

SVD-decompose A[ξ,ξ'] as $U^{X}_{ξ} Σ_X δ_{XY} V^{Y}_{ξ'}$. using full dense SVD. Return $U^{X}_{ξ}$ as U[ξ,X] and $Σ_X$ for $Σ_X$ > tol

svd_decompose_dense(Amat, nvirt, nocc, tol=1e-6; verbose=true, description="")

SVD-decompose A[ai,ξ] as $U^{iX}_a Σ_X δ_{XY} V^{Y}_{ξ}$ using full dense SVD. Return $U^{iX}_a$ as U[a,i,X] for $Σ_X$ > tol

svd_decompose_llama(Amat, tol=1e-6; pivotol=0.0, pivotol_mode=:maxdim, verbose=true, description="")

SVD-decompose A[ξ,ξ'] as $U^{X}_{ξ} Σ_X δ_{XY} V^{Y}_{ξ'}$ using LLAMA low-rank approximation. Return $U^{X}_{ξ}$ as U[ξ,X] and $Σ_X$ for $Σ_X$ > tol. If pivotol > 0, it overrides LLAMA's pivot tolerance. Otherwise, pivotol_mode controls the computed pivot tolerance: :maxdim (default) uses tol/sqrt(max(m,n)), :adaptive delegates to LLAMA's internal logic.

svd_decompose_llama(Amat, nvirt, nocc, tol=1e-6; pivotol=0.0, pivotol_mode=:maxdim, verbose=true, description="")

SVD-decompose A[ai,ξ] as $U^{iX}_a Σ_X δ_{XY} V^{Y}_{ξ}$ using LLAMA low-rank approximation. Return $U^{iX}_a$ as U[a,i,X] for $Σ_X$ > tol. If pivotol > 0, it overrides LLAMA's pivot tolerance. Otherwise, pivotol_mode controls the computed pivot tolerance: :maxdim (default) uses tol/sqrt(max(m,n)), :adaptive delegates to LLAMA's internal logic.

IntegralMatrix{T} <: AbstractALPACAMatrix{T}

Matrix-free representation of the two-electron integral matrix for ALPACA decomposition.

Uses the raw integral array from integ2_ss(EC.fd) directly (mmapped, physicist notation order, upper triangular storage for the last two indices): int2[p, q, tri(r,s)] = $v_{pq}^{rs}$ with $r ≤ s$.

The matrix has compound indices $I = (r-1) n + p$ and $J = (s-1) n + q$ (column-major order), with elements $M_{IJ} = v_{pq}^{rs} = ⟨pq|rs⟩$.

The matrix is symmetric: $M^T = M$ (complex symmetric for complex MOs).

PMIntegralMatrix{T} <: AbstractALPACAMatrix{T}

The AO integral matrix $M_{(pr),(qs)} = v_{pq}^{rs}$ served element-wise from the ± supermatrix store: a requested column is reconstructed on the fly through pm_vs_va, a ket swap reduced to a bra swap by the exchange symmetry $v_{pq}^{rs} = v_{qp}^{sr}$. Nothing is materialized.

_check_llama_reconstruction(Amat, Q, tol, description) -> Float64

Check the actual reconstruction error $\|A - Q Q^H A\|$ after LLAMA decomposition and warn if it exceeds the requested tolerance. Returns the reconstruction error.

_compute_pivotol(Amat, tol, pivotol, pivotol_mode)

Compute the pivot tolerance for LLAMA based on the mode. If pivotol > 0, use it directly (manual override). Otherwise, use the mode:

• :maxdim → tol / sqrt(max(size(A)...))
• :adaptive → NaN (let LLAMA decide internally)