Computations involving regular matrix pencils

 regbalance!(A, E; maxiter = 100, tol = 1, pow2 = true) -> (Dl,Dr)

Balance the regular pair (A,E) by reducing the 1-norm of the matrix M := abs(A)+abs(E) by row and column balancing. This involves diagonal similarity transformations Dl*(A-λE)*Dr applied iteratively to M to make the rows and columns of Dl*M*Dr as close in norm as possible. The Sinkhorn–Knopp algorithm is used to reduce M to a doubly stochastic matrix.

The resulting Dl and Dr are diagonal scaling matrices. If the keyword argument pow2 = true is specified, then the components of the resulting optimal Dl and Dr are replaced by their nearest integer powers of 2. If pow2 = false, the optimal values Dl and Dr are returned. The resulting Dl*A*Dr and Dl*E*Dr overwrite A and E, respectively

The keyword argument tol = τ, with τ ≤ 1, specifies the tolerance used in the stopping criterion. The iterative process is stopped as soon as the incremental scalings are tol-close to the identity.

The keyword argument maxiter = k specifies the maximum number of iterations k allowed in the balancing algorithm.

Note: This function is based on the MATLAB function rowcolsums.m of [1], modified such that the scaling operations are directly applied to A and E.

[1] F.M.Dopico, M.C.Quintana and P. van Dooren, "Diagonal scalings for the eigenstructure of arbitrary pencils", SIMAX, 43:1213-1237, 2022.

 ev = ordeigvals(A)

Compute the vector ev of eigenvalues of a Schur matrix A in their order of appearance down the diagonal of A. ordeigvals is an order-preserving version of eigvals for triangular/quasitriangular matrices.

ordeigvals(A, B) -> (ev, α, β)

Compute the vector ev of generalized eigenvalues of the pair (A,B), with A a Schur matrix and B an upper triangular matrix, in their order of appearance down the diagonals of A and B. ordeigvals is an order-preserving version of eigvals for (triangular/quasi-upper-triangular, triangular) pairs of matrices. α is a complex vector and β is a real vector such that the generalized eigenvalues ev can be alternatively obtained with α./β.

isregular(A, E, γ; atol::Real = 0,  rtol::Real = atol > 0 ? 0 : n*ϵ) -> Bool

Test whether the matrix pencil A-λE is regular at λ = γ (i.e., A-λE is square and ${\small\det(A-λE) \neq 0}$). The underlying computational procedure checks the maximal rank of A-γE if γ is finite and of E if γ is infinite .

The keyword arguements atol and rtol specify the absolute and relative tolerances for the nonzero elements of A-γE, respectively. The default relative tolerance is n*ϵ, where n is the size of A, and ϵ is the machine epsilon of the element type of A.

isregular(A, E; atol1::Real = 0, atol2::Real = 0, rtol::Real=min(atol1,atol2)>0 ? 0 : n*ϵ) -> Bool

Test whether the matrix pencil A-λE is regular (i.e., A-λE is square and ${\small\det(A-λE) \not\equiv 0}$). The underlying computational procedure reduces the pencil A-λE to an appropriate Kronecker-like form, which provides information on the rank of A-λE.

The keyword arguements atol1, atol2 and rtol specify the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E, respectively. The default relative tolerance is n*ϵ, where n is the size of A, and ϵ is the machine epsilon of the element type of A.

isunimodular(A, E; atol1::Real = 0, atol2::Real = 0, rtol::Real=min(atol1,atol2)>0 ? 0 : n*ϵ) -> Bool

Test whether the matrix pencil A-λE is unimodular (i.e., A-λE is square, regular and det(A-λE) == constant). The underlying computational procedure reduces the pencil A-λE to an appropriate Kronecker-like form, which provides information to check the full rank of A-λE and the lack of finite eigenvalues.

The keyword arguements atol1, atol2 and rtol specify the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E, respectively. The default relative tolerance is n*ϵ, where n is the size of A, and ϵ is the machine epsilon of the element type of A.

