PDP-10.its/doc/share/eigen.usage

              
                 This is the file  EIGEN USAGE DSK:SHARE; .

       The EIGEN package is described in this file.  The source code 
is in the file EIGEN > DSK:SHARE; and the fastload file is 
EIGEN FASL DSK;SHARE; .  (You can load this one using MACSYMA's LOADFILE 
command, i.e. LOADFILE(EIGEN,FASL,DSK,SHARE); .  If you access the FASL 
file via the functions EIGENVALUES or EIGENVECTORS, the FASL file will 
autoload.)  The DEMO file is EIGEN DEMO DSK:SHARE; .  You can BATCH or DEMO 
this file, i.e. BATCH(EIGEN,DEMO,DSK,SHARE); or DEMO(EIGEN,DEMO,DSK,SHARE); .
Note that in the DEMO mode you should hit the space key at each step...

       The new EIGEN package is written by Yekta G"ursel (YEKTA@MIT-MC) and
is faster and more memory efficient than the old EIGEN package.  It also is 
able to handle multiple eigenvalues and the eigenvectors corresponding
to those eigenvalues.  It will work with any square matrix ( not necessarily
symmetric or hermitian ) and will tell whether the matrix is diagonalizable.
The calculated eigenvectors and the unit eigenvectors of the matrix are the
RIGHT eigenvectors and the RIGHT unit eigenvectors respectively.
( You should be aware of the fact that this program uses the MACSYMA functions
SOLVE and ALGSYS and if SOLVE can not find the roots of the characteristic
polynomial of the matrix or if it generates a rather messy solution the
EIGEN package may not produce any useful results.  More info on this will be 
given in the description of the commands...  This package is DESIGNED to try
to get the EXACT solutions to the eigenvalue and eigenvector problems.  If the
matrices you have contain FLOATING point numbers, it may not be able to solve
your problem.  You should use the IMSL eigenvalue and eigenvector package for
numerical matrices with floating point numbers.  These excellent routines will
find the APPROXIMATE solutions for numerical matrices with floating point 
numbers.  See MACSYMA Manual Version 10, Volume 2, Page V2-4-78.)
	
	If MODULUS is not false, i.e. MODULUS:7, then EIGENVALUES will 
automatically call, EIGENFINITEFIELD, to give the eigenvalues of your
matrix over the finite field. EIGENFINITEFIELD calls FACTOR. This capability
gives exact answers for matrices over finite field. This was written by 
Nicholas C. Strauss (NCS@MIT-MC).

	Another command of interest is JORDANFORM. For algebraically closed
fields, for example the complex numbers, this will always return a matrix
which is the Jordan canonical form of the input matrix. For non-algebraically
closed fields, a matrix will be returned only in the event that all eigenvalues
are in the field.

	Otherwise, a list of lists similar to the EIGENVALUES list will be
returned. The first entry is a list of eigenvalues together with a list which
contains the information on the number and type of Jordan block for each
eigenvalue. the second entry is the statement "Field Not Algebraically Closed."
For example, [[1,[0,1,2]], ... ] states that 1 is an eigenvalue with one
2x2 Jordan block, and two 3x3 Jordan blocks. The list paired with the 
eigenvalue lists the Jordan blocks of that eigenvalue in ascending order.
The example [[5,[2]],...], states that the eigenvalue 5 has two 1x1 Jordan
blocks. Thus [[1,[1]],[1,[1]]] denotes the 2x2 Identity matrix.

	The Jordan form for real symmetric matrices is diagonal.
In general, the Jordan form is the similar matrix closest to diagonal form.
This was written by ncs.

        Description of the functions :

CONJUGATE(X) returns the complex conjugate of its argument.
	( Note that %I's in the expressions should be explicit, since there is
	no complex variable declaration in MACSYMA at the present time.  This
	is true for all the functions in this package...)


INNERPRODUCT(X,Y) takes two LISTS of equal length as its arguments and
	returns their inner ( scalar ) product defined by
	(Complex Conjugate of X).Y ( The "dot" operation is the same
	as the usual one defined for vectors. ) .


UNITVECTOR(X) takes a LIST as its argument and returns a  unit list.
	( i.e. a list with unit magnitude. )


