archive/share/trash/eigen.usg

   1
   2                  This is the file  EIGEN USAGE DSK:SHARE; .
   3
   4        The EIGEN package is described in this file.  The source code
   5 is in the file EIGEN > DSK:SHARE; and the fastload file is
   6 EIGEN FASL DSK;SHARE; .  (You can load this one using MACSYMA's LOADFILE
   7 command, i.e. LOADFILE(EIGEN,FASL,DSK,SHARE); .  If you access the FASL
   8 file via the functions EIGENVALUES or EIGENVECTORS, the FASL file will
   9 autoload.)  The DEMO file is EIGEN DEMO DSK:SHARE; .  You can BATCH or DEMO
  10 this file, i.e. BATCH(EIGEN,DEMO,DSK,SHARE); or DEMO(EIGEN,DEMO,DSK,SHARE); .
  11 Note that in the DEMO mode you should hit the space key at each step...
  12
  13        The new EIGEN package is written by Yekta G"\bursel (YEKTA@MIT-MC) and
  14 is faster and more memory efficient than the old EIGEN package.  It also is
  15 able to handle multiple eigenvalues and the eigenvectors corresponding
  16 to those eigenvalues.  It will work with any square matrix ( not necessarily
  17 symmetric or hermitian ) and will tell whether the matrix is diagonalizable.
  18 The calculated eigenvectors and the unit eigenvectors of the matrix are the
  19 RIGHT eigenvectors and the RIGHT unit eigenvectors respectively.
  20 ( You should be aware of the fact that this program uses the MACSYMA functions
  21 SOLVE and ALGSYS and if SOLVE can not find the roots of the characteristic
  22 polynomial of the matrix or if it generates a rather messy solution the
  23 EIGEN package may not produce any useful results.  More info on this will be
  24 given in the description of the commands...  This package is DESIGNED to try
  25 to get the EXACT solutions to the eigenvalue and eigenvector problems.  If the
  26 matrices you have contain FLOATING point numbers, it may not be able to solve
  27 your problem.  You should use the IMSL eigenvalue and eigenvector package for
  28 numerical matrices with floating point numbers.  These excellent routines will
  29 find the APPROXIMATE solutions for numerical matrices with floating point
  30 numbers.  See MACSYMA Manual Version 10, Volume 2, Page V2-4-78.)
  31
  32
  33         Description of the functions :
  34
  35 CONJUGATE(X) returns the complex conjugate of its argument.
  36         ( Note that %I's in the expressions should be explicit, since there is
  37         no complex variable declaration in MACSYMA at the present time.  This
  38         is true for all the functions in this package...)
  39
  40
  41 INNERPRODUCT(X,Y) takes two LISTS of equal length as its arguments and
  42         returns their inner ( scalar ) product defined by
  43         (Complex Conjugate of X).Y ( The "dot" operation is the same
  44         as the usual one defined for vectors. ) .
  45
  46
  47 UNITVECTOR(X) takes a LIST as its argument and returns a  unit list.
  48         ( i.e. a list with unit magnitude. )
  49
  50
  51 COLUMNVECTOR(X) takes a LIST as its argument and returns a column vector the
  52         components of which are the elements of the list.  The first element is
  53         the first component,...etc...( This is useful if you want to use parts
  54         of the outputs of the functions in this package in matrix calculations.
  55         ..)
  56
  57
  58 GRAMSCHMIDT(X) takes a LIST of lists the sublists of which are of
  59         equal length and not necessarily orthogonal ( with respect to the
  60         innerproduct defined above ) as its argument and returns a similar
  61         list each sublist of which is orthogonal to  all others.
  62         ( Returned results may contain integers that are factored.
  63         This is due to the fact that the MACSYMA function FACTOR is
  64         used to simplify each substage of the Gram-Schmidt algorithm.
  65         This prevents the expressions from getting very messy and
  66         helps to reduce the sizes of the numbers that are produced
  67         along the way. )
  68
  69
  70 EIGENVALUES(MAT) takes a MATRIX as its argument and returns a list of
  71         lists the first sublist of which is the list of eigenvalues of
  72         the matrix and the other sublist of which is the list of the
  73         multiplicities of the eigenvalues in the corresponding order.
  74         { The MACSYMA function SOLVE is used here to find the roots of
  75         the characteristic polynomial of the matrix.  Sometimes SOLVE
  76         may not be able to find the roots of the polynomial;in that
  77         case nothing in this package except CONJUGATE, INNERPRODUCT,
  78         UNITVECTOR, COLUMNVECTOR and GRAMSCHMIDT will work unless
  79         you know the eigenvalues.
  80         In some cases SOLVE may generate very messy eigenvalues.  You may
  81         want to simplify the answers yourself before you go on.  There
  82         are provisions for this and they will be explained below.
  83         ( This usually happens when SOLVE returns a not-so-obviously
  84         real expression for an eigenvalue which is supposed to be real...)}
  85
  86
  87 EIGENVECTORS(MAT) takes a MATRIX as its argument and returns a list of
  88         lists the first sublist of which is the output of the EIGENVALUES
  89         command and the other sublists of which are the eigenvectors
  90         of the matrix corresponding to those eigenvalues respectively.
  91         The flags that affect this function are :
  92
  93         NONDIAGONALIZABLE[FALSE] will be set to TRUE or FALSE depending
  94         on whether the matrix is nondiagonalizable or diagonalizable after
  95         an EIGENVECTORS command is executed.
  96
  97         HERMITIANMATRIX[FALSE] If set to TRUE will cause the degenerate
  98         eigenvectors of the hermitian matrix to be orthogonalized using
  99         the Gram-Schmidt algorithm.
 100
 101         KNOWNEIGVALS[FALSE] If set to TRUE the EIGEN package will assume
 102         the eigenvalues of the matrix are known to the user and stored
 103         under the global name LISTEIGVALS.  LISTEIGVALS should be set to
 104         a list similar to the output of the EIGENVALUES command.
 105         ( The MACSYMA function ALGSYS is used here to solve for the
 106         eigenvectors. Sometimes if the eigenvalues are messy, ALGSYS may
 107         not be able to produce a solution.  In that case you are advised
 108         to try to simplify the eigenvalues by first finding them using
 109         EIGENVALUES command and then using whatever marvelous tricks you
 110         might have to reduce them to something simpler.  You can then use
 111         the KNOWNEIGVALS flag to proceed further. )
 112
 113
 114
 115 UNITEIGENVECTORS(MAT) takes a MATRIX as its argument and returns a list of
 116         lists the first sublist of which is the output of the EIGENVALUES
 117         command and the other sublists of which are the unit eigenvectors
 118         of the matrix corresponding to those eigenvalues respectively.
 119         The flags mentioned in the description of the EIGENVECTORS command
 120         have the same effects in this one as well.  In addition there is one
 121         more flag which may be useful :
 122
 123         KNOWNEIGVECTS[FALSE] If set to TRUE the EIGEN package will assume that
 124         the eigenvectors of the matrix are known to the user and are stored
 125         under the global name LISTEIGVECTS.  LISTEIGVECTS should be set to
 126         a list similar to the output of the EIGENVECTORS command.
 127         ( If KNOWNEIGVECTS is set to TRUE and the list of eigenvectors is
 128         given the setting of the flag NONDIAGONALIZABLE may not be correct.
 129         If that is the case please set it to the correct value.  The author
 130         assumes that the user knows what he is doing and will not try to
 131         diagonalize a matrix the eigenvectors of which do not span the
 132         vector space of the appropriate dimension...)
 133
 134
 135 SIMILARITYTRANSFORM(MAT) takes a MATRIX as its argument and returns a list
 136         which is the output of the UNITEIGENVECTORS command.  In addition if
 137         the flag NONDIAGONALIZABLE is FALSE two global matrices LEFTMATRIX
 138         and RIGHTMATRIX will be generated.  These matrices have the  property
 139         that LEFTMATRIX.MAT.RIGHTMATRIX is a  diagonal matrix with the
 140         eigenvalues of MAT on the diagonal.  If NONDIAGONALIZABLE
 141         is TRUE these two matrices will not be generated.
 142         If the flag HERMITIANMATRIX is TRUE then LEFTMATRIX is the
 143         complex conjugate of the transpose of  RIGHTMATRIX.  Otherwise
 144         LEFTMATRIX is the inverse of RIGHTMATRIX.  RIGHTMATRIX
 145         is the matrix the columns of which are the unit eigenvectors of MAT.
 146         The other flags have the same effects since SIMILARITYTRANSFORM
 147         calls the other functions in the package in order to be able to
 148         form RIGHTMATRIX...
 149
 150
 151                 Finally, for some of you who may think that the names of the
 152         functions are too long, I also made shorter names...( In the following
 153         list " := "  means  "is equivalent to" ...). Note that using these may
 154         make your code pretty unreadable, you'll save 50% in typing though.
 155
 156 CONJ(X):= CONJUGATE(X)
 157
 158 INPROD(X,Y):= INNERPRODUCT(X,Y)
 159
 160 UVECT(X):= UNITVECTOR(X)
 161
 162 COVECT(X):= COLUMNVECTOR(X)
 163
 164 GSCHMIT(X):= GRAMSCHMIDT(X)
 165
 166 EIVALS(MAT):= EIGENVALUES(MAT)
 167
 168 EIVECTS(MAT):= EIGENVECTORS(MAT)
 169
 170 UEIVECTS(MAT):= UNITEIGENVECTORS(MAT)
 171
 172 SIMTRAN(MAT):= SIMILARITYTRANSFORM(MAT)
 173
 174                 Well, I guess this is the end...  Have fun with the EIGEN
 175         package.  I hope it will give you useful results.  If you run into a
 176         bug please let me know...
 177         ( I do not think there is any, but nevertheless... )
 178
 179