;;; *** NAMING CONVENTION ***
;;;
;;;   LINEAR1.LISP
;;;     first attempt at linear algebra, so no uniform naming scheme.
;;;
;;;   LINEAR2.C
;;;      fn_ab - where fn is the function name, and a & b are one letter
;;;      abbreviations representing the argument types, ranging over:
;;;
;;;        s = scalar
;;;        v = vector
;;;	   m = 2d-matrix
;;;	   x = vector or matrix (any dimensionality)
;;;
;;;      So, for example, we have the following:
;;;
;;;        add_xs      ===> [vector or matrix] + scalar
;;;	   multiply_vv ===> vector * vector (pairwise multiplication)
;;;        multiply_mm ===> matrix * matrix (pairwise multiplication)
;;;
;;;      Higher-level multiplications are specified by "dot":
;;;
;;;        dot_vv ===> dot-product(vector,vector)
;;;	   dot_mm ===> matrix-product(matrix,matrix)
;;;
;;;      Unfortunately, there are two higher-level multiplications for two
;;;      vectors:  dot-product & outer-product.  Thus, the outer product is
;;;
;;;        outer_vv ===> outer-product(vector,vector)
;;;
;;;   LINEAR2.LISP
;;;     This file is simply the lisp counterpart to the foreign functions of
;;;     linear2.c, so the naming convention is very similar.  C functions are
;;;     designated in lisp by an "&", and the words like "add" in C are
;;;     replaced by a "+".  So, for example, we have the following:
;;;
;;;        &+xs    ===> [vector or matrix] + scalar
;;;	   &*vv    ===> vector * vector (pairwise multiplication)
;;;        &*mm    ===> matrix * matrix (pairwise multiplication)
;;;        &.vv    ===> dot-product(vector,vector)
;;;	   &.mm    ===> matrix-product(matrix,matrix)
;;;        &outer  ===> outer-product(vector,vector)
;;;        &copy.x ===> copy [vector or matrix]
;;;
;;;     Note that in some cases (like "&outer") the "vv" is dropped because
;;;     outer products apply only to two vectors -- we skipped the generalized
;;;     outer product in this version.
;;;
;;;   MATH.LISP
;;;     This file is a set of macros that serve as an interface to either
;;;     library. Thus the user should never have to call any function in
;;;     linear1.lisp or linear2.lisp -- instead he should just use the
;;;     appropriate macro in this file.  So we have:
;;;
;;;        +xs    ===> [vector or matrix] + scalar
;;;	   *vv    ===> vector * vector (pairwise multiplication)
;;;        *mm    ===> matrix * matrix (pairwise multiplication)
;;;        .vv    ===> dot-product(vector,vector)
;;;	   .mm    ===> matrix-product(matrix,matrix)
;;;        outer  ===> outer-product(vector,vector)
;;;        copy.x ===> copy [vector or matrix]
;;;
;;;     Finally in this file we have two functions (NOT MACROS) that can be
;;;     used to do any type of multiplication/addition/dot.  It is provided for
;;;     the user's convenience when working at the lisp top level.  They should
;;;     be avoided in actual code, since the macros won't be expanded, and this
;;;     will slow things down at run time.
;;;
;;;        (%* a b) ===> multiplication
;;;        (%+ a b) ===> addition
;;;        (%. a b) ===> a dot function...  one of [.mm .vv .mv .vm]
