PLEASE NOTE : This is the documentation for the avs module executable
matrix_algebra, which contains the following modules:

	mcovar
        meigen
	minfo
	minvert
	mlde
	mlse
	mlud
	mmult
	msvd
	mtrans

Any mention of xvimage is actually a "field 2D".  Also, the INPUTs and
OUTPUTs, which are mapped to avs parameters, inputs, and outputs, are for the
khoros library routine.
*********************************************************************************

Documentation for avs module mcovar
	

INPUT
     image          pointer to xvimage structure to be processed

OUTPUT
     covimage       points to the result image.  The data storage
                    type is FLOAT and the image (actually matrix)
                    is square symmetric and positive definate.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     mcovar computes the  maximum  likelihood  estimate  of  the
     covariance  matrix describing the distribution of the vector
     data in the input image. The result is returned as a  single
     band image containing the covariance matrix.

     The input image must be of type FLOAT or  BYTE.  The  output
     image  is  of  type  float,  and is a square matrix with the
     number of columns equal to the number of bands in the  input
     image.

     Note that the argument covimage is a pointer to  an  xvimage
     pointer;  the  covariance  image  is attached to the pointer
     indicate by covimage so it is best to be sure that there  is
     no  image  or memory attached to this pointer before calling
     mcovar or that memory will be lost.

SEE ALSO
     mcovar(1), intro(3), vipl(3), verror(3), vutils(3)


RESTRICTIONS
     mcovar works only on images of type FLOAT or BYTE.

AUTHOR
     Scott Wilson


COPYRIGHT
     Copyright  1991,  University  of  New  Mexico.   All  rights
     reserved.

********************************************************************************

Documentation for avs module meigen


INPUT
     image          pointer to VIFF  structure  containing  image
                    data to be processed.

     out_option     specifies what output is desired.  if zero is
                    selected,  no  output  is  desired.   if 1 is
                    selected,  then  the  eigenvalues  only   are
                    desired.  2 is used for eigenvectors only.  3
                    for both eigenvalues and eigenvectors.

     arith_type     type of arithmetic  to  be  used  on  complex
                    data.   0  specifies  scalar arithmetic and 1
                    specifies vector arithmetic.

OUTPUT
     image          pointer to viff structure containing an array
                    of eigenvectors.

     values         pointer to viff structure containing  a  tri-
                    angular matrix of eigenvalues.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     computes the eigenvectors and eigenvalues of a real or  com-
     plex square matrix.

     The input matrices are expected to be n by n, where n is any
     non zero, positive integer.  One matrix is allowed per band.
     The output consists of two sets of information,  the  eigen-
     vectors,  and the eigenvalues.  These are placed in separate
     files. If the Eigenvalues are output to a  file,  then  they
     will  be  output  as a diagonal matrix.  If the Eigenvectors
     are output, they will be output as a single matrix  consist-
     ing  of  column  eigenvectors.  The  eigenvector  in a given
     column corresponds to the eigenvalue in that same column.