COLUMNVECTOR(X) takes a LIST as its argument and returns a column vector the
	components of which are the elements of the list.  The first element is
	the first component,...etc...( This is useful if you want to use parts 
	of the outputs of the functions in this package in matrix calculations.
        ..)


GRAMSCHMIDT(X) takes a LIST of lists the sublists of which are of
	equal length and not necessarily orthogonal ( with respect to the
	innerproduct defined above ) as its argument and returns a similar
	list each sublist of which is orthogonal to  all others.
	( Returned results may contain integers that are factored.
	This is due to the fact that the MACSYMA function FACTOR is 
	used to simplify each substage of the Gram-Schmidt algorithm.
	This prevents the expressions from getting very messy and
	helps to reduce the sizes of the numbers that are produced
	along the way. )


EIGENVALUES(MAT) takes a MATRIX as its argument and returns a list of
	lists the first sublist of which is the list of eigenvalues of
	the matrix and the other sublist of which is the list of the
	multiplicities of the eigenvalues in the corresponding order.
	{ The MACSYMA function SOLVE is used here to find the roots of
	the characteristic polynomial of the matrix.  Sometimes SOLVE
	may not be able to find the roots of the polynomial;in that
	case nothing in this package except CONJUGATE, INNERPRODUCT,
	UNITVECTOR, COLUMNVECTOR and GRAMSCHMIDT will work unless
	you know the eigenvalues.
	In some cases SOLVE may generate very messy eigenvalues.  You may
	want to simplify the answers yourself before you go on.  There
	are provisions for this and they will be explained below.
	( This usually happens when SOLVE returns a not-so-obviously
	real expression for an eigenvalue which is supposed to be real...)}


EIGENVECTORS(MAT) takes a MATRIX as its argument and returns a list of
	lists the first sublist of which is the output of the EIGENVALUES 
	command and the other sublists of which are the eigenvectors
	of the matrix corresponding to those eigenvalues respectively.
	The flags that affect this function are :

	NONDIAGONALIZABLE[FALSE] will be set to TRUE or FALSE depending 
	on whether the matrix is nondiagonalizable or diagonalizable after
	an EIGENVECTORS command is executed.

	HERMITIANMATRIX[FALSE] If set to TRUE will cause the degenerate
	eigenvectors of the hermitian matrix to be orthogonalized using
	the Gram-Schmidt algorithm.

	KNOWNEIGVALS[FALSE] If set to TRUE the EIGEN package will assume
	the eigenvalues of the matrix are known to the user and stored
	under the global name LISTEIGVALS.  LISTEIGVALS should be set to
	a list similar to the output of the EIGENVALUES command.
	( The MACSYMA function ALGSYS is used here to solve for the 
        eigenvectors. Sometimes if the eigenvalues are messy, ALGSYS may
	not be able to produce a solution.  In that case you are advised
	to try to simplify the eigenvalues by first finding them using
	EIGENVALUES command and then using whatever marvelous tricks you
	might have to reduce them to something simpler.  You can then use 
	the KNOWNEIGVALS flag to proceed further. )



UNITEIGENVECTORS(MAT) takes a MATRIX as its argument and returns a list of
	lists the first sublist of which is the output of the EIGENVALUES
	command and the other sublists of which are the unit eigenvectors
	of the matrix corresponding to those eigenvalues respectively.
	The flags mentioned in the description of the EIGENVECTORS command
	have the same effects in this one as well.  In addition there is one
	more flag which may be useful :

	KNOWNEIGVECTS[FALSE] If set to TRUE the EIGEN package will assume that
	the eigenvectors of the matrix are known to the user and are stored
	under the global name LISTEIGVECTS.  LISTEIGVECTS should be set to
	a list similar to the output of the EIGENVECTORS command.
	( If KNOWNEIGVECTS is set to TRUE and the list of eigenvectors is
	given the setting of the flag NONDIAGONALIZABLE may not be correct.
	If that is the case please set it to the correct value.  The author
	assumes that the user knows what he is doing and will not try to 
	diagonalize a matrix the eigenvectors of which do not span the
	vector space of the appropriate dimension...)


