ffsim.linalg.givens_decomposition_slater

ffsim.linalg.givens_decomposition_slater(orbital_coeffs, tol=1e-12, *, max_givens=None, max_layers=None, **optimize_kwargs)[source]

Givens rotation decomposition for Slater determinant preparation.

Given the coefficient matrix of the occupied orbitals of a Slater determinant, returns a sequence of Givens rotations that, when applied to the electronic configuration \(\lvert 1 \cdots 1 0 \cdots 0 \rangle\) (with the first \(m\) orbitals occupied), prepares the Slater determinant. Here orbital_coeffs is an \(m \times n\) matrix whose rows are the \(m\) occupied orbitals expressed in a basis of \(n\) spatial orbitals; its rows are assumed to be orthonormal.

Unlike givens_decomposition(), this decomposition is specialized for state preparation: it only needs to prepare the \(m\) occupied orbitals rather than a full \(n \times n\) orbital rotation, so it uses at most \(m (n - m)\) Givens rotations arranged in a diamond-shaped pattern. The decomposition contains no diagonal phases, because a global phase and any rotation within the occupied space leave the prepared Slater determinant unchanged.

A Givens rotation is described by a 4-tuple \((c, s, i, j)\), where \(c\) is a real number, \(s\) is a complex number, and \(i\) and \(j\) are the (adjacent) indices of the orbitals being rotated.

Compression. By default this function returns an exact decomposition. If max_givens or max_layers is specified, the exact decomposition is trimmed to use at most that many Givens rotations or brickwork layers, respectively (never more than the exact decomposition already contains, so a near-identity matrix may use fewer rotations than the budget). The retained rotations lie at the beginning of the pattern, and their angles are numerically optimized to maximize the fidelity \(\lvert \det(A B^\dagger) \rvert^2\) between the prepared Slater determinant (occupied orbitals \(A\)) and the target (occupied orbitals \(B\)). The returned decomposition is then only approximate. When both max_givens and max_layers are given, the tighter of the two constraints is applied. Note that when the decomposition is compressed, tol is not respected: the optimized angles are chosen to best approximate the target Slater determinant, so the prepared state may differ from the target by more than tol.

Parameters:

  • orbital_coeffs (ndarray) – The \(m \times n\) matrix of occupied orbital coefficients.

  • tol (float) – Matrix entries smaller than this value will be treated as equal to zero when computing the exact decomposition (which the compressed path also starts from).

  • max_givens (int | None) – The maximum number of Givens rotations to use. If specified, the decomposition is compressed to use at most this many Givens rotations.

  • max_layers (int | None) – The maximum number of brickwork layers to use. If specified, the decomposition is compressed to use at most this many layers.

  • optimize_kwargs – Keyword arguments to pass to scipy.optimize.minimize(), which performs the optimization when the decomposition is compressed.

Return type:

list[tuple[float, complex, int, int]]

Returns:

A list containing the Givens rotations, each represented as a 4-tuple \((c, s, i, j)\).