schur ===== [ordered] Schur decomposition of matrix and pencils Calling Sequence ~~~~~~~~~~~~~~~~ :: [U,T] = schur(A) [U,dim [,T] ]=schur(A,flag) [U,dim [,T] ]=schur(A,extern1) [As,Es [,Q,Z]]=schur(A,E) [As,Es [,Z,dim]] = schur(A,E,flag) [Z,dim] = schur(A,E,flag) [As,Es [,Z,dim]]= schur(A,E,extern2) [Z,dim]= schur(A,E,extern2) Arguments ~~~~~~~~~ :A real or complex square matrix. : :E real or complex square matrix with same dimensions as `A`. : :flag character string ( `'c'` or `'d'`) : :extern1 an ``external'', see below : :extern2 an ``external'', see below : :U orthogonal or unitary square matrix : :Q orthogonal or unitary square matrix : :Z orthogonal or unitary square matrix : :T upper triangular or quasi-triangular square matrix : :As upper triangular or quasi-triangular square matrix : :Es upper triangular square matrix : :dim integer : Description ~~~~~~~~~~~ Schur forms, ordered Schur forms of matrices and pencils :MATRIX SCHUR FORM :Usual schur form: `[U,T] = schur(A)` produces a Schur matrix `T` and a unitary matrix `U` so that `A = U*T*U'` and `U'*U = eye(U)`. By itself, schur( `A`) returns `T`. If `A` is complex, the Complex Schur Form is returned in matrix `T`. The Complex Schur Form is upper triangular with the eigenvalues of `A` on the diagonal. If `A` is real, the Real Schur Form is returned. The Real Schur Form has the real eigenvalues on the diagonal and the complex eigenvalues in 2-by-2 blocks on the diagonal. : :Ordered Schur forms `[U,dim]=schur(A,'c')` returns an unitary matrix `U` which transforms `A` into schur form. In addition, the dim first columns of `U` make a basis of the eigenspace of `A` associated with eigenvalues with negative real parts (stable "continuous time" eigenspace). `[U,dim]=schur(A,'d')` returns an unitary matrix `U` which transforms `A` into schur form. In addition, the `dim` first columns of `U` span a basis of the eigenspace of `A` associated with eigenvalues with magnitude lower than 1 (stable "discrete time" eigenspace). `[U,dim]=schur(A,extern1)` returns an unitary matrix `U` which transforms `A` into schur form. In addition, the `dim` first columns of `U` span a basis of the eigenspace of `A` associated with the eigenvalues which are selected by the external function `extern1` (see external for details). This external can be described by a Scilab function or by C or Fortran procedure: :a Scilab function If `extern1` is described by a Scilab function, it should have the following calling sequence: `s=extern1(Ev)`, where `Ev` is an eigenvalue and `s` a boolean. : :a C or Fortran procedure If `extern1` is described by a C or Fortran function it should have the following calling sequence: `int extern1(double *EvR, double *EvI)` where `EvR` and `EvI` are eigenvalue real and complex parts. a true or non zero returned value stands for selected eigenvalue. : : : :PENCIL SCHUR FORMS :Usual Pencil Schur form `[As,Es] = schur(A,E)` produces a quasi triangular `As` matrix and a triangular `Es` matrix which are the generalized Schur form of the pair `A, E`. `[As,Es,Q,Z] = schur(A,E)` returns in addition two unitary matrices `Q` and `Z` such that `As=Q'*A*Z` and `Es=Q'*E*Z`. : :Ordered Schur forms: `[As,Es,Z,dim] = schur(A,E,'c')` returns the real generalized Schur form of the pencil `s*E-A`. In addition, the dim first columns of `Z` span a basis of the right eigenspace associated with eigenvalues with negative real parts (stable "continuous time" generalized eigenspace). `[As,Es,Z,dim] = schur(A,E,'d')` returns the real generalized Schur form of the pencil `s*E-A`. In addition, the dim first columns of `Z` make a basis of the right eigenspace associated with eigenvalues with magnitude lower than 1 (stable "discrete time" generalized eigenspace). `[As,Es,Z,dim] = schur(A,E,extern2)` returns the real generalized Schur form of the pencil `s*E-A`. In addition, the dim first columns of `Z` make a basis of the right eigenspace associated with eigenvalues of the pencil which are selected according to a rule which is given by the function `extern2`. (see external for details). This external can be described by a Scilab function or by C or Fortran procedure: :A Scilab function If `extern2` is described by a Scilab function, it should have the following calling sequence: `s=extern2(Alpha,Beta)`, where `Alpha` and `Beta` defines a generalized eigenvalue and `s` a boolean. : :C or Fortran procedure if external `extern2` is described by a C or a Fortran procedure, it should have the following calling sequence: `int extern2(double *AlphaR, double *AlphaI, double *Beta)` if `A` and `E` are real and `int extern2(double *AlphaR, double *AlphaI, double *BetaR, double *BetaI)` if `A` or `E` are complex. `Alpha`, and `Beta` defines the generalized eigenvalue. a true or non zero returned value stands for selected generalized eigenvalue. : : : References ~~~~~~~~~~ Matrix schur form computations are based on the Lapack routines DGEES and ZGEES. Pencil schur form computations are based on the Lapack routines DGGES and ZGGES. Examples ~~~~~~~~ :: //SCHUR FORM OF A MATRIX //---------------------- A=`diag`_([-0.9,-2,2,0.9]);X=`rand`_(A);A=`inv`_(X)*A*X; [U,T]=schur(A);T [U,dim,T]=schur(A,'c'); T(1:dim,1:dim) //stable cont. eigenvalues function t=mytest(Ev),t=`abs`_(Ev)<0.95,endfunction [U,dim,T]=schur(A,mytest); T(1:dim,1:dim) // The same function in C (a Compiler is required) `cd`_ TMPDIR; C=['int mytest(double *EvR, double *EvI) {' //the C code 'if (*EvR * *EvR + *EvI * *EvI < 0.9025) return 1;' 'else return 0; }';] `mputl`_(C,TMPDIR+'/mytest.c') //build and link lp=`ilib_for_link`_('mytest','mytest.c',[],'c'); `link`_(lp,'mytest','c'); //run it [U,dim,T]=schur(A,'mytest'); //SCHUR FORM OF A PENCIL //---------------------- F=[-1,%s, 0, 1; 0,-1,5-%s, 0; 0, 0,2+%s, 0; 1, 0, 0, -2+%s]; A=`coeff`_(F,0);E=`coeff`_(F,1); [As,Es,Q,Z]=schur(A,E); Q'*F*Z //It is As+%s*Es [As,Es,Z,dim] = schur(A,E,'c') function t=mytest(Alpha, Beta),t=`real`_(Alpha)<0,endfunction [As,Es,Z,dim] = schur(A,E,mytest) //the same function in Fortran (a Compiler is required) ftn=['integer function mytestf(ar,ai,b)' //the fortran code 'double precision ar,ai,b' 'mytestf=0' 'if(ar.lt.0.0d0) mytestf=1' 'end'] `mputl`_(' '+ftn,TMPDIR+'/mytestf.f') //build and link lp=`ilib_for_link`_('mytestf','mytestf.f',[],'F'); `link`_(lp,'mytestf','f'); //run it [As,Es,Z,dim] = schur(A,E,'mytestf') See Also ~~~~~~~~ + `spec`_ eigenvalues of matrices and pencils + `bdiag`_ block diagonalization, generalized eigenvectors + `ricc`_ Riccati equation + `pbig`_ eigen-projection + `psmall`_ spectral projection .. _pbig: pbig.html .. _ricc: ricc.html .. _bdiag: bdiag.html .. _psmall: psmall.html .. _spec: spec.html