GenericSchur

https://ralphas.github.io/GenericSchur.jl/stable
Admin
GenericSchur is a Julia package for eigen-analysis and Schur decomposition of non-symmetric real and...
Tokens:3,696
Snippets:36
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Compute Schur decomposition

Source: https://ralphas.github.io/GenericSchur.jl/stable

Example of how to compute the Schur decomposition using the schur wrapper.

```julia
A = your_matrix_generator() + 0im # in case you start with a real matrix
S = schur(A)
```

--------------------------------

### balance! (GenericSchur.balance!)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Balances a square matrix to improve stability of eigen-analysis. Optionally permutes rows and columns to block form and scales diagonal elements to enhance accuracy.

```APIDOC
## GenericSchur.balance!

### Description
Balance a square matrix so that various operations are more stable. If `permute`, then row and column permutations are found such that `Abal` has the block form `[T₁ X Y; 0 C Z; 0 0 T₂]` where `T₁` and `T₂` are upper-triangular. If `scale`, then a diagonal similarity transform using powers of 2 is found such that the 1-norm of the `C` block (or the whole of `Abal`, if not permuting) is near unity. The transformations are encoded into `B` so that they can be inverted for eigenvectors, etc. Balancing typically improves the accuracy of eigen-analysis.

### Signature
`balance!(A; scale=true, permute=true) => Abal, B::Balancer`

### Parameters
- **A** - The matrix to balance.
- **scale** (Bool, Optional) - Whether to apply scaling.
- **permute** (Bool, Optional) - Whether to apply permutation.

### Returns
- **Abal** - The balanced matrix.
- **B** (Balancer) - Balancer object encoding transformations for inversion.

```

--------------------------------

### Balance matrix for improved accuracy

Source: https://ralphas.github.io/GenericSchur.jl/stable

Using the balance! function to improve eigenvalue and eigenvector accuracy via similarity transform.

```julia
Ab, B = balance!(copy(A))
S = schur(Ab)
v = eigvecs(S)
lmul!(B, v) # to get the eigenvectors of A
```

--------------------------------

### triangularize (GenericSchur.triangularize)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Converts a real quasi-triangular Schur decomposition into a complex triangular Schur decomposition.

```APIDOC
## GenericSchur.triangularize

### Description
Convert a (standard-form) quasi-triangular real Schur factorization into a triangular complex Schur factorization.

### Function
`triangularize(S::Schur{T}) => Schur{complex{T)}`

### Parameters
- **S::Schur{T}** - The real quasi-triangular Schur factorization.

### Returns
- **Schur{complex{T}}** - The complex triangular Schur factorization.

```

--------------------------------

### GenericSchur.balance! Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Balances a square matrix to improve stability for eigen-analysis. The transformations are stored in a Balancer object for later inversion.

```julia
balance!(A; scale=true, permute=true) => Abal, B::Balancer
```

--------------------------------

### GenericSchur.gschur! Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Destructive versions of the generic Schur decomposition methods.

```julia
gschur!(A::StridedMatrix) -> F::Schur
```

```julia
gschur!(H::Hessenberg, Z) -> F::Schur
```

--------------------------------

### Extract eigenvectors from Schur factorization

Source: https://ralphas.github.io/GenericSchur.jl/stable

How to obtain right and left eigenvectors from a complex Schur factorization.

```julia
S = schur(A)
VR = eigvecs(S)
VL = eigvecs(S,left=true)
```

--------------------------------

### gschur! (GenericSchur.gschur!)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Destructive generic Schur decomposition for a strided matrix or Hessenberg matrix, updating the unitary transformations when a matrix Z is provided.

```APIDOC
## GenericSchur.gschur!

### Description
Destructive version of `gschur` (q.v.). Compute the Schur decomposition of a strided matrix or Hessenberg matrix, updating unitary transformations if `Z` is provided.

### Functions
`gschur!(A::StridedMatrix) -> F::Schur`

`gschur!(H::Hessenberg, Z) -> F::Schur`

### Parameters
- **A::StridedMatrix** - The matrix to decompose.
- **H::Hessenberg** - A Hessenberg matrix; subdiagonals must be real.
- **Z** - Optional matrix updated with the unitary transformations.

### Returns
The Schur decomposition `F::Schur` of the input.

```

--------------------------------

### GenericSchur.triangularize Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Converts a real quasi-triangular Schur factorization into a complex triangular Schur factorization.

```julia
triangularize(S::Schur{T}) => Schur{complex{T})
```

--------------------------------