fisplit(A, E, B, C; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Bt, Ct, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi |   *     |
    At - λEt = |--------|---------|, 
               |    O   | Af-λEf  |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (ni, nf).

(2) if finite_infinite = true, then

               | Af-λEf |   *    |
    At - λEt = |--------|--------|, 
               |   O    | Ai-λEi |

where the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE and the ni x ni subpencil Ai-λEi contains the infinite elementary divisors.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (nf, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

Bt = Q'*B, unless B = missing, in which case Bt = missing is returned, and Ct = C*Z, unless C = missing, in which case Ct = missing is returned .

fisplit!(A, E, Q, Z, B, C; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q1'*(A - λE)*Z1 using orthogonal or unitary transformation matrices Q1 and Z1 such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi |   *     |
    At - λEt = |--------|---------|, 
               |    O   | Af-λEf  |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (ni, nf).

(2) if finite_infinite = true, then

               | Af-λEf |   *    |
    At - λEt = |--------|--------|, 
               |   O    | Ai-λEi |

where the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE and the ni x ni subpencil Ai-λEi contains the infinite elementary divisors.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (nf, ni).

The reduced matrices At and Et are returned in A and E, respectively, while Q1'*B is returned in B, unless B = missing, and C*Z1, is returned in C, unless C = missing.

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations Q1 are accumulated in the matrix Q <- Q*Q1 if withQ = true. Otherwise, Q is unchanged. The performed right orthogonal or unitary transformations Z1 are accumulated in the matrix Z <- Z*Z1 if withZ = true. Otherwise, Z is unchanged.

sfisplit(A, E, B, C; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Bt, Ct, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = true, then

               | Ai1    *        *     |
    At - λEt = | O    Af-λEf     *     |
               | O      0     Ai2-λEi2 |

where the ni1 x ni1 upper triangular nonsingular matrix Ai1 and the ni2 x ni2 subpencil Ai2-λEi2 contain the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai2-λEi2 is in a staircase form, with Ai2 nonsingular and upper triangular and Ei2 nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai2-λEi2 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+2]-ν[nb-j+1] for j = 1, 2, ..., nb+1 is the number of infinite elementary divisors of degree j (with ν[0] := 0 and ν[nb+1] := ni1).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, nf, ni2).

(2) if finite_infinite = false, then

               | Ai1-λEi1    *      *  |
    At - λEt = | O         Af-λEf   *  |
               | O           0     Ai2 |

where the ni1 x ni1 subpencil Ai1-λEi1 and the upper triangular nonsingular matrix Ai2 contain the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai1-λEi1 is in a staircase form, with Ai1 nonsingular and upper triangular and Ei1 nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai1-λEi1 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 0, 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0 and ν[0] = ni2).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, nf, ni2).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

Bt = Q'*B, unless B = missing, in which case Bt = missing is returned, and Ct = C*Z, unless C = missing, in which case Ct = missing is returned .

sfisplit!(A, E, Q, Z, B, C; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q1'*(A - λE)*Z1 using orthogonal or unitary transformation matrices Q1 and Z1 such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = true, then

               | Ai1    *        *     |
    At - λEt = | O    Af-λEf     *     |
               | O      0     Ai2-λEi2 |

where the ni1 x ni1 upper triangular nonsingular matrix Ai1 and the ni2 x ni2 subpencil Ai2-λEi2 contain the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai2-λEi2 is in a staircase form, with Ai2 nonsingular and upper triangular and Ei2 nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai2-λEi2 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+2]-ν[nb-j+1] for j = 1, 2, ..., nb+1 is the number of infinite elementary divisors of degree j (with ν[0] := 0 and ν[nb+1] := ni1).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, nf, ni2).

(2) if finite_infinite = false, then

               | Ai1-λEi1    *      *  |
    At - λEt = | O         Af-λEf   *  |
               | O           0     Ai2 |

where the ni1 x ni1 subpencil Ai1-λEi1 and the upper triangular nonsingular matrix Ai2 contain the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai1-λEi1 is in a staircase form, with Ai1 nonsingular and upper triangular and Ei1 nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai1-λEi1 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 0, 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0 and ν[0] = ni2).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, nf, ni2).

The reduced matrices At and Et are returned in A and E, respectively, while Q1'*B is returned in B, unless B = missing, and C*Z1, is returned in C, unless C = missing.

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations Q1 are accumulated in the matrix Q <- Q*Q1 if withQ = true. Otherwise, Q is unchanged. The performed right orthogonal or unitary transformations Z1 are accumulated in the matrix Z <- Z*Z1 if withZ = true. Otherwise, Z is unchanged.