SIMILARITYTRANSFORM(MAT) takes a MATRIX as its argument and returns a list
	which is the output of the UNITEIGENVECTORS command.  In addition if
	the flag NONDIAGONALIZABLE is FALSE two global matrices LEFTMATRIX
	and RIGHTMATRIX will be generated.  These matrices have the  property
	that LEFTMATRIX.MAT.RIGHTMATRIX is a  diagonal matrix with the
	eigenvalues of MAT on the diagonal.  If NONDIAGONALIZABLE
	is TRUE these two matrices will not be generated.
	If the flag HERMITIANMATRIX is TRUE then LEFTMATRIX is the
	complex conjugate of the transpose of  RIGHTMATRIX.  Otherwise
	LEFTMATRIX is the inverse of RIGHTMATRIX.  RIGHTMATRIX
	is the matrix the columns of which are the unit eigenvectors of MAT.
	The other flags have the same effects since SIMILARITYTRANSFORM
	calls the other functions in the package in order to be able to
	form RIGHTMATRIX...


		Finally, for some of you who may think that the names of the 
	functions are too long, I also made shorter names...( In the following
	list " := "  means  "is equivalent to" ...). Note that using these may 
	make your code pretty unreadable, you'll save 50% in typing though.

CONJ(X):= CONJUGATE(X)

INPROD(X,Y):= INNERPRODUCT(X,Y)

UVECT(X):= UNITVECTOR(X)

COVECT(X):= COLUMNVECTOR(X)

GSCHMIT(X):= GRAMSCHMIDT(X)

EIVALS(MAT):= EIGENVALUES(MAT)

EIVECTS(MAT):= EIGENVECTORS(MAT)

UEIVECTS(MAT):= UNITEIGENVECTORS(MAT)

SIMTRAN(MAT):= SIMILARITYTRANSFORM(MAT)

		Well, I guess this is the end...  Have fun with the EIGEN
	package.  I hope it will give you useful results.  If you run into a 
	bug please let me know...
	( I do not think there is any, but nevertheless... )


	        Here is the beginning of Eigenfinite field and Jordanform.
	I hope it will give you useful and fascinating results.
				--ncs.

EIGENFINITE(MAT) By brute force plugging in of every member of the reduced
	modulus p, p prime, eigenfinite finds the roots of the characteristic
	equation generated from CHARPOLY. This is here only in the event
	of error checking. MODULUS flag must be set.

EIGENFINITEFIELD(MAT) Using FACTOR, eigenfinitefield finds the roots of the
	characteristic equation generated from CHARPOLY. If entries are
	in CRE form, eigenfinitefield, TOTALDISREP's them into general form.
	MODULUS flag must be set.

JORDANBLOCK(X,MAT) X is an eigenvalue of matrix MAT. JORDANBLOCK will return
	a list which contains all the Jordan block information for the 
	eigenvalue X. For example, [0,1,2,3] states that there is one 2x2
	Jordan block, two 3x3 Jordan blocks, three 4x4 Jordan blocks for
	the given eigenvalue. JORDANBLOCK calls PRANK.

PRETTYJORDAN(LIST,MAT) This constructs the Jordan matrix from the
	information given by JORDANFORM.

JORDANFORM(MAT) This first calls EIGENVALUES, then JORDANBLOCK for each
	eigenvalue, finally returning a matrix constructed by PRETTYJORDAN.

JRANK(MAT,LAMBDA) Since the system RANK has zero equivalence problems,
	JRANK is RANK with a user given lambda simplifier. For example,
	RANK gives the wrong answer for the matrix 
	[sin(x),1-cos(x)],[cos(x)+1,sin(x)]. But by giving as argument,
	lambda([x],fullratsimp(trigreduce(x))) to JRANK the proper answer,
	one will be given. A global variable R is left loose by JRANK.
	So this program should not be called. Call PRANK instead.

PRANK(MAT) This program wraps a block around JRANK, so that there are
	no loose global variables. The flag RANKPRO will normally
	be set false and FULLRATSIMP will be used to determine zero
	equivalence. If RANKPRO is set to a lambda expression then 
	that lambda will be used to simplify for zero equivalence.


Any comments, criticisms, or bugs should be addressed to ncs @ mc.