### eigvalscond (GenericSchur.eigvalscond)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Estimates the reciprocal of the condition number for a set of leading eigenvalues of a Schur decomposition.

```APIDOC
## GenericSchur.eigvalscond (Function)

### Description
Estimate the reciprocal of the condition number of the `nsub` leading eigenvalues of `S`. (Use `ordschur` to move a subspace of interest to the front of `S`.)

### Function
`eigvalscond(S::Schur,nsub::Integer) => Real`

### Parameters
- **S::Schur** - The Schur decomposition.
- **nsub::Integer** - The number of leading eigenvalues to consider.

### Returns
- **Real** - The estimated reciprocal condition number.

---

### Alternative Function for Generalized Schur
`eigvalscond(S::GeneralizedSchur, nsub) => pl, pr`

### Description
Computes approx. reciprocal norms of projectors on left/right subspaces associated w/ leading `nsub`×`nsub` block of `S`. Use `ordschur` to select eigenvalues of interest. An approximate bound on avg. absolute error of associated eigenvalues is `ϵ * norm(vcat(A,B)) / pl`. See LAPACK documentation for further details.

### Parameters
- **S::GeneralizedSchur** - The Generalized Schur decomposition.
- **nsub** - The number of leading eigenvalues to consider.

### Returns
- **pl** - Reciprocal norm of projector on left subspace.
- **pr** - Reciprocal norm of projector on right subspace.

```

--------------------------------

### GenericSchur.gschur Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Computes the Schur factorization of a matrix using a generic implementation.

```julia
gschur(A::StridedMatrix) -> F::Schur
```

--------------------------------

### Complex Schur decomposition definition

Source: https://ralphas.github.io/GenericSchur.jl/stable

The mathematical definition of the complex Schur decomposition provided by the package.

```julia
A::StridedMatrix{C} where {C <: Complex} == Z * T * adjoint(Z)
```

--------------------------------

### Real Schur decomposition definition

Source: https://ralphas.github.io/GenericSchur.jl/stable

The mathematical definition of the quasi-triangular real Schur decomposition.

```julia
A::StridedMatrix{R} where {R <: Real} == Z * T * transpose(Z)
```

--------------------------------

### LinearAlgebra.eigvecs Method

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Computes right or left eigenvectors from a complex Schur decomposition, returned as columns of a matrix.

```julia
eigvecs(S::Schur{Complex{<:AbstractFloat}}; left=false) -> Matrix
```

--------------------------------

### GenericSchur.eigvalscond Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Estimates the reciprocal condition number for eigenvalues of Schur decompositions.

```julia
eigvalscond(S::Schur,nsub::Integer) => Real
```

```julia
eigvalscond(S::GeneralizedSchur, nsub) => pl, pr
```

--------------------------------

### eigvecs (LinearAlgebra.eigvecs)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Computes eigenvectors from a Schur decomposition, returning right or left eigenvectors as columns of a matrix ordered to match the eigenvalues.

```APIDOC
## LinearAlgebra.eigvecs (Method)

### Description
Compute right or left eigenvectors from a Schur decomposition. Eigenvectors are returned as columns of a matrix, ordered to match `S.values`. The returned eigenvectors have unit Euclidean norm, and the largest elements are real.

### Function
`eigvecs(S::Schur{Complex{<:AbstractFloat}}; left=false) -> Matrix`

### Parameters
- **S::Schur{Complex{<:AbstractFloat}}** - The Schur decomposition.
- **left** (Bool, Optional, - Whether to compute left eigenvectors (default: right).

### Returns
- **Matrix** - Eigenvectors as columns, in Euclidean norm and largest elements real.

```

--------------------------------

### subspacesep (GenericSchur.subspacesep)

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Estimates the reciprocal condition of the separation angle for an invariant subspace in a Schur decomposition.

```APIDOC
## GenericSchur.subspacesep

### Description
Estimate the reciprocal condition of the separation angle for the invariant subspace corresponding to the leading block of size `nsub` of a Schur decomposition. (Use `ordschur` to move a subspace of interest to the front of `S`.)

### Function
`subspacesep(S::Schur,nsub::Integer) => Real`

### Parameters
- **S::Schur** - The Schur decomposition.
- **nsub::Integer** - The size of the leading block.

### Returns
- **Real** - The reciprocal condition of the separation angle.

```

--------------------------------

### GenericSchur.subspacesep Function

Source: https://ralphas.github.io/GenericSchur.jl/stable/library

Estimates the reciprocal condition of the separation angle for an invariant subspace.

```julia
subspacesep(S::Schur,nsub::Integer) => Real
```
Tokens:
Raw