fihess(A, E; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi |   *     |
    At - λEt = |--------|---------|, 
               |    O   | Af-λEf  |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors and the nf x nf subpencil Af-λEf contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The subpencil Af-λEf is with Af in an upper Hessenberg form and Ef nonsingular and upper triangular.

The dimensions of the diagonal blocks are returned in blkdims = (ni, nf).

(2) if finite_infinite = true, then

               | Af-λEf |   *    |
    At - λEt = |--------|--------|, 
               |   O    | Ai-λEi |

where the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE and the ni x ni subpencil Ai-λEi contains the infinite elementary divisors.

The subpencil Af-λEf is with Af in an upper Hessenberg form and Ef nonsingular and upper triangular.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (nf, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

fischur(A, E; fast = true, finite_infinite = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et are in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi |   *     |
    At - λEt = |--------|---------|, 
               |    O   | Af-λEf  |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors and the nf x nf subpencil Af-λEf contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The subpencil Af-λEf is with the pair (Af,Ef) in a generalized Schur form, with Af (quasi) upper triangular and Ef nonsingular and upper triangular.

The dimensions of the diagonal blocks are returned in blkdims = (ni, nf).

(2) if finite_infinite = true, then

               | Af-λEf |   *    |
    At - λEt = |--------|--------|, 
               |   O    | Ai-λEi |

where the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE and the ni x ni subpencil Ai-λEi contains the infinite elementary divisors.

The subpencil Af-λEf is with the pair (Af,Ef) in a generalized Schur form, with Af (quasi) upper triangular and Ef nonsingular and upper triangular.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (nf, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

fischursep(A, E; smarg, disc = false, fast = true, finite_infinite = false, stable_unstable = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent block upper triangular form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et have separated infinite, stable and unstable eigenvalues with respect to a stability domain Cs defined by the stability margin parameter smarg and the stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts less than smarg, while if disc = true, Cs is the set of complex numbers with moduli less than smarg (i.e., the interior of a disc of radius smarg centered in the origin). If smarg = missing, the default value used is smarg = 0, if disc = false, and smarg = 1, if disc = true.

The pencil At - λEt results in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi   *      *    |
    At - λEt = |    O   A1-λE1   *    |
               |    0     0    A2-λE2 |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (ni, n1, n2).

(2) if finite_infinite = true, then

               | A1-λE1   *      *    |
    At - λEt = |    O   A2-λE2   *    |
               |    0     0    Ai-λEi |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (n1, n2, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

sfischursep(A, E; smarg, disc = false, fast = true, finite_infinite = false, stable_unstable = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Q, Z, ν, blkdims)

Reduce the regular matrix pencil A - λE to an equivalent block upper triangular form At - λEt = Q'*(A - λE)*Z using orthogonal or unitary transformation matrices Q and Z such that the transformed matrices At and Et have separated infinite, stable and unstable eigenvalues with respect to a stability domain Cs defined by the stability margin parameter smarg and the stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts less than smarg, while if disc = true, Cs is the set of complex numbers with moduli less than smarg (i.e., the interior of a disc of radius smarg centered in the origin). If smarg = missing, the default value used is smarg = 0, if disc = false, and smarg = 1, if disc = true.

The pencil At - λEt results in one of the following block upper-triangular forms:

(1) if finite_infinite = true, then

               | Ai1   *      *       *     |
    At - λEt = |  0  A1-λE1   *       *     |
               |  0    0    A2-λE2    *     |
               |  0    0      0    Ai2-λEi2 |

where the ni1 x ni1 matrix Ai1 and the ni2 x ni2 subpencil Ai2-λEi2 contain the infinite elementary divisors, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai2-λEi2 is in a staircase form, with Ai2 nonsingular and upper triangular and Ei2 nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai2-λEi2 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+2]-ν[nb-j+1] for j = 1, 2, ..., nb+1 is the number of infinite elementary divisors of degree j (with ν[0] := 0 and ν[nb+1] := ni1).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, n1, n2, ni2).

(2) if finite_infinite = false, then

               | Ai1-λEi1   *      *     *  |
               |    0     A1-λE1   *     *  |
    At - λEt = |    0       0    A2-λE2  *  |
               |    0       0      0    Ai2 |

where the ni1 x ni1 subpencil Ai1-λEi1 and the ni2 x ni2 upper triangular and nonsingular matrix Ai2 contain the infinite elementary divisors of A-λE, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai1-λEi1 is in a staircase form, with Ai1 nonsingular and upper triangular and Ei1 nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai1-λEi1 such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 0, 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0 and ν[0] = ni2).

The dimensions of the diagonal blocks are returned in blkdims = (ni1, n1, n2, ni2).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations are accumulated in the matrix Q if withQ = true. Otherwise, Q is set to nothing. The performed right orthogonal or unitary transformations are accumulated in the matrix Z if withZ = true. Otherwise, Z is set to nothing.

fiblkdiag(A, E, B, C; fast = true, finite_infinite = false, trinv = false, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Bt, Ct, Q, Z, ν, blkdims, sep)

Reduce the regular matrix pencil A - λE to an equivalent form At - λEt = Q*(A - λE)*Z using the transformation matrices Q and Z such that the transformed matrices At and Et are in one of the following block diagonal forms:

(1) if finite_infinite = false, then

               | Ai-λEi |   0     |
    At - λEt = |--------|---------|, 
               |    O   | Af-λEf  |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors and the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (ni, nf).

(2) if finite_infinite = true, then

               | Af-λEf |   0    |
    At - λEt = |--------|--------|, 
               |   O    | Ai-λEi |

where the nf x nf subpencil Af-λEf, with Ef nonsingular and upper triangular, contains the finite eigenvalues of the pencil A-λE and the ni x ni subpencil Ai-λEi contains the infinite elementary divisors.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (nf, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decomdiagpositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

If withQ = true, Q contains the left transformation matrix, if trinv = false, or its inverse, if trinv = true. If withQ = false, Q is set to nothing. If withZ = true, Z contains the right transformation matrix, if trinv = false, or its inverse, if trinv = true. If withZ = false, Z is set to nothing.

Bt = Q*B, unless B = missing, in which case Bt = missing is returned, and Ct = C*Z, unless C = missing, in which case Ct = missing is returned .

An estimation of the separation of the spectra of Ai-λEi and Af-λEf is returned in sep, where 0 < sep ≤ 1.

gsblkdiag(A, E, B, C; smarg, disc = false, fast = true, finite_infinite = false, stable_unstable = false, trinv = false, 
          atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (At, Et, Bt, Ct, Q, Z, ν, blkdims, sep)

Reduce the regular matrix pencil A - λE to an equivalent block diagonal triangular form At - λEt = Q*(A - λE)*Z using the transformation matrices Q and Z such that the transformed matrices At and Et have separated infinite, stable and unstable eigenvalues with respect to a stability domain Cs defined by the stability margin parameter smarg and the stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts less than smarg, while if disc = true, Cs is the set of complex numbers with moduli less than smarg (i.e., the interior of a disc of radius smarg centered in the origin). If smarg = missing, the default value used is smarg = 0, if disc = false, and smarg = 1, if disc = true.

The pencil At - λEt results in one of the following block upper-triangular forms:

(1) if finite_infinite = false, then

               | Ai-λEi   *      0    |
    At - λEt = |    O   A1-λE1   0    |
               |    0     0    A2-λE2 |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vector ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[i]-ν[i+1] for i = 1, 2, ..., nb is the number of infinite elementary divisors of degree i (with ν[nb+1] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (ni, n1, n2).

(2) if finite_infinite = true, then

               | A1-λE1   0      0    |
    At - λEt = |    O   A2-λE2   *    |
               |    0     0    Ai-λEi |

where the ni x ni subpencil Ai-λEi contains the infinite elementary divisors, the n1 x n1 subpencil A1-λE1 is with the pair (A1,E1) in a generalized Schur form, and the n2 x n2 subpencil A2-λE2 is with the pair (A2,E2) in a generalized Schur form. The pencil A1-λE1 has unstable finite eigenvalues and A2-λE2 has stable finite eigenvalues if stable_unstable = false, while A1-λE1 has stable finite eigenvalues and A2-λE2 has unstable finite eigenvalues if stable_unstable = true.

The subpencil Ai-λEi is in a staircase form, with Ai nonsingular and upper triangular and Ei nilpotent and upper triangular. The nb-dimensional vectors ν contains the dimensions of the diagonal blocks of the staircase form Ai-λEi such that i-th block has dimensions ν[i] x ν[i]. The difference ν[nb-j+1]-ν[nb-j] for j = 1, 2, ..., nb is the number of infinite elementary divisors of degree j (with ν[0] = 0).

The dimensions of the diagonal blocks are returned in blkdims = (n1, n2, ni).

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

If withQ = true, Q contains the left transformation matrix, if trinv = false, or its inverse, if trinv = true. If withQ = false, Q is set to nothing. If withZ = true, Z contains the left transformation matrix, if trinv = false, or its inverse, if trinv = true. If withZ = false, Z is set to nothing.

Bt = Q*B, unless B = missing, in which case Bt = missing is returned, and Ct = C*Z, unless C = missing, in which case Ct = missing is returned .

An estimation of the separation of the spectra of the two underlying diagonal blocks is returned in sep, where 0 ≤ sep ≤ 1. A value sep ≈ 0 indicates that A1-λE1 and A2-λE2 have some almost equal eigenvalues.

ssblkdiag(A, B, C; smarg, disc = false, stable_unstable = false, withQ = true, withZ = true) -> (At, Bt, Ct, Q, Z, blkdims, sep)

Reduce the regular matrix pencil A - λI to an equivalent block diagonal triangular form At - λI = Q*(A - λI)*Z using the transformation matrices Q and Z, where Q = inv(Z), such that the transformed matrix At have separated stable and unstable eigenvalues with respect to a stability domain Cs defined by the stability margin parameter smarg and the stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts less than smarg, while if disc = true, Cs is the set of complex numbers with moduli less than smarg (i.e., the interior of a disc of radius smarg centered in the origin). If smarg = missing, the default value used is smarg = 0, if disc = false, and smarg = 1, if disc = true. The matrix At results in the following block diagonal form

    At = | A1  0  |
         | 0   A2 |

where the n1 x n1 matrix A1 and the n2 x n2 matrix A2 are in Schur form. The matrix A1 has unstable eigenvalues and A2 has stable eigenvalues if stable_unstable = false, while A1 has stable eigenvalues and A2 has unstable eigenvalues if stable_unstable = true. The dimensions of the diagonal blocks are returned in blkdims = (n1, n2). If withQ = true, Q contains the left transformation matrix. If withQ = false, Q is set to nothing. If withZ = true, Z contains the right transformation matrix. If withZ = false, Z is set to nothing. Bt = Q*B, unless B = missing, in which case Bt = missing is returned, and Ct = C*Z, unless C = missing, in which case Ct = missing is returned . An estimation of the separation of the spectra of the two underlying diagonal blocks is returned in sep, where 0 ≤ sep ≤ 1. A value sep ≈ 0 indicates that A1 and A2 have some almost equal eigenvalues.

saloc(A, B; evals, sdeg, disc = false, atol1 = 0, atol2 = 0, rtol) -> (F, Scl, blkdims)

Compute for the pair (A,B), a matrix F such that all eigenvalues of the matrix A+B*F lie in the stability domain Cs specified by the stability degree parameter sdeg and stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts at most sdeg, while if disc = true, Cs is the set of complex numbers with moduli at most sdeg (i.e., the interior of a disc of radius sdeg centered in the origin). evals is a real or complex vector, which contains the desired eigenvalues of the matrix A+B*F within Cs. For real data A and B, evals must be a self-conjugated complex set to ensure that the resulting F is also a real matrix.

For a pair (A,B) with A of order n, the number of assignable eigenvalues is nc := n-nu, where nu is the number of fixed eigenvalues of A. The assignable eigenvalues are called the controllable eigenvalues, while the fixed eigenvalues are called the uncontrollable eigenvalues (these are the zeros of the pencil [A-λI B]). The spectrum allocation is achieved by successively replacing the controllable eigenvalues of A lying outside of the stability domain Cs with eigenvalues provided in evals. All eigenvalues of A lying in Cs are kept unalterred. If the number of specified eigenvalues in evals is less than the number of controllable eigenvalues of A outside of Cs (e.g., if evals = missing), then some of the controllable eigenvalues of A are assigned to the nearest values on the boundary of Cs. If sdeg = missing and evals = missing, the default value used for sdeg is -0.05 if disc = false and 0.95 if disc = true.

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of B, and the relative tolerance for the nonzero elements of A and B. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The resulting matrix Acl := Z'*(A+B*F)*Z in a Schur form, where Z is the orthogonal/unitary matrix used to obtain the matrix A+B*F in Schur form, has the form

       ( Ag  *   *  )     
 Acl = ( 0   Aa  *  ) 
       ( 0   0   Au )

where: Ag contains the ng eigenvalues of A in Cs, Aa contains the na assigned eigenvalues in Cs and Au contains nu uncontrollable eigenvalues of A lying outside Cs. The matrices Acl and Z and the vector α of eigenvalues of Acl (also of A+B*F) are returned in the Schur object Scl. The values of ng, na and nu are returned in the 3-dimensional vector blkdims = [ng, na, nu].

Method: The Schur method of [1], extended to possibly uncontrollable pairs, is employed.

References:

[1] A. Varga. A Schur method for pole assignment. IEEE Trans. on Automatic Control, vol. 26, pp. 517-519, 1981.

saloc(A, E, B; evals, sdeg, disc = false, atol1 = 0, atol2 = 0, atol3 = 0, rtol, sepinf = true, fast = true) -> (F, Scl, blkdims)

Compute for the pair (A-λE,B), with A-λE a regular pencil, a matrix F such that all finite eigenvalues of the pencil A+B*F-λE lie in the stability domain Cs specified by the stability degree parameter sdeg and stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts at most sdeg, while if disc = true, Cs is the set of complex numbers with moduli at most sdeg (i.e., the interior of a disc of radius sdeg centered in the origin). evals is a real or complex vector, which contains a set of finite desired eigenvalues for the pencil A+B*F-λE. For real data A, E, and B, evals must be a self-conjugated complex set to ensure that the resulting F is also a real matrix.

For a pair (A-λE,B) with A of order n, the number of assignable finite eigenvalues is nfc := n-ninf-nfu, where ninf is the number of infinite eigenvalues of A-λE and nfu is the number of fixed finite eigenvalues of A-λE. The assignable finite eigenvalues are called the controllable finite eigenvalues, while the fixed finite eigenvalues are called the uncontrollable finite eigenvalues (these are the finite zeros of the pencil [A-λE B]). The spectrum allocation is achieved by successively replacing the controllable finite eigenvalues of A-λE lying outside of the stability domain Cs with eigenvalues provided in evals. All finite eigenvalues of A-λE lying in Cs are kept unalterred. If the number of specified eigenvalues in evals is less than the number of controllable finite eigenvalues of A-λE outside of Cs (e.g., if evals = missing), then some of the controllable finite eigenvalues of A-λE are assigned to the nearest values on the boundary of Cs. If sdeg = missing and evals = missing, the default value used for sdeg is -0.05 if disc = false and 0.95 if disc = true.

The keyword arguments atol1, atol2, atol3, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, the absolute tolerance for the nonzero elements of B, and the relative tolerance for the nonzero elements of A, E and B. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The keyword argument sepinf specifies the option for a preliminary separation of the infinite eigenvalues of the pencil A-λE as follows: if sepinf = false, no separation of infinite eigenvalues is performed, while for sepinf = true (the default option), a preliminary separation of the infinite eigenvalues from the finite ones is performed. If E is nonsingular, then sepinf = false is recommended to be used. If E is numerically singular, then the option sepinf = false is used. The separation of finite and infinite eigenvalues is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The resulting pencil Acl-λEcl := Q'*(A+B*F-λE)*Z, where Q and Z are the orthogonal/unitary matrices used to obtain the pair (Acl,Ecl) in a generalized Schur form (GSF), has the form

            ( Ai-λEi    *        *       *      )     
 Acl-λEcl = (   0    Afg-λEfg    *       *      )  
            (   0       0     Afa-λEfa   *      )    
            (   0       0        0     Afu-λEfu )

where: Ai-λEi with Ai upper triangular and invertible and Ei upper triangular and nilpotent, contains the ninf infinite eigenvalues of A-λE; Afg-λEfg contains nfg finite eigenvalues of A-λE in Cs; Afa-λEfa contains nfa assigned finite generalized eigenvalues in Cs; and Afu-λEfu contains nfu uncontrollable finite eigenvalues of A-λE lying outside Cs. The matrices Acl, Ecl, Q, Z and the vectors α and β such that α./β are the generalized eigenvalues of the pair (Acl,Ecl) are returned in the GeneralizeSchur object Scl. The values of ninf, nfg, nfa and nfu are returned in the 4-dimensional vector blkdims = [ninf, nfg, nfa, nfu].

Method: For a pair (A-λE,B) with E = I, the Schur method of [1] is used, while for a general pair (A-λE,B) the generalized Schur method of [2] is used to solve the R-stabilzation problem.

References:

[1] A. Varga. A Schur method for pole assignment. IEEE Trans. on Automatic Control, vol. 26, pp. 517-519, 1981.

[2] A. Varga. On stabilization methods of descriptor systems. Systems & Control Letters, vol. 24, pp.133-138, 1995.

salocd(A, C; evals, sdeg, disc = false, atol1 = 0, atol2 = 0, rtol) -> (K, Scl, blkdims)

Compute for the pair (A,C), a matrix K such that all eigenvalues of the matrix A+K*C lie in the stability domain Cs specified by the stability degree parameter sdeg and stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts at most sdeg, while if disc = true, Cs is the set of complex numbers with moduli at most sdeg (i.e., the interior of a disc of radius sdeg centered in the origin). evals is a real or complex vector, which contains the desired eigenvalues of the matrix A+K*C within Cs. For real data A and C, evals must be a self-conjugated complex set to ensure that the resulting K is also a real matrix.

For a pair (A,C) with A of order n, the number of assignable eigenvalues is nc := n-nu, where nu is the number of fixed eigenvalues of A. The assignable eigenvalues are called the observable eigenvalues, while the fixed eigenvalues are called the unobservable eigenvalues (these are the zeros of the pencil [A-λI; C]). The spectrum allocation is achieved by successively replacing the observable eigenvalues of A lying outside of the stability domain Cs with eigenvalues provided in evals. All eigenvalues of A lying in Cs are kept unalterred. If the number of specified eigenvalues in evals is less than the number of observable eigenvalues of A outside of Cs (e.g., if evals = missing), then some of the observable eigenvalues of A are assigned to the nearest values on the boundary of Cs. If sdeg = missing and evals = missing, the default value used for sdeg is -0.05 if disc = false and 0.95 if disc = true.

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of C, and the relative tolerance for the nonzero elements of A and C. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The resulting matrix Acl := Z'*(A+K*C)*Z in a Schur form, where Z is the orthogonal/unitary matrix used to obtain the matrix A+K*C in Schur form, has the form

       ( Au  *   *  )     
 Acl = ( 0   Aa  *  ) 
       ( 0   0   Ag )

where: Au contains nu unobservable eigenvalues of A lying outside Cs, Aa contains the na assigned eigenvalues in Cs and Ag contains the ng eigenvalues of A in Cs. The matrices Acl and Z and the vector α of eigenvalues of Acl (also of A+K*C) are returned in the Schur object Scl. The values of nu, na and ng are returned in the 3-dimensional vector blkdims = [nu, na, ng].

Method: The Schur method of [1] is applied to the dual pair (A',C') (extended to possibly unobservable pairs).

References:

[1] A. Varga. A Schur method for pole assignment. IEEE Trans. on Automatic Control, vol. 26, pp. 517-519, 1981.

salocd(A, E, C; evals, sdeg, disc = false, atol1 = 0, atol2 = 0, atol3 = 0, rtol, sepinf = true, fast = true) -> (K, Scl, blkdims)

Compute for the pair (A-λE,C), with A-λE a regular pencil, a matrix K such that all finite eigenvalues of the pencil A+K*C-λE lie in the stability domain Cs specified by the stability degree parameter sdeg and stability type parameter disc. If disc = false, Cs is the set of complex numbers with real parts at most sdeg, while if disc = true, Cs is the set of complex numbers with moduli at most sdeg (i.e., the interior of a disc of radius sdeg centered in the origin). evals is a real or complex vector, which contains a set of finite desired eigenvalues for the pencil A+K*C-λE. For real data A, E, and B, evals must be a self-conjugated complex set to ensure that the resulting F is also a real matrix.

For a pair (A-λE,C) with A of order n, the number of assignable finite eigenvalues is nfc := n-ninf-nfu, where ninf is the number of infinite eigenvalues of A-λE and nfu is the number of fixed finite eigenvalues of A-λE. The assignable finite eigenvalues are called the observable finite eigenvalues, while the fixed finite eigenvalues are called the unobservable finite eigenvalues (these are the finite zeros of the pencil [A-λE; C]). The spectrum allocation is achieved by successively replacing the observable finite eigenvalues of A-λE lying outside of the stability domain Cs with eigenvalues provided in evals. All finite eigenvalues of A-λE lying in Cs are kept unalterred. If the number of specified eigenvalues in evals is less than the number of observable finite eigenvalues of A-λE outside of Cs (e.g., if evals = missing), then some of the observable finite eigenvalues of A-λE are assigned to the nearest values on the boundary of Cs. If sdeg = missing and evals = missing, the default value used for sdeg is -0.05 if disc = false and 0.95 if disc = true.

The keyword arguments atol1, atol2, , atol3, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, the absolute tolerance for the nonzero elements of C, and the relative tolerance for the nonzero elements of A, E and C. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The keyword argument sepinf specifies the option for a preliminary separation of the infinite eigenvalues of the pencil A-λE as follows: if sepinf = false, no separation of infinite eigenvalues is performed, while for sepinf = true (the default option), a preliminary separation of the infinite eigenvalues from the finite ones is performed. If E is nonsingular, then sepinf = false is recommended to be used. If E is numerically singular, then the option sepinf = false is used. The separation of finite and infinite eigenvalues is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The resulting pencil Acl-λEcl := Q'*(A+K*C-λE)*Z, where Q and Z are the orthogonal/unitary matrices used to obtain the pair (Acl,Ecl) in a generalized Schur form (GSF), has the form

            ( Afu-λEfu    *        *       *    )     
 Acl-λEcl = (   0      Afa-λEfa    *       *    )  
            (   0         0     Afg-λEfg   *    )    
            (   0         0        0     Ai-λEi )

where: Afu-λEfu contains nfu unobservable finite eigenvalues of A-λE lying outside Cs, Afa-λEfa contains nfa assigned finite generalized eigenvalues in Cs, Afg-λEfg contains nfg finite eigenvalues of A-λE in Cs, and Ai-λEi, with Ai upper triangular and invertible and Ei upper triangular and nilpotent, contains the ninf infinite eigenvalues of A-λE. The matrices Acl, Ecl, Q, Z and the vectors α and β such that α./β are the generalized eigenvalues of the pair (Acl,Ecl) are returned in GeneralizeSchur object Scl. The values of nfu, nfa, nfg and ninf and are returned in the 4-dimensional vector blkdims = [nfu, nfa, nfg, ninf].

Method: For a pair (A-λE,C) with E = I, the dual Schur method of [1] is used, while for a general pair (A-λE,C) the dual generalized Schur method of [2] is used to solve the R-stabilzation problem of [2] for the dual pair (A'-λE',C').

References:

[1] A. Varga. A Schur method for pole assignment. IEEE Trans. on Automatic Control, vol. 26, pp. 517-519, 1981.

[2] A. Varga. On stabilization methods of descriptor systems. Systems & Control Letters, vol. 24, pp.133-138, 1995.

salocinf(A, E, B; atol1 = 0, atol2 = 0, atol3 = 0, rtol, fast = true) -> (F, G, Scl, blkdims)

Compute for the controllable pair (A-λE,B), with A-λE a regular pencil, two matrices F and G such that all eigenvalues of the pencil A+B*F-λ(E+B*G) are infinite. For a pair (A-λE,B) with fixed (uncontrollable) finite eigenvalues, only the assignable (controllable) finite eigenvalues are moved to infinity.

For a pair (A-λE,B) with A of order n, the number of assignable infinite eigenvalues is nia := n-ninf-nfu, where ninf is the number of infinite eigenvalues of A-λE and nfu is the number of fixed finite eigenvalues of A-λE. The assignable finite eigenvalues are called the controllable finite eigenvalues, while the fixed finite eigenvalues are called the uncontrollable finite eigenvalues (these are the finite zeros of the pencil [A-λE B]). The spectrum allocation is achieved by successively replacing the controllable finite eigenvalues of A-λE with infinite eigenvalues. All infinite eigenvalues of A-λE are kept unalterred.

The keyword arguments atol1, atol2, atol3, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, the absolute tolerance for the nonzero elements of B, and the relative tolerance for the nonzero elements of A, E and B. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The preliminary separation of finite and infinite eigenvalues is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The resulting pencil Acl-λEcl := Q'*(A+B*F-λ(E+B*G))*Z, where Q and Z are the orthogonal/unitary matrices used to obtain the pair (Acl,Ecl) in a generalized Schur form (GSF), has the form

            ( Aig-λEig    *        *     )     
 Acl-λEcl = (   0      Aia-λEia    *     )  
            (   0         0     Afu-λEfu )

where: Aig-λEig with Aig upper triangular and invertible and Eig upper triangular and nilpotent, contains the ninf infinite eigenvalues of A-λE; Aia-λEia, with Aia upper triangular and invertible and Eia upper triangular and nilpotent, contains nia assigned infinite generalized eigenvalues; and Afu-λEfu, with the pair (Afu,Efu) in a generalized Schur form, contains nfu fixed (uncontrollable) finite eigenvalues of A-λE. The matrices Acl, Ecl, Q, Z and the vectors α and β such that α./β are the generalized eigenvalues of the pair (Acl,Ecl) are returned in the GeneralizeSchur object Scl. The values of ninf, nia and nfu are returned in the 3-dimensional vector blkdims = [ninf, nia, nfu].

Method: For a general pair (A-λE,B) the modified generalized Schur method of [1] is used to determine F and G such that the pair (A+B*F,E+B*G) has only infinite eigenvalues.

References:

[1] A. Varga. On stabilization methods of descriptor systems. Systems & Control Letters, vol. 24, pp.133-138, 1995.

salocinfd(A, E, C; atol1 = 0, atol2 = 0, atol3 = 0, rtol, sepinf = true, fast = true) -> (K, L, Scl, blkdims)

Compute for the pair (A-λE,C), with A-λE a regular pencil, the matrices K and L such that all eigenvalues of the pencil A+K*C-λ(E+L*C) are infinite. For a pair (A-λE,C) with fixed (unobservable) finite eigenvalues, only the assignable (observable) finite eigenvalues are moved to infinity.

For a pair (A-λE,C) with A of order n, the number of assignable infinite eigenvalues is nia := n-ninf-nfu, where ninf is the number of infinite eigenvalues of A-λE and nfu is the number of fixed finite eigenvalues of A-λE. The assignable finite eigenvalues are called the observable finite eigenvalues, while the fixed finite eigenvalues are called the unobservable finite eigenvalues (these are the finite zeros of the pencil [A-λE; C]). The spectrum allocation is achieved by successively replacing the observable finite eigenvalues of A-λE with infinite eigenvalues. All infinite eigenvalues of A-λE are kept unalterred.

The keyword arguments atol1, atol2, , atol3, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, the absolute tolerance for the nonzero elements of C, and the relative tolerance for the nonzero elements of A, E and C. The default relative tolerance is n*ϵ, where ϵ is the machine epsilon of the element type of A.

The preliminary separation of finite and infinite eigenvalues is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The resulting pencil Acl-λEcl := Q'*(A+K*C-λ(E+L*C))*Z, where Q and Z are the orthogonal/unitary matrices used to obtain the pair (Acl,Ecl) in a generalized Schur form (GSF), has the form

            ( Afu-λEfu    *        *     )     
 Acl-λEcl = (   0      Aia-λEia    *     )  
            (   0         0     Aig-λEig )

where: Afu-λEfu, with the pair (Afu,Efu) in a generalized Schur form, contains nfu fixed (unobservable) finite eigenvalues of A-λE, Aia-λEia, with Aia upper triangular and invertible and Eia upper triangular and nilpotent, contains nia assigned infinite generalized eigenvalues; Aig-λEig, with Aig upper triangular and invertible and Eig upper triangular and nilpotent, contains the ninf infinite eigenvalues of A-λE. The matrices Acl, Ecl, Q, Z and the vectors α and β such that α./β are the generalized eigenvalues of the pair (Acl,Ecl) are returned in the GeneralizeSchur object Scl. The values of nfu, nia and ninf and are returned in the 3-dimensional vector blkdims = [nfu, nia, ninf].

Method: For a general pair (A-λE,C) the dual of the modified generalized Schur method of [1] is used to determine K and L such that the pair (A+K*C,E+L*G) has only infinite eigenvalues.

References:

[1] A. Varga. On stabilization methods of descriptor systems. Systems & Control Letters, vol. 24, pp.133-138, 1995.

_qrE!(A, E, Q, B; withQ = true)

Reduce the regular matrix pencil A - λE to an equivalent form A1 - λE1 = Q1'*(A - λE) using an orthogonal or unitary transformation matrix Q1 such that the transformed matrix E1 is upper triangular. The reduction is performed using the QR-decomposition of E.

The performed left orthogonal or unitary transformations Q1 are accumulated in the matrix Q <- Q*Q1 if withQ = true. Otherwise, Q is unchanged.

Q1'*B is returned in B unless B = missing.

_svdlikeAE!(A, E, Q, Z, B, C; svdA = true, fast = true, atol1 = 0, atol2 = 0, rtol, withQ = true, withZ = true) -> (rE, rA22)

Reduce the regular matrix pencil A - λE to an equivalent form A1 - λE1 = Q1'*(A - λE)*Z1 using orthogonal or unitary transformation matrices Q1 and Z1 such that the transformed matrices A1 and E1 are, for svdA = true, in the following SVD-like coordinate form

               | A11-λE11 |  A12  |  A13  |
               |----------|-------|-------|
    A1 - λE1 = |    A21   |  A22  |   0   | ,
               |----------|-------|-------|
               |    A31   |   0   |   0   |

where the rE x rE matrix E11 and rA22 x rA22 matrix A22 are nosingular, and E11 and A22 are upper triangular, if fast = true, and diagonal, if fast = false.

If svdA = false, only E is reduced to SVD-like form and A1 - λE1 has the form

               | A11-λE11 |  A12  |
    A1 - λE1 = |----------|-------| , 
               |    A21   |  A22  |

where the rE x rE matrix E11 is nonsingular upper triangular, if fast = true, and diagonal, if fast = false, and A22 is unreduced and has rank rA22.

The keyword arguments atol1, atol2, and rtol, specify, respectively, the absolute tolerance for the nonzero elements of A, the absolute tolerance for the nonzero elements of E, and the relative tolerance for the nonzero elements of A and E.

The reduction is performed using rank decisions based on rank revealing QR-decompositions with column pivoting if fast = true or the more reliable SVD-decompositions if fast = false.

The performed left orthogonal or unitary transformations Q1 are accumulated in the matrix Q <- Q*Q1 if withQ = true. Otherwise, Q is unchanged. The performed right orthogonal or unitary transformations Z1 are accumulated in the matrix Z <- Z*Z1 if withZ = true. Otherwise, Z is unchanged.

Q1'*B is returned in B unless B = missing and C*Z1 is returned in C unless C = missing .