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

[jvdp1]

Thank you @perazz . It is a nice addition. I only have a few minor comments. So, it is close to be ready to be merged IMO

[perazz]

Thanks for the reviews @jvdp1, looks much better now. Regarding the eigenvalues, I'm open to changing the API

Sorry I just realized we had the approach in place for eigs. So, I implemented the same: option for real eigenvalues request; it will raise an error if any have non-zero imaginary component

[jvdp1]

Thank you @perazz . LGTM. It is ready to be merged IMO

[perazz]

Thank you @jvdp1, let's wait another couple of days, and then merge if there are no further comments.