SEE ALSO
     meigen(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module minfo


INPUT
     image          an image containg one or more  matrices  (one
                    per band).

OUTPUT
     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     obtain information about a matrix.  The  information  output
     includes  the  matrix' dimensions, an estimate of its condi-
     tion, its  determinant  if  it  is  square,  and  its  norm,
     "Euclidean norm", and 1-norm.

     The condition of the matrix is determined by calculating the
     ratio  of  the  largest  and smallest singular values of the
     matrix.

     The norm is defined as the largest  singular  value  of  the
     matrix.   The  1-norm  and  Euclidean  norm  are obtained by
     selecting the max of the norms of the column  vectors.   The
     vector norm for the 1-norm is defined as the sum of the ele-
     ments of the vector.  For the  Euclidean  norm,  the  vector
     norm is defined as the square root of the sum of the squares
     of the elements of the vector  (i.e.  the  n-space  distance
     from the origin).

SEE ALSO
     minfo(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Jeremy Worley

COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module minvert


INPUT
     image          an  image  containing  one  or  more   square
                    matrices (one per band) of any data type.

OUTPUT
     iamge          double or double complex image containing the
                    inverses of the input image's matrices.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     computes the inverse of a real or complex matrix by generat-
     ing  the  row  equivelant  lower and upper triangular matrix
     factors and estimating its condition.  If the  condition  is
     greater than zero, then the LU factorization is used to com-
     pute the inverse.
     This routine can take in a matrix of any data type and  will
     perform the inverse in double precision.  The output is dou-
     ble or double complex.

SEE ALSO
     minvert(1), intro(3), vipl(3), verror(3), vutils(3)


RESTRICTIONS
     the input matrix must be square

AUTHOR
     Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation fro avs module mlde


INPUT
     t0             initial time value for the solution.

     tf             final time value for the solution

     h              time step to be used to progress from  t0  to
                    tf.

     image          real or complex coefficient matrix.

     bimage         real or complex vector  containing  the  con-
                    stant driving functions of the system.

     ivimage        real or complex vector containing the initial
                    values of the system.

OUTPUT
     image          complex vector  containing  solution  to  the
                    differential  equations.  Solution  is inter-
                    leaved. i.e., if matrix has four  rows,  then
                    solution  will  have  five  elements per row.
                    The first element is the time, the  remaining
                    elements  are  the solutions to the system at
                    various that time step.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     solves a system of constant coefficient linear ordinay  dif-
     ferential  equations  with  constant  driving functions.  As
     input, it takes a matrix that represents the constant  coef-
     ficients,  a vector that contains the constant driving func-
     tions and a vector that  contains  the  initial  conditions.
     With these inputs, the system is defined by the equation:

             x' = Ax + b

     where x',x, and b are n-vectors and A is an  n  x  m  matrix
     such that m is less than or equal to n.

     If the constant driving function vector (b) or  the  initial
     condition  vector is not specified, then they will be set to
     zero.  The coefficient matrix is a required argument.

     mlde will output data in the variable 'solution'.  solution
     will  contains  the  time data for one time step followed by
     the data for each of the xs  in  order.   That  is  followed
     immediately  by  the  next time step in the same order.  For
     example, given a second order system,  the  first  two  time
     steps might look like:

             solution[0] = <time step 0>
             solution[1] = <x1 data at time 0>
             solution[2] = <x2 data at time 0>
             solution[3] = <time step 1>
             solution[4] = <x1 data at time 1>
             solution[5] = <x2 data at time 1>


     mlde solves the  system  of  linear  ordinary  differential
     equations by using the Classic 4th order Runge-Kutta method.
     This method uses the equations

             k1 = h*f'(xn,yn)
             k2 = h*f'(xn + h/2, yn + k1/2)
             k3 = h*f'(xn + h/2, yn + k2/2)
             k4 = h*f'(xn + h, yn + k3)

             y(n+1) = yn + k1/6 + k2/3 + k3/3 + k4/6

     where yn = y(n) and xn = x(n), to progress from xn to xn+h.

SEE ALSO
     mlde(1), intro(3), vipl(3), verror(3), vutils(3)


RESTRICTIONS
AUTHOR
     Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module mlse


INPUT
     image          real or complex coefficient image.

     bimage         real or complex b-vector image.

OUTPUT
     image          complex vector image containing  solution  to
                    simultaneous equations.

     Return Value:  1 on success, 0 on failure.

DESCRIPTION
     solves a system of linear silseaneous equations by  gaussian
     elimination.  the input consists of a real or complex matrix
     A and a real or complex column vector b.  It solves the sys-
     tem

             A*x = b

     If the A matrix is singular or near  singular,  then  the  x
     vector  will  not be generated, and an error message will be
     generated.

SEE ALSO
     mlse(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Jeremy Worley, Salah Al-Daragmi, Johnny Pino, Matt Lawrence,
     Ken Downs

COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module mlud


INPUT
     image          real or complex matrix.

OUTPUT
     image          real or complex matrix containing  the  lower
                    triangular  of  the  LU  decomposition of the
                    input matrix.

     uimage         real or complex matrix containing  the  upper
                    triangular  of  the  LU  decomposition of the
                    input matrix.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     computes the LU decomposition of a matrix by gaussian elimi-
     nation.   If  A is the input matrix, this program will solve
     the system L*U = A for the L and U matrices.  U is an  upper
     triangular matrix, and L "nearly" lower diagonal.

SEE ALSO
     mlud(1), intro(3), vipl(3), verror(3), vutils(3)


RESTRICTIONS
     the input matrix must be square

AUTHOR
     Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module mmult


INPUT
     image1         the first matrix in multiplication sequence

     image2         the  second  matrix  in  the   multiplication
                    sequence

OUTPUT
     image1         holds the result of image1*image2, the dimen-
                    sions should be rows1*cols2

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     mmult 
       	This routine multiplies two matricies.  The  matricies
     can  be  either  real  or  complex.   To be able to multiply
     matricies, the second matrix should have the same number  of
     rows as the first matrix has columns.

SEE ALSO
     mmult(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Matthew Lawrence, Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module msvd


INPUT
     image          image which contains one or more matrices  of
                    arbitrary dimension that will be decomposed.

OUTPUT
     image          double or double  complex  matrix  containing
                    the  U part of the decomposition of the input
                    matrix.

     simage         double or double  complex  matrix  containing
                    the S part of the decomposition of the of the
                    input matrix.

     vimage         double or double  complex  matrix  containing
                    the V part of the decomposition of the of the
                    input matrix.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     computes the singular value decomposition  of  a  matrix  by
     gaussian  elimination.   If A is the input matrix, this pro-
     gram will solve the system A = U*S*V' for the U and  V  uni-
     tary  matrices  and  S, a non-negative diagonal matrix, with
     values in descending order.

     This decomposition method is particularly useful for  linear
     least  squares problems and for decomposition of singular or
     ill-conditioned matrices.

     The S matrix has the same dimensions as A, U has both dimen-
     sions  equal to A's row dimension, and V has the same dimen-
     sions as A's column dimension.

SEE ALSO
     msvd(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************

Documentation for avs module mtrans


INPUT
     image          an image containg one or more  matrices  (one
                    per band).

     conjugate      1-> make conjugate 0-> dont make conjugate

OUTPUT
     image          double or double complex image containing the
                    transposes of the input image's matrices.

     Return Value:  1 on success, 0 on failure.


DESCRIPTION
     mtrans transposes  the  matrices  contained  in  the  input
     image.   If  the  input  image is complex, then the user can
     select whether to generate the conjugate  transpose  or  the
     pure transpose.

     The output image will be of type double or double complex.

SEE ALSO
     mtrans(1), intro(3), vipl(3), verror(3), vutils(3)


AUTHOR
     Matthew Lawrence, Jeremy Worley


COPYRIGHT
     Copyright  1992,  University  of  New  Mexico.   All  rights
     reserved.

*********************************************************************************
