linalg: Schur decomposition

[perazz]

Compute the Schur decomposition of a real or complex square matrix: $A = Z T Z^H$.

Proposed implementation

• call schur(A, T, Z [, eigvals] [, overwrite_a] [, storage] [, err]) : subroutine interface
• call schur_space(A, lwork [, err]) query internal storage size for pre-allocation.

Key facts

• The Schur decomposition is based on LAPACK's General Schur decomposition (*GEES) and eigenvalue sorting mechanisms.
• The output matrix $T$ is upper-triangular for complex matrices and quasi-upper-triangular for real matrices, with possible $2 \times 2$ blocks on the diagonal.
• Optionally, the user may request eigenvalues of $A$, which are the diagonal elements of $T$.
• The function supports an overwrite_a flag (default: .false.). If .true., and storage is user-provided, the input matrix a will be overwritten, avoiding memory allocation.

Progress

• base implementation
• tests
• documentation
• submodule
• examples
• workspace size evaluation

Prior art

• Numpy: not available
• Scipy: T, Z = schur(a, output='real', lwork=None, overwrite_a=False, sort=None, check_finite=True)

cc: @fortran-lang/stdlib @jvdp1 @jalvesz @loiseaujc